Tutorial: Generar factura simplificada

¡Hola! Te voy a explicar paso a paso cómo generar una factura simplificada usando nuestra API. No te preocupes si no eres experto en programación, te lo explico de manera sencilla.

Entorno

URL Base: https://api.guarani.app

¿Qué vamos a hacer?

Para crear una factura electrónica simplificada necesitas completar estos pasos:

1. Consultar el timbrado (autorización de la SET)
2. Los datos del cliente (quién compra)
3. Las mercaderias o servicios (qué se vende)
4. La información de la venta (cómo se paga, etc.)
5. Juntar todo y enviar (envío final)

---

Paso 1: Consultar el timbrado

¿Por qué necesitas consultar el timbrado?

El timbrado es la autorización que te da la SET (Secretaría de Estado de Tributación) para emitir facturas electrónicas. Contiene información importante que necesitas incluir en cada factura:

• numero_timbrado: El número de autorización de la SET
• numero_establecimiento: El código de tu local o sucursal
• punto_expedicion: El punto desde donde emitís las facturas

¿Cómo consultar el timbrado?

Hacé una consulta al endpoint de timbrados:

curl -X GET "https://api.guarani.app/timbrados?page=1&limit=100" \
  -H "x-api-key: Bearer <access_token>" \
  -H "Accept: application/json" | jq

Nota: Reemplazá <access_token> con un token JWT válido proporcionado por el equipo Guarani.

Para más información sobre timbrados, consultá la documentación completa en Obtener lista de timbrados.

---

Paso 2: Construir el objeto cliente

⚠️ IMPORTANTE: Pasos preparatorios vs envío final

Este tutorial te explica cómo preparar todos los datos necesarios para luego enviarlos en una sola llamada al endpoint final. Los pasos 1, 2 y 3 son de preparación - no envías nada aún, solo construyes los objetos JSON con los datos correctos.

¿Qué necesitas conseguir primero?

Antes de crear la factura, necesitas algunos datos que son los IDs. Te explico por qué:

Primero, consigue el ID de la ciudad:

• Cada ciudad tiene un ID único
• Necesitas este ID para decirle al sistema dónde vive tu cliente
• Es obligatorio, no puedes saltártelo

¿Cómo lo consigues? Haces una consulta a este enlace: GET /ciudades

curl -X GET 'https://api.guarani.app/ciudades?page=1&limit=100' \
-H 'x-api-key: Bearer {access_token}' \
-H 'Content-Type: application/json'

Nota: Asegúrate de reemplazar {access_token} con un token JWT válido proporcionado por el equipo Guarani.

Para más info sobre cómo conseguir el ID de ciudad puedes (ver ciudades)

¿Por qué es importante?

• Sin este ID, el sistema no sabe dónde está ubicado tu cliente
• Es como si intentaras enviar una carta sin dirección

Segundo, consulta el RUC del cliente:

Antes de emitir la factura, verificá si el RUC del cliente es valido o no y el estado que se encuentra ese RUC si es Activo, Cancelado, etc.

curl -X GET "https://api.guarani.app/consultas/ruc/{ruc}" \
  -H "x-api-key: Bearer <access_token>" \
  -H "Accept: application/json" | jq

Reemplazá {ruc} por el número del RUC con o sin el digito verificador y <access_token> por un token JWT válido. Si querés ver todos los campos disponibles, ejemplos de respuestas y otras consideraciones, revisá la documentación completa en Consultar RUC.

¿Por qué es importante?

• Podes consultar la cedula del cliente y verificar si tiene RUC.
• Si el cliente no tiene RUC, podes emitir la factura con la cedula.
• Si el cliente tiene RUC, podes emitir la factura con el RUC.
• Podes validar si el RUC es valido o no y si es activo, cancelado, etc.

Una vez que tengas el ID de la ciudad, puedes completar los demás campos de tu cliente. Te explico cada campo:

