KilaSifen Docs

Estados y reintentos

Interpretá el resultado fiscal sin duplicar documentos.

Cada documento tiene dos estados: el fiscal (internal_status del documento) y el de su job de emisión (status del job, con el detalle en error_snapshot). GET /v1/emitters/{emitter_id}/documents/{document_id} devuelve los dos (ver Consultas y artefactos).

Estados del documento

Los estados terminales (approved, approved_with_observation, rejected, failed, cancelled e inutilized) sólo cambian por los caminos de la columna «Qué sigue».

EstadoSignificadoQué sigue
queuedEn cola y sin nada aprobado en SIFEN: todavía no salió, el request no llegó a SIFEN o SIFEN respondió 0420 a la consulta del CDC.El próximo intento arma y firma el DE o, si ya está firmado, reenvía el mismo DE. Si el job ya terminó, hace falta reintentar el job o inutilizar el número. Si el intento ni siquiera arranca, ver abajo.
submittingEl XML firmado y el request exacto están guardados y el worker los está enviando.El mismo intento registra la respuesta. Si el worker se cae, queda así (ver abajo).
submittedEstado heredado: SIFEN recibió el request sin un resultado clasificable.El próximo intento consulta el CDC.
retry_pendingResultado incierto: timeout, conexión cortada, SOAP Fault, respuesta ilegible o sin dEstRes reconocible, rechazo 1001/1002 por confirmar o consulta del CDC fallida.El próximo intento consulta el CDC.
reconciliation_requiredSe agotaron los intentos automáticos sin saber qué tiene SIFEN para el CDC.Reintentar el job o POST .../reconcile vuelven a consultar.
approvedTerminal. DTE aprobado.Sólo puede pasar a cancelled.
approved_with_observationTerminal. DTE aprobado con observación: la única de un DE en el MT v150 es 1005, transmisión extemporánea (con posible sanción). Es un DTE válido.Sólo puede pasar a cancelled.
rejectedTerminal. SIFEN rechazó el DE.Definitivo, salvo 0161/0162 y un 0160 sin detalle, que KilaSifen reenvía. Si no se reenvía, el número se inutiliza.
failedTerminal. No se pudo armar o firmar (validación local); nunca llegó a SIFEN.Reintentar el job lo vuelve a preparar una vez corregida la causa; si no, el número se inutiliza.
cancelledTerminal y definitivo: SIFEN registró su cancelación.Nada.
inutilizedTerminal y definitivo: su número se inutilizó con un evento aprobado.Nada.

Las reglas del KuDE, la cancelación y la inutilización nombran también processing entre los estados pendientes del documento: es un estado heredado que ningún flujo actual le asigna a un documento. El processing que vas a ver es el del job.

La cancelación y la inutilización están en Cancelación e inutilización. Los webhooks document.* que publica el worker se describen en Webhooks.

Estados del job

EstadoSignificado
queuedEspera que un worker lo tome (también después de reintentar el job).
processingUn worker está ejecutando un intento.
retry_scheduledHay otro intento programado para scheduled_at.
succeededTerminado: el documento quedó aprobado, o SIFEN ya lo tenía cancelado.
failedSin más intentos automáticos; el motivo está en error_snapshot.category.

attempts cuenta cada intento, sea un envío o una consulta del CDC. Hay hasta cinco intentos automáticos, con esperas de 30 s, 2 min, 10 min y 30 min (unos 43 minutos en total): una caída de SIFEN más larga deja el job failed. Pasados los cinco, cada reintento del job ejecuta un solo intento: si ese intento consulta el CDC y SIFEN responde 0420, el reenvío necesita otro reintento.

Reintentar un job

POST /v1/emitters/{emitter_id}/jobs/{job_id}/retry

Requiere fiscal:write. Vuelve a encolar un job de documento, evento o webhook del emisor que no terminó bien: failed, trabado en queued o processing, o con un reintento programado que no querés esperar. Es lo mismo que hace un operador desde la consola de administración (/admin).

  • Responde 200 con el job en queued.
  • Un job succeeded responde 409 jobs.retry_not_allowed, y uno de un emisor desactivado, 409 emitters.inactive.
  • También responde 409 jobs.retry_not_allowed el job de un documento que ya no admite intentos: aprobado, cancelado, inutilizado o rechazado en firme por SIFEN. El job queda como estaba, con su error_snapshot.
  • Un emisor o un job que no son tuyos responden 404.

Reintentar no duplica el documento. Si el DE pudo llegar a SIFEN, el intento consulta el CDC antes de decidir y sólo reenvía el mismo DE firmado, con el mismo CDC. Tampoco corren dos intentos a la vez:

  • si el job sigue corriendo, vale lo que decida esa corrida; si termina en failed, podés volver a pedirlo;
  • si su worker se cayó, el job vuelve a correr cuando la cola da por muerta esa corrida, en unos minutos.

