Tutorial: Generar nota de débito

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

1. Consultar el timbrado (autorización de la SET)
2. Identificar el carrito (datos de la factura original)
3. Definir el motivo (por qué se emite la nota)
4. Crear la nota con la API
5. 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 débito:

• 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 débito

Identificar el carrito

Campo	Descripción	Cómo obtenerlo
carrito_id	UUID del carrito al que aplica la nota.	Obtener carrito por ID o CDC

Definir el motivo de la nota

Código	Descripción
1	Devolución y ajuste de precios
2	Devolución
3	Descuento
4	Bonificación
5	Crédito incobrable
6	Recupero de costo
7	Recupero de gasto
8	Ajuste de precio

---

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, podés consultar Obtener carrito por ID o CDC.

Nota: Asegurate 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 débito electrónica

¿Qué debe contener el payload?

• jsonDE: true para devolver el XML en formato JSON (false por defecto).
• nota_debito.carrito_id: el carrito facturado del que se origina la nota (se reutilizan cliente, moneda y cotización del carrito).
• nota_debito.motivo_codigo: código del motivo de la nota (ver tabla del Paso 2).
• nota_debito.numero_timbrado, numero_establecimiento, punto_expedicion: datos vigentes del timbrado con el que emitirás la nota.
• nota_debito.total: suma total a debitar; debe coincidir con la suma de los ítems enviados.
• items: arreglo de ítems del carrito, cada uno con:
  • carrito_item_id: el ID del ítem tal como fue facturado.
  • precio_unitario: objeto con los importes a debitar discriminados por tipo de IVA (0, 5, 10).

⚠️ 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/debito" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "jsonDE": false,
    "nota_debito": {
      "carrito_id": "1981e7a1-0e65-4b58-b625-150f4b771d89",
      "motivo_codigo": 6,
      "numero_timbrado": "12345678",
      "numero_establecimiento": "001",
      "punto_expedicion": "001",
      "total": 10300
    },
    "items": [
      {
        "carrito_item_id": "c027cbf2-cd46-4f40-bb3f-1d21fbbe3d38",
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 10300
        }
      }
    ]
  }' | jq

Nota: Asegurate 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": "12345678",
    "numero_documento": "001-001-0000012",
    "serie": "AA",
    "cdc": "06801580404001001000001212025111112609055674",
    "estado_sifen": {
      "estado": "Aprobado",
      "mensaje": "Autorización del DE satisfactoria"
    },
    "xml": "https://api.guarani.app/sifen/xml/06801580404001001000001212025111112609055674",
    "qr": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=06801580404001001000001212025111112609055674"
  }
}

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

---

Paso 5: Consultar el estado del 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: Reemplazá {cdc} por el CDC del documento emitido y <access_token> con un token JWT válido.

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

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