API SIFEN: integración de facturación electrónica por REST

Es un gateway REST de facturación electrónica para Paraguay, pensado para sistemas que no son Odoo: un ERP propio o de terceros, un punto de venta, un e-commerce, una facturación recurrente. Vos armás el documento en JSON. El gateway construye el XML, lo valida, lo firma con tu certificado, lo envía a SIFEN, consulta el lote y guarda el XML y el KuDE.

El modelo es asíncrono: toda emisión responde 202 con un identificador, y el resultado se consulta o llega por webhook. No hay modo síncrono. La latencia promedio es de menos de 2 segundos, así que consultar el resultado cada segundo da una experiencia casi inmediata sin sostener una conexión abierta.

Si ya usás Odoo, probablemente no necesites la API: el módulo de Odoo usa este mismo gateway.

Se hace con un POST /v1/sifen/documents. El cuerpo tiene cuatro partes: document_kind (factura, autofactura, nota_credito, nota_debito o remision), invoice_data (el documento: receptor, ítems, condición de pago), params_data (el emisor y el timbrado) y context (certificado, CSC, ambiente y una referencia tuya).

curl -X POST https://sifen.ecav.com.py/v1/sifen/documents \
  -H "Authorization: Bearer sk_test_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: FAC-2026-0001" \
  -d @factura.json

{
  "document_kind": "factura",
  "invoice_data": {
    "establecimiento": "001",
    "punto": "001",
    "tipoTransaccion": 2,
    "tipoImpuesto": 1,
    "moneda": "PYG",
    "condicion": { "tipo": 1, "entregas": [{ "tipo": 1, "monto": 110000 }] },
    "cliente": { "ruc": "5012345-6", "razonSocial": "Cliente SA" },
    "items": [{ "descripcion": "Servicio mensual", "cantidad": 1, "precioUnitario": 110000 }]
  },
  "params_data": { "ruc": "80000000-7", "timbradoNumero": "12345678" },
  "context": {
    "certificate_b64": "<.p12 en base64>",
    "certificate_password": "<contraseña del .p12>",
    "csc": "<CSC>",
    "csc_id": "0001",
    "environment": "test",
    "document_ref": "FAC-2026-0001"
  }
}

El gateway responde de inmediato, sin esperar a la DNIT:

HTTP/1.1 202 Accepted

{
  "request_id": "req-8f3a1c2e9b7d4e60",
  "poll_url": "/v1/sifen/documents/req-8f3a1c2e9b7d4e60",
  "webhook_will_fire": true,
  "processing_delayed": false
}

Dos detalles que ahorran problemas:

• Idempotency-Key. Si reintentás por un timeout con la misma clave, recibís el mismo request_id y el documento no se emite dos veces. La clave es única por tenant. Usá, por ejemplo, el identificador del documento en tu sistema.
• Certificado. Va en context como certificate_b64 y certificate_password. Las demás formas de entregarlo están en el manual de integración.

La referencia completa de campos por tipo de documento, el código de verificación de webhooks y las opciones para el certificado no se publican acá: se entregan en el manual de integración cuando se activa tu cuenta. Pedí tu clave y te lo enviamos.

Cada cambio de estado se puede entregar con un POST a tu URL. Las entregas van firmadas con HMAC-SHA256 con el secreto de tu webhook, y llevan cabeceras para verificar la firma, identificar el evento y descartar repetidas. La entrega es al menos una vez, así que una puede repetirse; si tu endpoint falla muchas veces seguidas, el gateway lo desactiva. Webhooks y consulta conviven: podés usar los dos. El código de verificación está en el manual de integración.

Un documento que la DNIT rechaza no consume cuota: se descuenta solo cuando SIFEN lo acepta.

Los planes son los de ECAV SIFEN, por volumen mensual de comprobantes, y valen para las tres vías (API, Odoo y portal). Hay más detalle en precios.

Uso razonable en Empresa: a partir de 3.000 comprobantes por mes te contactamos para asegurarte el mejor plan.