API SIFEN: integração de faturamento eletrônico via REST

É um gateway REST de faturamento eletrônico para o Paraguai, pensado para sistemas que não são Odoo: um ERP próprio ou de terceiros, um PDV, um e-commerce, uma cobrança recorrente. Você monta o documento em JSON. O gateway constrói o XML, valida, assina com o seu certificado, envia ao SIFEN, consulta o lote e guarda o XML e o KuDE.

O modelo é assíncrono: toda emissão responde 202 com um identificador, e o resultado é consultado ou chega por webhook. Não há modo síncrono. A latência média é de menos de 2 segundos, então consultar o resultado a cada segundo dá uma experiência quase imediata sem manter uma conexão aberta.

Se você já usa Odoo, provavelmente não precisa da API: o módulo do Odoo usa este mesmo gateway.

Com um POST /v1/sifen/documents. O corpo tem quatro partes: document_kind (factura, autofactura, nota_credito, nota_debito ou remision), invoice_data (o documento: receptor, itens, condição de pagamento), params_data (o emissor e o timbrado) e context (certificado, CSC, ambiente e uma referência sua).

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

O gateway responde na hora, sem esperar a DNIT:

HTTP/1.1 202 Accepted

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

Dois detalhes que evitam problemas:

• Idempotency-Key. Se você tentar de novo após um timeout com a mesma chave, recebe o mesmo request_id e o documento não é emitido duas vezes. A chave é única por tenant. Use, por exemplo, o identificador do documento no seu sistema.
• Certificado. Vai em context como certificate_b64 e certificate_password. As outras formas de entregá-lo estão no manual de integração.

A referência completa de campos por tipo de documento, o código de verificação de webhooks e as opções para o certificado não são publicados aqui: são entregues no manual de integração quando a sua conta é ativada. Peça a sua chave e nós o enviamos.

Cada mudança de estado pode ser entregue com um POST para a sua URL. As entregas vão assinadas com HMAC-SHA256 com o segredo do seu webhook, e levam cabeçalhos para verificar a assinatura, identificar o evento e descartar repetidas. A entrega é pelo menos uma vez, então uma pode se repetir; se o seu endpoint falhar muitas vezes seguidas, o gateway o desativa. Webhooks e consulta convivem: você pode usar os dois. O código de verificação está no manual de integração.

Um documento que a DNIT rejeita não consome cota: ela só é descontada quando o SIFEN aceita o documento.

Os planos são os do ECAV SIFEN, por volume mensal de documentos, e valem para as três vias (API, Odoo e portal). Há mais detalhes em preços.

Uso razoável no Empresa: a partir de 3.000 documentos por mês entramos em contato para garantir o melhor plano.