Documentación API
Integración REST + JSON. Funciona desde cualquier lenguaje en menos de 30 minutos.
Introducción
El middleware expone una API REST que recibe documentos en un modelo canónico, los firma digitalmente, los envía a SIFEN y devuelve el CDC + KuDE listo para compartir con tu cliente.
Autenticación
Toda llamada requiere el header x-api-key. La key la obtenés en el panel del cliente, sección API key.
x-api-key: tk_xxxxxxxxxxxxxxxxxxxxxxxx
Emitir un documento
POST /v1/invoices
Acepta cualquier tipo: Factura, Nota de Crédito, Nota de Débito, Nota de Remisión, Autofactura.
curl -X POST https://api.fenex.com.py/v1/invoices \
-H "Content-Type: application/json" \
-H "x-api-key: tk_xxxxxxxxxxxxxxxxxxxxxxxx" \
-d '{
"claveIdempotencia": "venta-2026-0001",
"tipoDocumento": "FACTURA_ELECTRONICA",
"tipoEmision": "NORMAL",
"tipoTransaccion": "VENTA_MERCADERIA",
"condicionOperacion": "CONTADO",
"moneda": "PYG",
"fechaEmision": "2026-06-10T15:00:00-03:00",
"numeroDocumento": "0000123",
"emisor": {
"ruc": "80012345", "dv": "7",
"razonSocial": "Mi Empresa S.A.",
"establecimiento": "001", "puntoExpedicion": "001",
"timbrado": "12345678"
},
"receptor": {
"tipoIdentificacion": "RUC",
"numeroDocumento": "80098765",
"razonSocial": "Cliente S.A."
},
"items": [{
"codigo": "P001",
"descripcion": "Producto X",
"cantidad": 2,
"precioUnitario": 50000,
"afectacionIva": "GRAVADO",
"tasaIva": 10
}]
}'{
"cdc": "01800123457001001000012322026053018867138884",
"estado": "APROBADO",
"protocolo": "12026000001234567",
"mensaje": "Documento aprobado por SIFEN"
}Webhooks de retorno
Cuando SIFEN aprueba o rechaza un documento, te enviamos un POST firmado a la URL que registres en el portal. Esto evita la doble facturación: tu ERP guarda el CDC y bloquea re-emitir la misma venta.
# El middleware envía este POST a la URL que registres
POST https://tu-erp.com/fe/notificar
X-FE-Event: documento.procesado
X-FE-Signature: sha256=9ae31bf8f63900d792...
X-FE-Attempt: 1
Content-Type: application/json
{
"evento": "documento.procesado",
"payload": {
"cdc": "01800123457001001000012322026053018867138884",
"status": "APROBADO",
"kudeUrl": "https://api.fenex.com.py/v1/invoices/.../kude.pdf"
},
"ts": 1717030200000
}Códigos de error
- 400Datos inválidos en el documento canónico (RUC mal formado, ítems sin tasa, etc).
- 401API key faltante o inválida.
- 409Conflicto: la
claveIdempotenciaya fue usada (no se duplica). - 422SIFEN rechazó el documento (revisar campo
mensaje). - 429Estás emitiendo demasiado rápido — esperá unos segundos.
- 500Error interno: intentá de nuevo. Si persiste, contactá soporte.
Verificación HMAC de webhooks
Cada webhook viene con un header X-FE-Signature de la forma sha256=<hex>. Calcula HMAC-SHA256 del body usando tu secreto para validar antes de procesar.