Tutorial: Generar nota de crédito libre (descuento)

¡Hola! Te voy a explicar paso a paso cómo generar una nota de crédito electrónica libre por descuento usando nuestra API. Este flujo es ideal cuando querés emitir una nota de crédito por descuento, porque el endpoint final arma todo en una sola solicitud.

La idea es que primero prepares todos los datos y luego hagas una única llamada a la API.

---

Entorno

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

Necesitás un token válido en el encabezado x-api-key: Bearer <access_token> para todas las llamadas.

---

¿Qué vamos a hacer?

1. Consultar el timbrado (autorización de la SET).
2. Preparar los datos del cliente.
3. Definir el descuento a acreditar, discriminado por tipo de IVA (0%, 5%, 10%).
4. Preparar los datos generales: establecimiento, punto de expedición y motivo.
5. Emitir la nota con la API.
6. Consultar el estado del documento electrónico.

---

Requisitos previos

• Certificado digital cargado en el sistema: Ver como cargar un certificado.
• Timbrado vigente y asociado al establecimiento/punto de expedición.
• Identificadores de ciudad listos.
• Motivo entre 6 y 30 caracteres (motivo_descripcion). Se recomienda usar “DESCUENTO CONCEDIDO AL CLIENTE”.

---

Paso 1: Consultar el timbrado

¿Por qué necesitás consultar el timbrado?

El timbrado es la autorización que te da la SET (Secretaría de Estado de Tributación) para emitir documentos electrónicos. Contiene información importante que necesitás incluir en cada nota de crédito:

• 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 los documentos

¿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: Preparar los datos del cliente

Aunque la API arma todo en una sola solicitud, es buena práctica validar los datos del cliente previamente (o crearlo en el sistema para reutilizarlo).

Obtener ciudad y validar documento

• Ver como obtener la lista de ciudades para encontrar el ciudad_id.
• Ver como validar un RUC para validar RUC o cédula.

Estructura de cliente que vas a enviar dentro de la nota

Campo	Requerido	Descripción
tipo_persona	Sí	Tipo de persona. Ver tabla de tipos de personas
tipo_documento	Sí	Tipo de documento de identidad. Ver tabla de tipos de documentos
documento	Sí	Número de CI o RUC.
nombre	Sí	Nombre completo o razón social.
nombre_fantasia	No	Nombre comercial (si aplica).
nacionalidad	Sí	Código ISO 3166-1 alfa-3 (ej: PRY).
fecha_nacimiento	Sí	Formato DD/MM/YYYY.
whatsapp	Sí	Número en formato internacional.
email	Sí	Correo del cliente.
direccion	Sí	Dirección física.
numero_casa	No	Número de casa.
barrio	No	Barrio/zona.
ciudad_id	Sí	UUID de la ciudad. Ver como obtener la lista de ciudades

---

Paso 3: Definir el descuento aplicado

Para una nota de crédito por descuento, necesitás definir el monto del descuento discriminado por tipo de IVA. La API recibe un objeto descuento con los importes a acreditar.

Campos del objeto descuento

Campo	Tipo	Requerido	Descripción
0	number	Sí	Descuento aplicado a items con IVA de tipo Exento (0%).
5	number	Sí	Descuento aplicado a items con IVA de tipo Gravado al 5%.
10	number	Sí	Descuento aplicado a items con IVA de tipo Gravado al 10%.

Nota: En la factura original debe existir ese tipo de IVA para que se pueda aplicar el descuento. Si la factura tiene un item con IVA parcialmente gravado, el descuento se aplicará sobre los 2 tipos de IVA correspondientes. ⚠️ Importante: El total del descuento (descuento["0"] + descuento["5"] + descuento["10"]) debe coincidir EXACTAMENTE con el campo nota_credito.total. Ejemplo: si querés descontar 1000 en IVA 0%, 1000 en IVA 5% y 1000 en IVA 10%, el total del descuento debe ser 3000.

Ejemplo de objeto descuento

{
  "descuento": {
    "0": 0,
    "5": 0,
    "10": 1000
  }
}

En este ejemplo, se está aplicando un descuento de 1000 guaraníes sobre items con IVA 10%.

---

Paso 4: Definir los campos de la nota de crédito electronica completa

Campos de la nota de crédito electronica completa

nota_credito (objeto)

