Tutorial: Generar nota de débito (Manual)

¡Hola! Te voy a explicar paso a paso cómo generar una nota de débito electrónica en modo manual usando nuestra API. En este flujo no usás un carrito existente — enviás todos los datos del cliente, ítems y documento asociado en una sola llamada.

Entorno

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

¿Qué vamos a hacer?

Consultar el timbrado (autorización de la SET)
Identificar el cliente (usar un cliente ya existente en el sistema)
Preparar los ítems (mercaderías y/o servicios con precios)
Definir el documento asociado (electrónico o impreso)
Emitir la nota con la API
Consultar el estado del documento electrónico

Endpoint: POST /simplificado/notas/debito/manual

Paso 1: Consultar el timbrado

El timbrado es la autorización que te da la SET para emitir documentos electrónicos.

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 consultá Obtener lista de timbrados.

Paso 2: Identificar el cliente

En el flujo manual necesitás el cliente_id (UUID del cliente ya registrado en el sistema). Si no lo tenés, podés buscarlo por nombre, documento o RUC.

Para más información consultá Obtener lista de clientes.

Paso 3: Preparar los ítems

Los ítems referencian mercaderías o servicios ya registrados en el sistema mediante su UUID (mercaderia_id o servicio_id). Podés enviar solo mercaderías, solo servicios o ambos.

Campo	Requerido	Descripción
`mercaderia_id`	Condicional	UUID de la mercadería. Requerido si no se envía `servicio_id`.
`servicio_id`	Condicional	UUID del servicio. Requerido si no se envía `mercaderia_id`.
`cantidad`	Sí	Cantidad a debitar.
`precio_unitario`	Sí	Objeto con montos por IVA (`0`, `5`, `10`).
`precio_unitario_original`	No	Precio original del ítem.

Paso 4: Definir el documento asociado

La nota de débito manual siempre requiere un documento asociado — puede ser electrónico (CDC) o impreso (factura física).

`documentos_asociados`

Campo	Tipo	Requerido	Descripción
`tipo_documento_asociado`	number	Sí	`1` = electrónico, `2` = impreso.
`electronico`	object	Condicional	Requerido si `tipo_documento_asociado = 1`. Contiene el `cdc`.
`impreso`	object	Condicional	Requerido si `tipo_documento_asociado = 2`. Datos del comprobante físico.

`electronico` (si `tipo_documento_asociado = 1`)

Campo	Tipo	Requerido	Descripción
`cdc`	string	Sí	CDC del documento electrónico original (44 caracteres).

`impreso` (si `tipo_documento_asociado = 2`)

Campo	Tipo	Requerido	Descripción
`numero_timbrado_documento_asociado`	string	Sí	Timbrado del comprobante físico original.
`numero_establecimiento_documento_asociado`	string	Sí	Establecimiento (3 dígitos).
`punto_expedicion_documento_asociado`	string	Sí	Punto de expedición (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í	Tipo de documento impreso. `1` = Factura.

Paso 5: Emitir la nota de débito manual

Campos de `nota_debito`

Campo	Tipo	Requerido	Descripción
`cliente_id`	uuid	Sí	UUID del cliente registrado en el sistema.
`motivo_codigo`	number	Sí	Código del motivo (ver tabla abajo).
`numero_timbrado`	string	Sí	Número de timbrado vigente.
`numero_establecimiento`	string	Sí	Establecimiento (3 dígitos).
`punto_expedicion`	string	Sí	Punto de expedición (3 dígitos).
`total`	number	Sí	Total de la nota. Debe coincidir con la suma de los ítems.
`moneda`	string	No	Código ISO de moneda (`PYG`, `USD`, etc.). Default `PYG`.
`cotizacion`	number	No	Cotización respecto al guaraní. Default `1`.

Códigos de motivo

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

Ejemplo con documento electrónico asociado

curl -X POST "https://api.guarani.app/simplificado/notas/debito/manual" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "jsonDE": false,
    "nota_debito": {
      "cliente_id": "1981e7a1-0e65-4b58-b625-150f4b771d89",
      "motivo_codigo": 6,
      "numero_timbrado": "12345678",
      "numero_establecimiento": "001",
      "punto_expedicion": "001",
      "total": 100000,
      "moneda": "PYG",
      "cotizacion": 1
    },
    "documentos_asociados": {
      "tipo_documento_asociado": 1,
      "electronico": {
        "cdc": "01801580404001001000001212025111112609055674"
      }
    },
    "items": [
      {
        "mercaderia_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "cantidad": 1,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        },
        "precio_unitario_original": 100000
      }
    ]
  }' | jq

Ejemplo con documento impreso asociado

curl -X POST "https://api.guarani.app/simplificado/notas/debito/manual" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "jsonDE": false,
    "nota_debito": {
      "cliente_id": "1981e7a1-0e65-4b58-b625-150f4b771d89",
      "motivo_codigo": 6,
      "numero_timbrado": "12345678",
      "numero_establecimiento": "001",
      "punto_expedicion": "001",
      "total": 100000,
      "moneda": "PYG",
      "cotizacion": 1
    },
    "documentos_asociados": {
      "tipo_documento_asociado": 2,
      "impreso": {
        "numero_timbrado_documento_asociado": "12345678",
        "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
      }
    },
    "items": [
      {
        "mercaderia_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "cantidad": 1,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        },
        "precio_unitario_original": 100000
      }
    ]
  }' | jq

Nota: Asegurate de reemplazar <access_token> con un token JWT válido.

Ejemplo de respuesta

{
  "success": true,
  "codigo": "200",
  "message": "Operación realizada correctamente.",
  "data": {
    "numero_timbrado": "12345678",
    "numero_documento": "001-001-0000015",
    "serie": "AA",
    "cdc": "06801580404001001000001512025111112609055674",
    "estado_sifen": {
      "estado": "Aprobado",
      "mensaje": "Autorización del DE satisfactoria"
    },
    "xml": "https://api.guarani.app/sifen/xml/06801580404001001000001512025111112609055674",
    "qr": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=06801580404001001000001512025111112609055674"
  }
}

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

Paso 6: 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

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": "Motivo del rechazo"
  }
}

Resumen del flujo

Consultás el timbrado para obtener numero_timbrado, numero_establecimiento y punto_expedicion.
Identificás el cliente_id del cliente en el sistema.
Preparás los ítems con mercaderia_id o servicio_id, cantidad y precio.
Definís el documento asociado (electrónico con CDC, o impreso con datos del comprobante).
Enviás todo junto a POST /simplificado/notas/debito/manual.
Consultás el estado con GET /sifen/consultas/estado/cdc/{cdc}.