Tutorial: Generar nota de crédito (devolución)

¡Hola! Te voy a explicar paso a paso cómo generar una nota de crédito electrónica (devolución) 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 nota de crédito electrónica válida, necesitas completar estos pasos:

Consultar el timbrado (autorización de la SET)
Identificar el carrito (datos de la factura)
Definir el motivo (por qué se emite la nota)
Crear 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 electrónica

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 de la nota

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

Paso 3: Obtener el carrito por CDC (opcional)

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

Para ver un ejemplo de respuesta, podes consultar Obtener carrito por ID o CDC.

Nota: Asegúrate de reemplazar {cdc} con el CDC del carrito y <access_token> con un token JWT válido proporcionado por el equipo Guarani.

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

¿Qué debe contener el payload?

jsonDE: true para devolver el XML en formato JSON (false por defecto).
nota_credito.carrito_id: el carrito facturado del que se origina la nota (se reutilizan cliente, moneda y cotización del carrito).
nota_credito.motivo_descripcion: descripción legible del motivo de la nota.
nota_credito.numero_timbrado, numero_establecimiento, punto_expedicion: datos vigentes del timbrado con el que emitirás la nota.
nota_credito.total: suma total a acreditar; debe coincidir con la suma de los ítems enviados.
items: arreglos de ítems originales del carrito, cada uno con:
- carrito_item_id: el ID del ítem tal como fue facturado.
- cantidad: cantidad a acreditar (no puede superar la facturada).

⚠️ La API valida que los ítems existan en el carrito y que las cantidades no excedan lo facturado. No se pueden mezclar ítems de otros carritos.

Ejemplo de solicitud

curl -X POST "https://api.guarani.app/simplificado/notas/credito/devolucion" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "jsonDE": false,
    "nota_credito": {
      "carrito_id": "1981e7a1-0e65-4b58-b625-150f4b771d89",
      "motivo_descripcion": "Devolución",
      "numero_timbrado": "12345678",
      "numero_establecimiento": "001",
      "punto_expedicion": "001",
      "total": 10300
    },
    "items": [
      {
        "carrito_item_id": "c027cbf2-cd46-4f40-bb3f-1d21fbbe3d38",
        "cantidad": 1
      }
    ]
  }' | jq

Nota: Asegúrate de reemplazar <access_token> con 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": "80158040",
    "numero_documento": "001-002-0000092",
    "serie": "AA",
    "cdc": "05801580404001002000009212025111112609055674",
    "estado_sifen": {
      "estado": "Aprobado",
      "mensaje": "Autorización del DE satisfactoria"
    },
    "xml": "https://api.guarani.app/sifen/xml/05801580404001002000009212025111112609055674",
    "qr": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=05801580404001002000009212025111112609055674&dFeEmiDE=323032352d31312d31315430383a30353a3237&dNumIDRec=5839704&dTotGralOpe=10300.00000000&dTotIVA=636.36363633&cItems=1&DigestValue=3131704755653773764266774f3563486d497931376a76566c614e4b784e55304e44556a744c464739366f3d&IdCSC=0001&cHashQR=8d68084388f3156242198e86af86d6894cb407c7733fea01153af338193b9ede"
  }
}

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"
  }
}

Resumen del flujo

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