Campo	Tipo	Requerido	Descripción
moneda	string	Sí	Código ISO de la moneda (PYG, USD, etc.). Debe coincidir con la moneda del documento original.
cotizacion	number	Sí	Cotización respecto al guaraní. Para operaciones en PYG, enviá 1.
cliente	object	Sí	Datos completos del receptor (ver Paso 2).
motivo_descripcion	string	Sí	Motivo comercial entre 6 y 30 caracteres. Se recomienda usar “DESCUENTO CONCEDIDO AL CLIENTE”.
numero_timbrado	string	Sí	Timbrado electrónico activo de tu empresa.
numero_establecimiento	string	Sí	Establecimiento (3 dígitos) asociado al timbrado.
punto_expedicion	string	Sí	Punto de expedición (3 dígitos) desde el cual emitís la nota.
total	number	Sí	Total a acreditar. Debe ser igual a la suma de los importes del objeto descuento (0 + 5 + 10).

Tip: mantené moneda y cotizacion iguales a los de la factura original y asegurate de que total coincida exactamente con la suma del objeto descuento para evitar rechazos.

documentos_asociados (objeto)

Campo	Tipo	Requerido	Descripción
tipo_documento_asociado	number	Sí	Tipo de documento asociado. Ver tabla de tipos de documentos asociados.
impreso	object	Condicional	Se envía cuando tipo = 2. Contiene la información del comprobante físico.
electronico	object	Condicional	Se envía cuando tipo = 1. Incluye el CDC y datos del documento electrónico original. Ver como obtener el CDC.

impreso (requerido si tipo_documento_asociado = 2)

Campo	Tipo	Requerido	Descripción
numero_timbrado_documento_asociado	string	Sí	Timbrado del documento impreso original.
numero_establecimiento_documento_asociado	string	Sí	Establecimiento del documento impreso original (3 dígitos).
punto_expedicion_documento_asociado	string	Sí	Punto de expedición del documento impreso original (3 dígitos).
fecha_emision_documento_asociado	string	Sí	Fecha de emisión en formato DD/MM/YYYY.
numero_documento_asociado	string	Sí	Número del documento (ej.: 0000001).
tipo_documento_impreso	number	Sí	Código SIFEN del tipo de documento. Ver tabla de tipos de documentos

electronico (requerido si tipo_documento_asociado = 1)

Campo	Tipo	Requerido	Descripción
cdc	string	Sí	CDC del documento electrónico original. Ver como obtener el CDC.

descuento (objeto)

Campo	Tipo	Requerido	Descripción
0	number	Sí	Importe del descuento aplicado a items con IVA Exento (0%). Ver Paso 3.
5	number	Sí	Importe del descuento aplicado a items con IVA Gravado al 5%. Ver Paso 3.
10	number	Sí	Importe del descuento aplicado a items con IVA Gravado al 10%. Ver Paso 3.

• El descuento se aplica sobre los tipos de IVA que existan en la factura original.
• La suma de los tres valores (0 + 5 + 10) debe coincidir exactamente con el campo nota_credito.total.

Bandera jsonDE

Campo	Tipo	Requerido	Descripción
jsonDE	boolean	No	Bandera opcional en la raíz del payload. Si la enviás en true, la respuesta incluye el XML transformado a JSON.

Si omitís este campo se asume false.

⚠️ Importante: El campo total debe coincidir EXACTAMENTE con la suma del objeto descuento (descuento["0"] + descuento["5"] + descuento["10"]) o la emisión será rechazada.

---

Paso 5: Enviar todo completo a la API

A continuación tenés un ejemplo completo que crea la nota de crédito por descuento con cliente, descuento discriminado por IVA, motivo y documento asociado en un solo paso.

Ejemplo completo con documento físico asociado:

curl -X POST 'https://api.guarani.app/simplificado/notas/credito/descuento/libre' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: Bearer <access_token>' \
  -d '{
    "jsonDE": false,
    "nota_credito": {
      "moneda": "PYG",
      "cotizacion": 1,
      "cliente": {
        "tipo_persona": 1,
        "tipo_documento": 1,
        "documento": "1234567",
        "nombre": "Cliente de ejemplo",
        "nombre_fantasia": "",
        "nacionalidad": "PRY",
        "fecha_nacimiento": "01/01/1990",
        "whatsapp": "",
        "email": "[email protected]",
        "direccion": "Dirección de ejemplo",
        "numero_casa": "",
        "barrio": "Barrio de ejemplo",
        "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
      },
      "motivo_descripcion": "DESCUENTO CONCEDIDO AL CLIENTE",
      "numero_timbrado": "12345678",
      "numero_establecimiento": "001",
      "punto_expedicion": "001",
      "total": 1000
    },
    "documentos_asociados": {
      "tipo_documento_asociado": 2,
      "impreso": {
        "numero_timbrado_documento_asociado": "12931292",
        "numero_establecimiento_documento_asociado": "001",
        "punto_expedicion_documento_asociado": "001",
        "fecha_emision_documento_asociado": "22/03/2025",
        "numero_documento_asociado": "0000001",
        "tipo_documento_impreso": 1
      }
    },
    "descuento": {
      "0": 0,
      "5": 0,
      "10": 1000
    }
  }' | jq