Usalo para destrabar un documento (ver Si el worker se cae) o después de corregir la causa de un failed, por ejemplo cargando el timbrado. No lo pongas en un bucle automático: un rechazo definitivo o un failed por la fecha de emisión no se arreglan reintentando.

Categorías de error_snapshot

error_snapshot trae category, message y, cuando hay un código de SIFEN, code.

categoryDocumentoQué pasa
transportretry_pendingEl envío o la consulta del CDC fallaron sin saber si llegaron; el próximo intento consulta.
transport_not_sentqueuedEl request no salió; se reenvía el mismo DE firmado.
sifen_unclassifiedretry_pendingSIFEN respondió sin un dEstRes reconocible; se consulta el CDC.
duplicate_reconciliationretry_pendingRechazo con 1001/1002; se consulta el CDC antes de creerlo.
reconciliation_pendingretry_pendingLa consulta respondió otro código (por ejemplo 0421); se vuelve a consultar.
resubmissionqueuedLa consulta respondió 0420; se reenvía el mismo DE firmado.
retryable_server_errorrejectedRechazo 0161/0162, o 0160 sin detalle; se reenvía el mismo DE firmado.
emitter_busysin cambioOtra operación retuvo el emisor; el intento no se consumió y se reprograma 30 s después.
sifen_rejectionrejectedRechazo definitivo.
fiscal_validationfailed o pendienteValidación local antes de firmar (documento failed), o una consulta del CDC rechazada por configuración antes de salir: en ese caso el documento sigue pendiente y reintentar el job vuelve a consultar una vez corregida.
retry_exhaustedqueued o rejectedSe agotaron los intentos sin un DTE aprobado (0420, request que no salió, 0161/0162 o 0160 sin detalle); reintentar el job reenvía el mismo DE firmado.
reconciliation_requiredreconciliation_requiredSe agotaron los intentos sin conocer el resultado.
concurrent_updateterminalOtra operación cerró el documento mientras el intento esperaba a SIFEN.

Cómo se lee la respuesta de SIFEN

KilaSifen decide por dEstRes, comparado sin tildes ni mayúsculas: «Aprobado» es approved, «Aprobado con observación» es approved_with_observation y «Rechazado» es rejected. Se acepta dEstRes tanto en rProtDe (como dice el XSD) como dentro de gResProc (como muestra el Manual Técnico). Sin dEstRes solo el código 0260 prueba una aprobación; cualquier otra respuesta queda retry_pending y se consulta el CDC. Un código distinto de 0260 nunca alcanza para dar por rechazado un documento.

Con la aprobación se guardan el número de transacción (dProtAut), todos los mensajes (gResProc) y la hora de aprobación (dFecProc), desde la que corre el plazo de cancelación. La API de documentos todavía no los expone como campos propios: están en sifen_response_raw, la respuesta de SIFEN tal cual llegó.

Si la aprobación se conoce por consulta del CDC, siConsDE no trae dEstRes ni dFecProc:

  • el documento queda approved aunque SIFEN lo haya aprobado con observación: KilaSifen no inventa un 1005 que SIFEN no informó;
  • el plazo de cancelación se cuenta desde la mayor de dFecFirma y la creación del documento, así que KilaSifen puede rechazar una cancelación algo antes que SIFEN;
  • el dProtAut viene en la respuesta de la consulta (sifen_protocol) y queda en last_query_response_raw.

Regla ante incertidumbre

Antes de llamar a SIFEN, KilaSifen guarda y confirma en la base el CDC, el XML firmado y el request exacto que va a viajar (con su dId real), y deja el documento en submitting. Ante timeout, conexión cortada, SOAP Fault o respuesta ilegible, el documento pasa a retry_pending y el intento siguiente consulta el documento por CDC (siConsDE):

  • 0422: el CDC ya es un DTE. El documento queda approved (o cancelled si SIFEN tiene una cancelación registrada) y nunca se vuelve a enviar.
  • 0420: SIFEN no tiene un DTE aprobado con ese CDC («no existe o no está aprobado»). El documento vuelve a queued y el intento siguiente reenvía el mismo DE firmado (mismo CDC, misma firma, misma dFecFirma) dentro de un rEnviDe nuevo con un dId nuevo. El reenvío lo pide la Guía de Mejores Prácticas de la DNIT (oct-2024, p. 12), y el Decreto 872/2023 (Art. 29) y el Manual Técnico (§6.5) permiten reutilizar el CDC de un DE que SIFEN no aprobó. La Guía pide comprobar antes que ningún lote en proceso contenga ese CDC: KilaSifen nunca envía lotes.
  • Cualquier otro código (por ejemplo 0421) es un error de la consulta: se vuelve a consultar.

