Tutorial: Generar nota de crédito (descuento)

¡Hola! En esta guía te explico paso a paso cómo emitir una nota de crédito electrónica para aplicar un descuento usando nuestra API. No te preocupes si no sos experto en programación, el objetivo es que entiendas qué datos necesitas, cómo prepararlos y cuál es el flujo completo.

Entorno

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

¿Qué vamos a hacer?

Para generar una nota de crédito electrónica necesitás:

Consultar el timbrado (autorización de la SET).
Identificar el carrito (la factura original) al que aplicarás el descuento.
Definir el descuento a acreditar, discriminado por tipo de IVA.
Emitir la nota con la API.
Consultar el estado del documento electrónico.

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 base de la nota de crédito

Identificar al carrito

Campo	Descripción	Cómo obtenerlo
`carrito_id`	UUID del carrito receptor de la nota.	Obtener carrito por ID o CDC

Definir el motivo

Campo	Descripción	Referencia
`motivo_descripcion`	Texto entre 6 y 30 caracteres explicando el motivo.	Texto libre

Sugerencia: Se recomienda usar “DESCUENTO CONCEDIDO AL CLIENTE” como motivo, aunque podés usar cualquier texto que describa el descuento, siempre que tenga entre 6 y 30 caracteres.

Definir el descuento aplicado

La API recibe un objeto descuento con los importes a acreditar discriminados por tipo de IVA (IVA 0%, IVA 5% y IVA 10%):

Campo	Descripción
`0`	Descuento aplicado a items con IVA de tipo Exento.
`5`	Descuento aplicado a items con IVA de tipo Gravado al 5%.
`10`	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, puede ser que en la factura tiene un item con IVA parcialmente gravado, en ese caso el descuento se aplicará sobre los 2 tipos de IVA.

⚠️ El total del descuento ("0" + "5" + "10") debe coincidir 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.

Paso 3: Obtener el carrito por CDC

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

Nota: Este paso es opcional pero recomendado para conseguir las informaciones del carrito original facturado.

Revisá el ejemplo de respuesta en Obtener carrito por ID o CDC.

Nota: Reemplazá {cdc} y <access_token> por los valores correspondientes.

Paso 4: Crear la nota de crédito electrónica por descuento

¿Qué debe contener el payload?

jsonDE: setealo en true si querés que el servicio te devuelva también el XML en formato JSON (por defecto es false).
nota_credito.carrito_id: carrito original facturado.
nota_credito.motivo_descripcion: motivo del descuento.
nota_credito.numero_timbrado, numero_establecimiento, punto_expedicion: datos vigentes del timbrado cargado en el sistema.
nota_credito.total: total a acreditar (suma de los importes del objeto descuento).
descuento: objeto con los importes del descuento agrupados por tipo de IVA.

Ejemplo de solicitud

curl -X POST 'https://api.guarani.app/simplificado/notas/credito/descuento' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: Bearer <access_token>' \
  -d '{
    "jsonDE": false,
    "nota_credito": {
        "carrito_id":"ejemplo-uuid-carrito-123",
        "motivo_descripcion": "DESCUENTO CONCEDIDO AL CLIENTE",
        "numero_timbrado": "12345678",
        "numero_establecimiento": "001",
        "punto_expedicion": "001",
        "total": 1000
    },
    "descuento": {
        "0": 1000,
        "5": 0,
        "10": 0
    }
  }' | jq

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

Ejemplo de respuesta

{
  "success": true,
  "codigo": "200",
  "message": "Operación realizada correctamente.",
  "data": {
    "numero_timbrado": "12345678",
    "numero_documento": "001-002-0000001",
    "serie": "AA",
    "cdc": "01234567890123456789012345678901234567890123",
    "estado_sifen": {
      "estado": "Pendiente",
      "mensaje": "Pendiente"
    },
    "xml": "https://api.guarani.app/sifen/xml/01234567890123456789012345678901234567890123",
    "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"
  }
}

El objeto data contiene la información básica del documento electrónico generado.

Descripción de campos de respuesta

Campos del objeto `data`

Campo	Descripción
`numero_timbrado`	Número del timbrado utilizado para emitir la nota de crédito.
`numero_documento`	Número del documento electrónico en formato `{establecimiento}-{punto_expedicion}-{numero}`.
`serie`	Serie del timbrado (normalmente “AA”).
`cdc`	Código de Control (CDC) generado por SIFEN. Identificador único del documento electrónico.
`estado_sifen`	Objeto con el estado de la nota en SIFEN.
`estado_sifen.estado`	Estado del documento (“Pendiente”, “Aprobado” o “Rechazado”).
`estado_sifen.mensaje`	Mensaje descriptivo del estado.
`xml`	URL del archivo XML firmado del documento electrónico.
`qr`	URL del código QR para consulta en Ekuatia (SIFEN).
`jsonDE`	(Opcional) XML del documento en formato JSON. Solo se incluye si `jsonDE: true` en la solicitud.

Paso 5: Consultar el estado del documento electrónico

Después de emitir la nota, esperá unos minutos y consultá el estado en SIFEN:

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

Ejemplo de respuesta aprobada

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

Ejemplo de respuesta rechazada

{
  "success": false,
  "codigo": "400",
  "mensaje": "Error al consultar el CDC.",
  "error": {
    "estado": "Rechazado",
    "mensaje": "Motivo del rechazo comunicado por SIFEN."
  }
}

Resumen del flujo

Consultás el timbrado para obtener numero_timbrado, numero_establecimiento y punto_expedicion.
Preparás los datos base: carrito, motivo y montos de descuento.
Obtenés (opcional) el carrito por CDC para verificar la factura original.
Enviás POST /simplificado/notas/credito/descuento con el payload correspondiente.
Consultás el estado del documento electrónico con GET /sifen/consultas/estado/cdc/{cdc}.

¡Listo! Así emitís una nota de crédito electrónica por descuento con nuestra API.