Ejemplo de respuesta documento impreso

{
  "success": true,
  "codigo": "200",
  "message": "Operación realizada correctamente.",
  "data": {
    "numero_timbrado": "80158040",
    "numero_documento": "001-002-0000128",
    "serie": "AA",
    "cdc": "05801580404001002000012812025111411459731517",
    "estado_sifen": {
      "estado": "Pendiente",
      "mensaje": "Pendiente"
    },
    "xml": "https://api.guarani.app/sifen/xml/05801580404001002000012812025111411459731517",
    "qr": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=05801580404001002000012812025111411459731517&dFeEmiDE=323032352d31312d31345431363a34303a3134&dNumIDRec=6088756&dTotGralOpe=1000.00000000&dTotIVA=0.00000000&cItems=1&DigestValue=6758366c33676b6e55742f71306376315737474e4676664b3166644e4d623148485962565572396b4f76733d&IdCSC=0001&cHashQR=b369a4efb74bac578de13d1d225527182762f365f086dfbec8acea0c14c967f2"
  }
}

Ejemplo completo con documento electrónico asociado:

curl -X POST 'https://api.guarani.app/simplificado/notas/credito/descuento/libre' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: Bearer <access_token>' \
  -d '{
    "jsonDE": false,
    "nota_credito": {
      "moneda": "PYG",
      "cotizacion": 1,
      "cliente": {
        "tipo_persona": 1,
        "tipo_documento": 1,
        "documento": "1234567",
        "nombre": "Cliente de ejemplo",
        "nombre_fantasia": "",
        "nacionalidad": "PRY",
        "fecha_nacimiento": "01/01/1990",
        "whatsapp": "",
        "email": "[email protected]",
        "direccion": "Dirección de ejemplo",
        "numero_casa": "",
        "barrio": "Barrio de ejemplo",
        "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
      },
      "motivo_descripcion": "DESCUENTO CONCEDIDO AL CLIENTE",
      "numero_timbrado": "12345678",
      "numero_establecimiento": "001",
      "punto_expedicion": "001",
      "total": 1000
    },
    "documentos_asociados": {
      "tipo_documento_asociado": 1,
      "electronico": {
        "cdc": "05801580404001002000009212025111112609055674"
      }
    },
    "descuento": {
      "0": 0,
      "5": 0,
      "10": 1000
    }
  }' | jq

Ejemplo de respuesta de documento electrónico

{
  "success": true,
  "codigo": "200",
  "message": "Operación realizada correctamente.",
  "data": {
    "numero_timbrado": "80158040",
    "numero_documento": "001-002-0000129",
    "serie": "AA",
    "cdc": "05801580404001002000012912025111411459731518",
    "estado_sifen": {
      "estado": "Pendiente",
      "mensaje": "Pendiente"
    },
    "xml": "https://api.guarani.app/sifen/xml/05801580404001002000012912025111411459731518",
    "qr": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=05801580404001002000012912025111411459731518&dFeEmiDE=323032352d31312d31345431363a34303a3134&dNumIDRec=6088756&dTotGralOpe=1000.00000000&dTotIVA=0.00000000&cItems=1&DigestValue=6758366c33676b6e55742f71306376315737474e4676664b3166644e4d623148485962565572396b4f76733d&IdCSC=0001&cHashQR=b369a4efb74bac578de13d1d225527182762f365f086dfbec8acea0c14c967f2"
  }
}

---

Paso 6: Consultar el estado del documento electrónico

Esperá unos 10 minutos y consultá:

GET /sifen/consultas/estado/cdc/{cdc}

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.

estado: "Aprobado" confirma que SIFEN aceptó el documento. Si ves Rechazado, revisá el mensaje devuelto para corregirlo y emitir nuevamente.

---

Resumen del flujo

1. Consultás el timbrado para obtener numero_timbrado, numero_establecimiento y punto_expedicion.
2. Preparás cliente, descuento discriminado por tipo de IVA, motivo y documento asociado (si es necesario).
3. Enviás todo completo a la API en un solo paso con POST /simplificado/notas/credito/descuento/libre.
4. Verificás el estado del documento electrónico con GET /sifen/consultas/estado/cdc/{cdc}.