Conservar la firma original es una decisión de KilaSifen: si un reenvío tiene que firmarse de nuevo es NO DETERMINADO en la norma. Como las 72 h corren desde esa dFecFirma, un reenvío que sale pasadas las 72 h se aprueba con observación 1005 (MT v150 §12.4, val. 6).

Si la consulta misma falla por transporte, el documento sigue retry_pending y se vuelve a consultar. Si se rechaza antes de salir por configuración (por ejemplo, el ambiente del emisor no coincide con el del despliegue), el documento sigue pendiente y el job queda failed (fiscal_validation).

Si al quinto intento el resultado sigue sin conocerse, el documento pasa a reconciliation_required. Si SIFEN respondió 0420 en el último intento, el documento queda queued y el job failed (retry_exhausted): reintentar el job lo reenvía.

El ERP no debe crear una segunda intención para «destrabar» un documento: la plataforma ya reenvía el mismo DE cuando SIFEN lo permite.

Si el worker se cae

Si el worker se cae durante el envío, el documento queda en submitting y el job en processing, y nada los retoma de forma automática. Si SIFEN ya lo aprobó, POST .../reconcile lo cierra (consulta 0422: approved y job succeeded). Con 0420 la reconciliación no toca un documento submitting: hace falta reintentar el job, y ese intento consulta el CDC antes de decidir.

Rechazos que se confirman o se reenvían

CódigoQué hace KilaSifen
1001, 1002 (CDC o documento duplicado)Solo saltan si otro documento ya está autorizado. Si cualquier mensaje del rechazo trae uno de esos códigos, el documento queda retry_pending y se consulta el CDC: con 0422 queda approved; con 0420 el rechazo se vuelve definitivo, con el primer error que informó SIFEN.
0161, 0162 (servidor de SIFEN sin respuesta o paralizado, en cualquier mensaje del rechazo)El documento queda rejected con el error del job retryable_server_error y el mismo DE firmado se reenvía con espera creciente, dentro de los cinco intentos. Al agotarlos (retry_exhausted), reintentar el job lo vuelve a enviar. Que estos códigos se puedan reenviar es una interpretación de KilaSifen: la norma no lo determina.
0160 sin detalle (el único código del rechazo, sin detalle de validación, como «XML Mal Formado.»)Igual que 0161/0162: el mismo DE firmado se reenvía dentro de los cinco intentos. El ambiente de pruebas de SIFEN respondió así a pedidos válidos que pasaron segundos después. Un 0160 con detalle («XML malformado: [El valor del elemento: …]») es un error de los datos y es definitivo.
Cualquier otroRechazo definitivo (job failed, sifen_rejection), con el primer error que informó SIFEN. KilaSifen no corrige ni reenvía un DE rechazado: corregí los datos y creá un documento nuevo, que recibe otro número y otro CDC. Como el CDC cambia, inutilizá el número rechazado (MT v150 §11.1.1; Decreto 872/2023 Art. 29). El Decreto también permite, si ya se configuró el hecho generador del impuesto, corregir el DE y reenviarlo con el mismo CDC mientras su estructura de datos no cambie; KilaSifen no ofrece ese camino.

Un rechazo 0161/0162, o 0160 sin detalle, no es definitivo

Igual se publica document.rejected, y si el reenvío se aprueba llega después document.approved. Ni el webhook ni el documento traen la marca de reenvío, y sifen_result_code es el primer mensaje de SIFEN, que puede no ser 0161/0162. Antes de reemitir o inutilizar un rejected, mirá su job: con retryable_server_error (job retry_scheduled) KilaSifen lo va a reenviar, y con retry_exhausted reintentar el job también puede reenviarlo. Un rechazo definitivo tiene la categoría sifen_rejection.

Avisos de plazo

Al terminar cada intento sobre un documento pendiente (o rechazado con 0161/0162 o 0160 sin detalle, y por reenviar) que ya tiene XML firmado, el job agrega a error_snapshot la lista deadline_alerts si corresponde algún aviso:

AvisoCuándo
late_transmission_soonFaltan menos de 24 h para las 72 h desde dFecFirma.
late_transmissionPasaron las 72 h: si se aprueba, será con la observación 1005 (transmisión extemporánea, con posible sanción).
emission_rejection_soonFaltan menos de 24 h para las 720 h desde dFeEmiDE.
emission_rejectionPasaron las 720 h: SIFEN lo rechaza con 1150.