Campo	Requerido	Tipo de dato	Ejemplo
tipo_persona	Sí	number	1 = física, 2 = jurídica (ver tabla de referencias)
tipo_documento	Sí	number	1 = CI, 0 = RUC, etc. (ver tabla de referencias)
documento	Sí	string	El número del documento (ejemplo: “1234567-8”)
nombre	Sí	string	Nombre completo o razón social
nombre_fantasia	No	string	Nombre comercial (no es obligatorio)
nacionalidad	Sí	string	PRY = Paraguay código ISO 3166-1 alpha-3
fecha_nacimiento	Sí	date	Fecha de nacimiento en (formato DD/MM/YYYY)
whatsapp	Sí	string	Número de WhatsApp con código internacional del país (ej: +595xxxxxxxxx)
email	Sí	string	Correo electrónico
direccion	Sí	string	Dirección completa
numero_casa	No	string	Número de casa (no es obligatorio)
barrio	No	string	Barrio o zona (no es obligatorio)
ciudad_id	Sí	uuid	El ID de ciudad que conseguiste antes (ver ciudades)

Ejemplo de cómo queda el objeto cliente

{
  "cliente": {
    "tipo_persona": 1,
    "tipo_documento": 0,
    "documento": "1234567-9",
    "nombre": "CLIENTE EJEMPLO",
    "nombre_fantasia": "",
    "nacionalidad": "PRY",
    "fecha_nacimiento": "11/09/2025",
    "whatsapp": "+595981234567",
    "email": "[email protected]",
    "direccion": "Av. ejemplo",
    "numero_casa": "789",
    "barrio": "Villa Morra",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
  }
}

---

Paso 3: Construir el objeto items con el array de mercaderias y/o servicios

¿Qué necesitas conseguir en este paso?

1. El ID de las unidades de medida (para saber si vendes por unidad, por kilo, por litro, etc.)
2. Definir las clasificaciones de tus mercaderias y/o servicios
3. Configurar los precios según el IVA que aplique

¿Qué puede contener el objeto items?

El objeto items es flexible y puede contener:

• Solo mercaderías (solamente enviar array de mercaderias)
• Solo servicios (solamente enviar array de servicios)
• Mercaderías Y servicios (combinación de ambos)

Primero, consigue el ID de las unidades de medida

Haces una consulta a: GET /unidades-medidas

curl -X GET 'https://api.guarani.app/unidades-medidas?page=1&limit=100' \
-H 'x-api-key: Bearer {access_token}' \
-H 'Content-Type: application/json'

Nota: Asegúrate de reemplazar {access_token} con un token JWT válido proporcionado por el equipo Guarani.

Para más info sobre cómo conseguir el ID de unidad de medida (ver unidades-medidas)

¿Por qué es importante?

• Cada unidad de medida tiene un número único
• Necesitas saber si vendes por unidad, por kilo, por litro, etc.
• Es como especificar en qué “paquete” vendes tu producto

Ahora creamos las mercaderías

Te explico cada campo de manera sencilla:

Campo	Requerido	Tipo de dato	Ejemplo
codigo_interno	Sí	string	Código interno del producto Ver tabla de código interno.
codigo_original	Sí	string	Código interno que usas en tu sistema
codigo_barra	No	string	Código de barras del producto
codigo_fabricante	No	string	Código que te da el fabricante
descripcion	Sí	string	Nombre corto del producto
descripcion_larga	No	string	Descripción detallada (opcional)
observacion	No	string	Notas adicionales (garantía, etc.)
unidad_medida_venta_id	Sí	uuid	El ID de unidad que conseguiste antes (ver unidades-medidas)
marca	No	string	Marca del producto (opcional)
clasificacion	Sí	objeto	Objeto con los campos código y nombre de la clasificación de mercaderias
cantidad	Sí	number	Cuántas unidades vendes
precio_unitario_original	Sí	number	Precio total del producto
precio_unitario	Sí	objeto	Precio desglosado por IVA

clasificacion (objeto)

Campo	Requerido	Tipo de dato	Ejemplo
codigo	Sí	string	Código de la clasificación de mercaderias (ej: “01”, “01.01”, “01.01.001”)
nombre	Sí	string	Nombre de la clasificación de mercaderias (ej: “Electrónica”, “Servicios de Mantenimiento”, etc.)

precio_unitario (objeto)

Campo	Requerido	Tipo de dato	Ejemplo
0	No	number	Precio con IVA 0%
5	No	number	Precio con IVA 5%
10	No	number	Precio con IVA 10%

• Solo mercaderías:

