Inicio rápido
Emití una factura de prueba siguiendo el recorrido mínimo seguro.
Antes de empezar necesitás:
- la URL de una instancia de KilaSifen conectada al ambiente de pruebas de SIFEN. Para probar sin transmitir nada, mirá Sandbox;
- una API key de consumidor con los scopes
tenant:readyfiscal:write, que emite un administrador de la plataforma (ver Autenticación); - un emisor de tu consumidor, con perfil fiscal completo, CSC cargado,
certificado activo y timbrado vigente. Lo da de alta tu ERP con el scope
emitters:createo un administrador (ver Emisores y Certificados y timbrado).
Verificá la API
curl https://TU_API/v1/health
curl https://TU_API/v1/readyhealth confirma que el proceso responde. ready controla la base de datos
y Redis y, en staging y producción, que haya workers en las colas
documents, events y webhooks y que el despachador del outbox esté
activo; si falta algo responde 503. En development y test no controla
workers ni outbox: asegurate de que estén corriendo.
Revisá el emisor
curl https://TU_API/v1/emitters/EMITTER_ID \
-H "X-API-Key: $KILA_API_KEY"
curl https://TU_API/v1/emitters/EMITTER_ID/health \
-H "X-API-Key: $KILA_API_KEY"La clave sólo ve emisores de su consumidor; cualquier otro responde 404.
Antes de emitir comprobá que:
- el emisor tenga
status: activeyfiscal_profile_complete: true. Sin perfil fiscal la factura responde422 emitters.fiscal_profile_required; - el emisor tenga
csc_configured: truey uncsc_id. Sin CSC no se puede calcular el QR y el documento termina enfailedconemitters.csc_required; healthmuestrehas_active_certificateyhas_active_stampingentrue, y uncertificate_valid_untilfuturo (un certificado activo pero vencido también datrue). Sin certificado activo el documento queda enqueuedsin un error visible (ver Estados y reintentos); sin un timbrado vigente en la fecha de emisión termina enfailed.
Emití una factura
curl -X POST https://TU_API/v1/emitters/EMITTER_ID/documents/facturas \
-H "X-API-Key: $KILA_API_KEY" \
-H "Content-Type: application/json" \
--data @factura.json{
"external_id": "venta_1842",
"idempotency_key": "venta_1842_v1",
"factura": {
"establecimiento": "001",
"punto": "001",
"moneda": "PYG",
"cliente": {
"ruc": "88899990-9",
"tipo_contribuyente": 2,
"razon_social": "Cliente de prueba"
},
"items": [
{
"descripcion": "Servicio mensual",
"cantidad": 1,
"precio_unitario": 150000,
"tasa": 10
}
],
"condicion_operacion": {
"tipo": "contado",
"formas_pago": [{ "tipo": "efectivo", "monto": 150000 }]
}
}
}cliente: un receptor contribuyente necesitatipo_contribuyente(1 persona física, 2 persona jurídica) y el RUC con su DV, que se valida por módulo 11. Si falta o no coincide, la respuesta es422condocuments.cliente.tipo_contribuyente_requiredodocuments.cliente.dv_mismatchen el detalle.- El RUC del ejemplo es ficticio (es el receptor del ejemplo de QR del Manual Técnico v150, §13.8.4): pasa la validación local, pero el Manual exige que el RUC del receptor exista y esté activo (validaciones 1306 a 1308). En el ambiente de pruebas usá el RUC de un receptor inscripto.
fecha_emisionno va en el ejemplo: si la omitís, KilaSifen usa la hora de Paraguay al armar el XML. Si la enviás, tiene que estar entre 720 h antes y 120 h después del momento de crear el documento (422 documents.fecha_emision.too_oldotoo_far_ahead), y se vuelve a controlar antes de firmar. Una fecha de más de 120 h atrás se acepta con un aviso enfiscal_warnings: es una transmisión extemporánea (MT v150 §6.2.1), que se aprueba con observación y puede tener sanción.condicion_operaciondeclara cómo se cobró. Si la omitís, la factura se informa al contado con un pago en efectivo por el total; para crédito u otros medios de pago, ver Facturas.codigo_seguridades opcional: si no lo enviás, KilaSifen genera uno aleatorio y lo conserva en los reintentos.
Esperá el estado final
La creación responde 201 con document y job en queued; todavía no
significa aprobación. Consultá el documento, o el job con
GET /v1/emitters/EMITTER_ID/jobs/JOB_ID, hasta que llegue a un estado
terminal. Qué significa cada estado y qué hacer está en
Estados y reintentos.
curl https://TU_API/v1/emitters/EMITTER_ID/documents/DOCUMENT_ID \
-H "X-API-Key: $KILA_API_KEY"En lugar de consultar podés registrar un webhook. Eso
requiere una clave con tenant:write, y la instancia publica los cambios de
estado sólo si el worker corre con KILA_SIFEN_DOCUMENT_PUBLISH_WEBHOOKS=true
(en el código vale false).
Reintentos del ERP
Si tu request inicial pierde la respuesta, reenviá exactamente el mismo
cuerpo y los mismos headers con el mismo idempotency_key: la respuesta es
200 con el mismo documento y job. Si algo difiere, incluido el header
X-Kila-Test-Outcome, la respuesta es
409 documents.idempotency_key_conflict. No inventes una nueva clave: el
mismo external_id con otra clave responde
409 documents.external_id_conflict.
Nombre del emisor en el ambiente de pruebas
Para el ambiente de pruebas, el Manual Técnico v150 pide un texto fijo como
nombre del emisor (dNomEmi, validación 1263) y la Guía de pruebas de la
DNIT (febrero de 2026) pide otro. Cuál acepta hoy el SIFEN de pruebas está
NO DETERMINADO. KilaSifen usa la razón social por defecto; si SIFEN rechaza
con 1263, el operador puede fijar el texto con
KILA_SIFEN_TEST_EMITTER_NAME_LITERAL.