La lista es una foto del momento en que terminó el intento: no se recalcula mientras el job está detenido (failed), reintentar el job la borra y no genera webhooks, sólo el log worker.document_job.transmission_deadline. Para vigilar el plazo por tu cuenta, leé dFecFirma y dFeEmiDE del XML firmado (GET .../xml). Las 24 h de anticipación son una elección de KilaSifen, no de la norma.

Las 72 h son la regla general: la DNIT puede fijar plazos menores, e incluso aprobación previa, según el perfil del facturador (Decreto 872/2023 Art. 27; MT v150 §6.2). Un DE rechazado por extemporáneo, con más de 720 h, sólo se normaliza con un trámite administrativo (MT v150 §6.2.1).

El MT v150 (§6.2.1) también considera extemporánea la transmisión de un DE emitido más de 120 h antes (y hasta 720 h). KilaSifen lo avisa sólo al crear el documento, en fiscal_warnings (documents.transmission.emission_far_from_now), no en deadline_alerts. El MT sólo publica la validación 1005, contada desde dFecFirma, así que qué informa SIFEN en ese caso es NO DETERMINADO.

Cuando el request no salió

Si la falla prueba que nada llegó a SIFEN (DNS, conexión rechazada, timeout al conectar, handshake TLS), no hay incertidumbre: el documento vuelve a queued con su DE firmado, el job queda retry_scheduled con la categoría transport_not_sent y el próximo intento envía el mismo DE firmado en un rEnviDe nuevo, sin volver a firmar. Si SIFEN sigue inalcanzable al agotar los intentos, el job pasa a failed (retry_exhausted) pero el documento sigue queued: reintentar el job vuelve a enviar el mismo XML firmado.

Cuando el intento no arranca

Si cuando el worker toma el job el emisor está inactivo o no tiene un certificado activo, el intento no arranca: documento y job quedan queued, con attempts en 0 y sin error_snapshot, y nada vuelve a despachar el job. Crear el documento no revisa el certificado: antes de emitir, comprobá has_active_certificate en GET /v1/emitters/{emitter_id}/health. Para destrabarlo, activá un certificado y reintentá el job. Un emisor desactivado no se puede reactivar: sus documentos en cola no salen.

Validación local (failed)

Antes de firmar, el worker frena lo que SIFEN rechazaría con seguridad. El documento queda failed y el job failed (fiscal_validation), con el motivo en error_snapshot.message:

MotivoRechazo de SIFEN que evita
Ningún timbrado activo cubre la fecha de emisión.1103, 1104
dFeEmiDE más de 720 h antes o más de 120 h después de ahora, o del 22/11/2018 o antes (documents.fecha_emision.*).1150, 1151, 1156
Certificado no vigente en dFecFirma (documents.certificate.not_valid_at_signature).2450
dFecFirma posterior a ahora (documents.fecha_firma.after_now).1004
Emisor sin CSC o sin csc_id (emitters.csc_required): no se puede calcular el QR.—
XML que no valida contra el XSD, ambiente del emisor distinto del despliegue u otros datos del emisor (ver Emisores).—

La ventana de la fecha de emisión ya se controla al crear el documento (422, ver Facturas); el worker la vuelve a controlar al firmar, porque el tiempo pasa. Reintentar el job vuelve a preparar un documento failed: sirve después de corregir la causa (por ejemplo, cargar el timbrado). Si la causa es la fecha de emisión, reintentar no sirve: inutilizá el número y creá un documento nuevo.

Timbrado

El timbrado se elige al firmar, con la fecha de emisión del documento (dFeEmiDE, hora de Paraguay) y no con la fecha del servidor. Si ningún timbrado activo cubre esa fecha, el documento queda failed antes de salir: SIFEN lo rechazaría con 1103 (emisión anterior al inicio del timbrado) o 1104. Cuándo activar un timbrado nuevo sin dejar documentos en failed está en Certificados y timbrado.

Reconciliación explícita

POST /v1/emitters/{emitter_id}/queries/documents/{document_id}/reconcile
X-API-Key: ...

Requiere el scope fiscal:write. La operación consulta el CDC y aplica la respuesta; nunca envía nada. En resumen:

  • con 0422, un documento que puede estar en SIFEN (incluido uno submitting) queda approved, o cancelled si SIFEN tiene una cancelación registrada, y un documento aprobado con una cancelación registrada pasa a cancelled;
  • con 0420, un documento que puede estar en SIFEN vuelve a queued, o queda rejected si esperaba confirmar un rechazo 1001/1002; un documento submitting no se toca;
  • en los demás casos sólo se registra la consulta.

Las reglas completas, los campos de la respuesta y los errores están en Consultas y artefactos.

La respuesta trae el resultado de la consulta, no el estado que quedó, y la reconciliación no publica webhooks: después leé el documento con GET /v1/emitters/{emitter_id}/documents/{document_id}.

En esta página