{
  "items": {
    "mercaderias": [
      {
        "codigo_interno": "01-1234567",
        "codigo_original": "PROD001",
        "codigo_barra": "7891234567890",
        "codigo_fabricante": "FAB123",
        "descripcion": "Laptop HP Pavilion",
        "descripcion_larga": "Laptop HP Pavilion con procesador Intel i5, 8GB RAM y 256GB SSD",
        "observacion": "Garantía 2 años",
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "marca": "HP",
        "clasificacion": {
          "codigo": "01",
          "nombre": "Electrónica"
        },
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ]
  }
}

Y también los servicios

Los servicios son similares a las mercaderias, pero con algunos campos diferentes:

Campo	Requerido	Tipo de dato	Ejemplo
codigo_interno	Sí	string	Código interno del servicio Ver tabla de código interno.
descripcion	Sí	string	Nombre corto del servicio
descripcion_larga	No	string	Descripción detallada (opcional)
observacion	No	string	Condiciones del servicio
clasificacion	Sí	objeto	Objeto con los campos código y nombre de la clasificación del servicio (opcional)
unidad_medida_venta_id	Sí	uuid	ID de la unidad de medida (ver unidades-medidas)
cantidad	Sí	number	Cuántos servicios contratas
precio_unitario_original	Sí	number	Precio total del servicio
precio_unitario	Sí	objeto	Precio desglosado por IVA

clasificacion

Campo	Requerido	Tipo de dato	Ejemplo
codigo	Sí	string	Código de la clasificación de servicios (ej: “01”, “01.01”, “01.01.001”)
nombre	Sí	string	Nombre de la clasificación de servicios (ej: “Servicios de Mantenimiento”)

precio_unitario

Campo	Requerido	Tipo de dato	Ejemplo
0	No	number	Precio con IVA 0%
5	No	number	Precio con IVA 5%
10	No	number	Precio con IVA 10%

Ejemplo de cómo quedan los objetos items

• Solo servicios:

{
  "items": {
    "servicios": [
      {
        "codigo_interno": "02-1234567",
        "descripcion": "Mantenimiento de computadoras",
        "descripcion_larga": "Servicio de limpieza, optimización y revisión general del equipo",
        "observacion": "Incluye diagnóstico completo",
        "clasificacion": {
          "codigo": "02",
          "nombre": "Servicios de Mantenimiento"
        },
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ]
  }
}

• Ejemplo de mercaderías y servicios:

{
  "items": {
    "mercaderias": [
      {
        "codigo_interno": "01-1234567",
        "codigo_original": "PROD001",
        "codigo_barra": "7891234567890",
        "codigo_fabricante": "FAB123",
        "descripcion": "Laptop HP Pavilion",
        "descripcion_larga": "Laptop HP Pavilion con procesador Intel i5, 8GB RAM y 256GB SSD",
        "observacion": "Garantía 2 años",
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "marca": "HP",
        "clasificacion": {
          "codigo": "01",
          "nombre": "Electrónica"
        },
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ],
    "servicios": [
      {
        "codigo_interno": "02-1234567",
        "descripcion": "Mantenimiento de computadoras",
        "descripcion_larga": "Servicio de limpieza, optimización y revisión general del equipo",
        "observacion": "Incluye diagnóstico completo",
        "clasificacion": {
          "codigo": "02",
          "nombre": "Servicios de Mantenimiento"
        },
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ]
  }
}

---

Paso 4: Construir el objeto venta

¿ Qué necesitas conseguir en este paso ?

1. Definir si es venta al contado o a crédito
2. Configurar los datos de la transacción

Nota importante: Los datos de timbrado y establecimiento se configuran a nivel de empresa/sistema, no necesitas buscarlos para cada venta individual.

Ahora creamos la información de la venta

El objeto venta contiene los datos específicos de esta transacción. Los datos de configuración (timbrado, establecimiento) ya deben estar configurados en tu cuenta.

venta (objeto)

Campo	Tipo	Requerido	Tamaño	Descripción
numero_timbrado	string	Sí	-	Número de timbrado.
numero_establecimiento	string	Sí	-	Número de establecimiento.
punto_expedicion	string	Sí	-	Punto de expedición.
moneda	string	Sí	-	Moneda.
cotizacion	number	Sí	-	Cotización de la moneda.

condicion_venta Contado

Campo	Tipo	Requerido	Tamaño	Descripción
condicion_venta	number	Sí	1	Condición de venta. (1: Contado, 2: Crédito)
total	number	Sí	-	Total del carrito.
venta_contado	object	Sí	-	Objeto con los datos de la venta en contado.
observacion	string	No	-	Observación de la venta.

venta_contado (objeto)

Campo	Tipo	Requerido	Tamaño	Descripción
monto	number	Sí	-	Monto de la venta en contado.

condicion_venta Credito

Campo	Tipo	Requerido	Tamaño	Descripción
condicion_venta	number	Sí	1	Condición de venta. (1: Contado, 2: Crédito)
total	number	Sí	-	Total del carrito.
venta_credito	object	Sí	-	Objeto con los datos de la venta en crédito.
observacion	string	No	-	Observación de la venta.

venta_credito (objeto)

Campo	Tipo	Requerido	Tamaño	Descripción
entrega_inicial	number	Sí	-	Monto de la entrega inicial.
plazo	number	Sí	-	Plazo de la venta crédito en días.

Ejemplo de venta al contado

{
  "venta": {
    "numero_timbrado": "12345678",
    "numero_establecimiento": "001",
    "punto_expedicion": "001",
    "moneda": "PYG",
    "cotizacion": 1,
    "condicion_venta": 1,
    "total": 100000,
    "venta_contado": {
      "monto": 100000
    },
    "observacion": "Venta realizada en contado"
  }
}

Ejemplo de venta a crédito

{
  "venta": {
    "numero_timbrado": "12345678",
    "numero_establecimiento": "001",
    "punto_expedicion": "001",
    "moneda": "PYG",
    "cotizacion": 1,
    "condicion_venta": 2,
    "total": 100000,
    "venta_credito": {
      "entrega_inicial": 50000,
      "plazo": 30
    },
    "observacion": "Venta realizada a crédito"
  }
}

⚠️ Importante: Solo debes incluir venta_contado O venta_credito, nunca ambos. El campo que incluyas debe coincidir con el valor de condicion_venta.

---

Paso 5: Juntar todo y enviar (ENVÍO FINAL)

🚀 Ahora sí: enviamos todo junto

Una vez que tienes preparados todos los objetos de los pasos anteriores, los juntamos en un solo JSON y lo enviamos al endpoint libre.

ℹ️ El campo jsonDE viene en false por defecto y la API te devuelve solo la estructura JSON. Si lo envías en true, además de crear el carrito, la respuesta incluye el XML generado.

JSON completo de ejemplo

{
  "venta": {
    "numero_timbrado": "12345678",
    "numero_establecimiento": "001",
    "punto_expedicion": "001",
    "moneda": "PYG",
    "cotizacion": 1,
    "condicion_venta": 1,
    "total": 200000,
    "venta_contado": {
      "monto": 200000
    },
    "observacion": "Venta realizada en promoción"
  },
  "cliente": {
    "tipo_persona": 1,
    "tipo_documento": 0,
    "documento": "12345678-9",
    "nombre": "CLIENTE EJEMPLO",
    "nombre_fantasia": "",
    "nacionalidad": "PRY",
    "fecha_nacimiento": "11/09/2025",
    "whatsapp": "+595981234567",
    "email": "[email protected]",
    "direccion": "Av. ejemplo",
    "numero_casa": "789",
    "barrio": "Villa Morra",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
  },
  "items": {
    "mercaderias": [
      {
        "codigo_interno": "01-1234567",
        "codigo_original": "PROD001",
        "codigo_barra": "7891234567890",
        "codigo_fabricante": "FAB123",
        "descripcion": "Laptop HP Pavilion",
        "descripcion_larga": "Laptop HP Pavilion con procesador Intel i5, 8GB RAM y 256GB SSD",
        "observacion": "Garantía 2 años",
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "marca": "HP",
        "clasificacion": {
          "codigo": "01",
          "nombre": "Electrónica"
        },
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ],
    "servicios": [
      {
        "codigo_interno": "02-1234567",
        "descripcion": "Mantenimiento de computadoras",
        "descripcion_larga": "Servicio de limpieza, optimización y revisión general del equipo",
        "observacion": "Incluye diagnóstico completo",
        "clasificacion": {
          "codigo": "02",
          "nombre": "Servicios de Mantenimiento"
        },
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ]
  }
}

Ejemplos de uso con curl

Ejemplo 1: Solo mercaderías

curl -X POST 'https://api.guarani.app/simplificado/carritos' \
-H 'x-api-key: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{
  "jsonDE": false,
  "venta": {
    "numero_timbrado": "12345678",
    "numero_establecimiento": "001",
    "punto_expedicion": "001",
    "moneda": "PYG",
    "cotizacion": 1,
    "condicion_venta": 1,
    "total": 100000,
    "venta_contado": {
      "monto": 100000
    }
  },
  "cliente": {
    "tipo_persona": 1,
    "tipo_documento": 0,
    "documento": "12345678-9",
    "nombre": "CLIENTE EJEMPLO",
    "nacionalidad": "PRY",
    "fecha_nacimiento": "11/09/2025",
    "whatsapp": "+595981234567",
    "email": "[email protected]",
    "direccion": "Av. ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
  },
  "items": {
    "mercaderias": [
      {
        "codigo_interno": "01-1234567",
        "codigo_original": "PROD001",
        "codigo_barra": "7891234567890",
        "codigo_fabricante": "FAB123",
        "descripcion": "Laptop HP Pavilion",
        "descripcion_larga": "Laptop HP Pavilion con procesador Intel i5, 8GB RAM y 256GB SSD",
        "observacion": "Garantía 2 años",
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "marca": "HP",
        "clasificacion": {
          "codigo": "01",
          "nombre": "Electrónica"
        },
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ]
  }
}' | jq

Ejemplo 2: Solo servicios

curl -X POST 'https://api.guarani.app/simplificado/carritos' \
-H 'x-api-key: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{
  "jsonDE": false,
  "venta": {
    "numero_timbrado": "12345678",
    "numero_establecimiento": "001",
    "punto_expedicion": "001",
    "moneda": "PYG",
    "cotizacion": 1,
    "condicion_venta": 1,
    "total": 100000,
    "venta_contado": {
      "monto": 100000
    }
  },
  "cliente": {
    "tipo_persona": 1,
    "tipo_documento": 0,
    "documento": "12345678-9",
    "nombre": "CLIENTE EJEMPLO",
    "nacionalidad": "PRY",
    "fecha_nacimiento": "11/09/2025",
    "whatsapp": "+595981234567",
    "email": "[email protected]",
    "direccion": "Av. ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
  },
  "items": {
    "servicios": [
      {
        "codigo_interno": "02-1234567",
        "descripcion": "Mantenimiento de computadoras",
        "clasificacion": {
          "codigo": "02",
          "nombre": "Servicios de Mantenimiento"
        },
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ]
  }
}' | jq

Ejemplo 3: Mercaderías y servicios (completo)

curl -X POST 'https://api.guarani.app/simplificado/carritos' \
-H 'x-api-key: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{
  "jsonDE": false,
  "venta": {
    "numero_timbrado": "12345678",
    "numero_establecimiento": "001",
    "punto_expedicion": "001",
    "moneda": "PYG",
    "cotizacion": 1,
    "condicion_venta": 1,
    "total": 200000,
    "venta_contado": {
      "monto": 200000
    },
    "observacion": "Venta realizada en promoción"
  },
  "cliente": {
    "tipo_persona": 1,
    "tipo_documento": 0,
    "documento": "12345678-9",
    "nombre": "CLIENTE EJEMPLO",
    "nombre_fantasia": "",
    "nacionalidad": "PRY",
    "fecha_nacimiento": "11/09/2025",
    "whatsapp": "+595981234567",
    "email": "[email protected]",
    "direccion": "Av. ejemplo",
    "numero_casa": "789",
    "barrio": "Villa Morra",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
  },
  "items": {
    "mercaderias": [
      {
        "codigo_interno": "01-1234567",
        "codigo_original": "PROD001",
        "codigo_barra": "7891234567890",
        "codigo_fabricante": "FAB123",
        "descripcion": "Laptop HP Pavilion",
        "descripcion_larga": "Laptop HP Pavilion con procesador Intel i5, 8GB RAM y 256GB SSD",
        "observacion": "Garantía 2 años",
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "marca": "HP",
        "clasificacion": {
          "codigo": "01",
          "nombre": "Electrónica"
        },
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ],
    "servicios": [
      {
        "codigo_interno": "02-1234567",
        "descripcion": "Mantenimiento de computadoras",
        "descripcion_larga": "Servicio de limpieza, optimización y revisión general del equipo",
        "observacion": "Incluye diagnóstico completo",
        "clasificacion": {
          "codigo": "02",
          "nombre": "Servicios de Mantenimiento"
        },
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ]
  }
}' | jq

Nota: Asegúrate de reemplazar {access_token} con un token JWT válido proporcionado por el equipo Guarani.

---

Ejemplo de respuesta del backend

{
  "success": true,
  "codigo": "200",
  "message": "Operación realizada correctamente.",
  "data": {
    "numero_timbrado": "12345678",
    "numero_documento": "001-001-0000001",
    "serie": "AA",
    "cdc": "018015804040010020000182120251028149230824767",
    "estado_sifen": {
      "estado": "Aprobado",
      "mensaje": "Autorización del DE satisfactoria"
    },
    "xml": "https://api.guarani.app/sifen/xml/018015804040010020000182120251028149230824767",
    "qr": "https://ekuatia.set.gov.py/consultas-test/qr?nVersion=150&Id=018015804040010020000182120251028149230824767&dFeEmiDE=323032352d31302d32385430383a31383a3139&dRucRec=362889&dTotGralOpe=200000.00000000&dTotIVA=18181.81818182&cItems=2&DigestValue=724a4b68652f6635616934566442357036797070704b504b66736c514370696f554a2f3374676674484b453d&IdCSC=0001&cHashQR=90832ec96b3a6f8cd667640386206708099adf9af74bdea2116d30099897fecda"
  }
}

---

Una vez emitido el documento electrónico, esperá 10 minutos y luego consulta el estado del documento electrónico.

Ejemplo de consulta de estado de un documento electrónico

curl -X GET "https://api.guarani.app/sifen/consultas/estado/cdc/{cdc}" \
  -H "x-api-key: Bearer <access_token>" \
  -H "Accept: application/json" | jq

Nota: Reemplaza {cdc} por el CDC a consultar y <access_token> con un token JWT válido proporcionado por el equipo Guarani.

Ejemplo de respuesta de estado aprobado

{
  "success": true,
  "codigo": "200",
  "message": "Operación realizada correctamente.",
  "data": {
    "estado": "Aprobado",
    "mensaje": "Aprobado"
  }
}

Ejemplo de respuesta de estado rechazado

{
  "success": false,
  "codigo": "400",
  "mensaje": "Error al consultar el CDC.",
  "error": {
    "estado": "Rechazado",
    "mensaje": "TEST - RUC del receptor inexistente en la base de datos de Marangatu"
  }
}

Ejemplo de respuesta de estado pendiente

{
  "success": true,
  "codigo": "200",
  "message": "Operación realizada correctamente.",
  "data": {
    "estado": "Pendiente",
    "mensaje": "Pendiente"
  }
}

---

Resumen de todo el proceso

Te explico paso a paso lo que acabamos de hacer:

1. Preparación (Conseguir los códigos de referencia)

• ✅ Conseguir ID de ciudad (para el cliente)
• ✅ Conseguir ID de unidad de medida (para mercaderías/servicios)

2. Construcción (Preparar cada objeto JSON)

• ✅ Construir el objeto cliente con datos corregidos
• ✅ Construir el objeto items con mercaderías y/o servicios
• ✅ Construir el objeto venta con condiciones de pago

3. Envío Final (Una sola llamada)

• ✅ Juntar todos los objetos en un solo JSON
• ✅ Enviar todo junto al endpoint /simplificado/carritos

---

¿Dónde encontrar más información?

• Si algo sale mal: (ver Tabla de errores)
• Para consultar datos de referencia: (ver Tablas de referencia)

---

Consejos que te van a ayudar

1. Verifica siempre que los códigos de referencia sean correctos antes de crear la factura
2. Calcula bien los totales y precios
3. Usa solo una condición de venta (contado O crédito, nunca ambas)
4. Revisa el formato de las fechas (DD/MM/YYYY) y teléfonos (+595xxxxxxxxx)
5. Si tienes dudas, revisa la documentación de cada endpoint