Cancelación, inutilización y nominación
Cancelá DTE, inutilizá numeración y nominá facturas innominadas como procesos durables que podés seguir por API y webhooks.
La v1 cubre tres eventos del emisor: la cancelación de un DTE, la inutilización de numeración y la nominación de una factura emitida a un receptor innominado. Los eventos del receptor (notificación, conformidad, disconformidad, desconocimiento) y el de transporte no están soportados.
Las tres operaciones exigen el scope fiscal:write, un emisor activo
(409 emitters.inactive) y un certificado activo
(409 certificates.active_required). Responden 201 con el event y su
job en cola: el request HTTP no espera a SIFEN.
El sandbox no se aplica a los eventos
X-Kila-Test-Outcome sólo existe en la creación de documentos. La
cancelación, la inutilización y la nominación siempre viajan al SIFEN del
ambiente
configurado, firmadas con el certificado del emisor. Un documento aprobado
por el sandbox nunca existió en SIFEN: no lo canceles,
porque el resultado no está determinado.
Cómo se procesa un evento
La API arma y firma el evento al aceptar el pedido. Su dFecFirma es la hora
del POST, y es la que SIFEN compara con el plazo de cancelación (4009 y
4010, MT v150 §11.6.1). El worker envuelve ese evento en rEnviEventoDe,
verifica la firma, guarda el request exacto (submitting) y recién entonces
lo envía. Cada reintento reenvía el mismo evento firmado.
| Estado del evento | Significado |
|---|---|
queued | En cola, o el intento anterior probó que el request no llegó a SIFEN. |
submitting | El request está guardado y el worker lo está enviando. |
submitted | SIFEN respondió sin código de resultado; se reintenta. |
retry_pending | Resultado incierto (timeout, respuesta ilegible o consulta por CDC fallida); se reintenta. |
approved | SIFEN registró el evento: respondió 0600 («Evento registrado correctamente») o la consulta por CDC muestra la cancelación. |
rejected | Rechazo de SIFEN; sifen_result_code y sifen_result_message dicen por qué. |
failed | El evento no salió: no se pudo preparar (por ejemplo, el ambiente del emisor no coincide con el del despliegue) o se agotaron los intentos sin que el request llegara a SIFEN. |
reconciliation_required | Pudo llegar a SIFEN y no se sabe qué registró (ver abajo). |
Sólo 0600 registra un evento. Cualquier otro código es un rechazo, salvo
los casos que se verifican consultando el CDC (ver
Si la respuesta de SIFEN se pierde).
El job hace hasta 5 intentos en total, con esperas de 30 s, 2 min, 10 min y
30 min entre ellos.
Seguir el evento
GET /v1/emitters/{emitter_id}/events/{event_id}
X-API-Key: ...Esta ruta exige fiscal:write; tenant:read no alcanza. Devuelve el event
(status, sifen_result_code, sifen_result_message, el evento firmado y la
respuesta cruda de SIFEN) y su job (attempts, error_snapshot,
scheduled_at). El job también se lee con
GET /v1/emitters/{emitter_id}/jobs/{job_id}, con tenant:read.
Cuando SIFEN registra el evento se publica el webhook document.cancelled,
numbering.inutilized o document.nominated (ver
Webhooks). Un
evento rejected, failed o reconciliation_required no publica ningún
webhook: consultá el evento.
Cancelar un documento
curl -X POST https://TU_API/v1/emitters/EMITTER_ID/documents/DOCUMENT_ID/cancel \
-H "X-API-Key: $KILA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"motivo":"Error en los datos de la operación"}'motivo lleva de 5 a 500 caracteres, en una sola línea (sin saltos de línea
ni tabulaciones). El documento pasa a cancelled solamente cuando SIFEN
registra el evento. Desde entonces
GET …/kude responde 409 documents.kude_not_available, porque un DTE
cancelado no tiene validez tributaria (Decreto 872/2023, Art. 30). Si
necesitás el KuDE como copia de archivo, descargalo antes de cancelar. El XML
firmado sigue disponible en GET …/xml.
Cuándo corresponde cancelar
La cancelación es para un DTE cuya operación no se concretó: hubo errores en la emisión, la mercadería no se entregó o el servicio no se prestó (MT v150 §11.1.2 y Tabla J; Decreto 872/2023, Art. 30). KilaSifen no puede verificarlo: la responsabilidad es del emisor.
Controles antes de firmar
| Respuesta | Cuándo |
|---|---|
404 documents.not_found | El documento no existe o es de otro emisor. |
409 events.cancel.already_cancelled | El documento ya está cancelado o tiene una cancelación aprobada. |
409 events.cancel.document_not_approved | El documento no tiene CDC o no está approved ni approved_with_observation. |
409 events.cancel.already_pending | Otra cancelación del mismo documento todavía puede registrarse (details.event_ids). |
409 events.cancel.deadline_exceeded | Venció el plazo (ver abajo). |
409 events.cancel.child_dte_not_cancelled | Hay documentos asociados que hay que cancelar antes (details.child_cdcs). |
422 request.validation_failed | motivo tiene menos de 5 o más de 500 caracteres, o trae saltos de línea o tabulaciones. |
Una cancelación a la vez. Una segunda solicitud sería rechazada como
duplicada (4003), así que se bloquea mientras otra cancelación del documento
esté queued, submitting, submitted, retry_pending o
reconciliation_required. También bloquea una cancelación failed que llegó
a guardar su request, porque un intento anterior pudo haber llegado a SIFEN:
para destrabarla, reintentá su job (ver
Estados y reintentos).
Plazo. 48 h para una factura y 168 h para autofactura, nota de crédito,
nota de débito y nota de remisión, contadas desde la aprobación en SIFEN,
dFecProc (MT v150 §6.2.1; RG 23/2019, Art. 22). Si la aprobación se conoció
por consulta, SIFEN no informa la hora, y se toma como cota inferior la más
tardía entre la dFecFirma del DE y la creación del documento. Así el plazo
local termina antes que el de SIFEN, nunca después. El
409 events.cancel.deadline_exceeded trae details.deadline_hours,
details.approved_at, details.approved_at_source y details.remedy.
Vencido el plazo, una factura se anula con una nota de crédito (RG 23/2019,
Art. 22). details.remedy vale nota_credito para cualquier tipo de
documento, pero para una autofactura, nota de crédito, nota de débito o nota
de remisión vencida la normativa no fija el remedio (NO DETERMINADO):
consultá a tu asesor.
Documentos asociados. Un DTE con otros DTE asociados se cancela del último al inicial (MT v150, Tabla J). Bloquean la cancelación los asociados que ya son DTE o que podrían serlo:
- aprobados;
- en envío o pendientes (
processing,submitting,submitted,retry_pending,reconciliation_required); - con su DE firmado y un job activo que los va a enviar (el mismo DE después
de un
0420, un request que no salió o un rechazo0161/0162o0160sin detalle por reenviar).
No bloquean los rechazados, los fallidos, los que están en cola sin armar, los cancelados, los inutilizados ni los que ningún job va a enviar.
KilaSifen sólo ve los documentos de este emisor creados por las rutas tipadas
con un único documento_asociado que apunta al CDC. No ve los asociados
emitidos por otro sistema ni los que lo referencian dentro de una lista de
documento_asociado: cancelalos vos primero. Qué responde SIFEN si quedan
asociados sin cancelar no está determinado.
Si la respuesta de SIFEN se pierde
No existe un servicio para consultar eventos: los eventos de un CDC vuelven en
la consulta del documento (siConsDE, contenedor xContEv). Por eso:
- Después de un intento incierto, una cancelación consulta el CDC antes de
reenviar:
- si la cancelación ya está registrada, el evento queda
approvedsin volver a enviarse; - si SIFEN tiene el DTE sin cancelación, se reenvía el mismo evento firmado;
- si responde
0420(no se sabe si un DTE cancelado responde así), el evento quedareconciliation_requiredsin enviar nada.
- si la cancelación ya está registrada, el evento queda
- Una respuesta
4002,4003,4009o4010puede esconder un registro anterior. Antes de darla por buena se consulta el CDC: si la cancelación figura registrada, el evento quedaapproved. El rechazo sólo se acepta si la consulta muestra el DTE sin cancelación. 4003(«el DTE ya se encuentra con un evento que se está requiriendo nuevamente») nunca se toma como rechazo. Si la consulta no muestra la cancelación, el evento quedareconciliation_requiredy el documento no cambia.- Pasa lo mismo con cualquiera de esos códigos cuando no se puede leer el
contenedor de la consulta (
xContenDE, cuyo formato no está publicado). Antes de un reenvío, en cambio, un contenedor ilegible no frena el envío: decide la respuesta al mismo evento firmado (0600, o uno de esos códigos). - Si el worker se cae durante el envío, el evento queda
submittingy nada lo retoma solo. Un reintento del job no envía nada hasta que pasen 5 minutos desde que se guardó el request, y después sigue estas mismas reglas.
Resolver un evento reconciliation_required. Reintentá su job con
POST /v1/emitters/{emitter_id}/jobs/{job_id}/retry (scope fiscal:write,
ver Estados y reintentos):
hace un único intento más con estas mismas reglas. Para una cancelación,
además:
POST /v1/emitters/{emitter_id}/queries/documents/{document_id}/reconcile
(scope fiscal:write) deja el documento cancelled si xContEv muestra la
cancelación (ver Consultas). El evento
sigue reconciliation_required y no se publica document.cancelled, ni
siquiera cuando un reintento posterior aprueba el evento.
Nominar una factura
Una factura emitida a un receptor innominado (tipo_documento_identidad 5)
puede nombrar después a su receptor con el evento de nominación (NT 14). Es la
salida cuando hace falta una nota de crédito o de débito sobre esa factura: una
nota no puede ser innominada (1331, NT 23) y tiene que nombrar al receptor de
la factura (2441, NT 10) o, si la factura fue nominada, al receptor nominado
(2442, NT 15).
curl -X POST https://TU_API/v1/emitters/EMITTER_ID/documents/DOCUMENT_ID/nominate \
-H "X-API-Key: $KILA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"motivo": "Nominación de la factura a pedido del cliente",
"receptor": {
"ruc": "44444402-5",
"tipo_contribuyente": 2,
"razon_social": "CLIENTE EJEMPLO SA"
}
}'receptor tiene la misma forma que cliente en una factura y las mismas
reglas (Receptor), más tres propias de la
nominación:
- no puede ser innominado (NT 27);
- no puede ser B2G (
tipo_operacion3), ni llevarcompras_publicas; - un contribuyente va con B2B, y un no contribuyente con B2C o B2F (
4475).
Sigue el mismo ciclo que la cancelación: responde 201 con el event y su
job, SIFEN lo registra con 0600 y se publica document.nominated con el
receptor. GET /v1/emitters/{emitter_id}/documents/{document_id} de la
factura muestra la nominación en data.nomination (event_id, status y
receptor): la aprobada o, si no hay, la última pedida. La NT 14 no fija un
plazo para nominar.
La factura no cambia de estado, y su XML firmado sigue diciendo innominado: la nominación es un evento aparte que no lo modifica. El KuDE muestra ese XML. Si el KuDE de una factura nominada debería mostrar al receptor nominado no está determinado.
Controles de la nominación
| Respuesta | Cuándo |
|---|---|
404 documents.not_found | El documento no existe o es de otro emisor. |
409 events.nominate.not_a_factura | No es una factura (SIFEN: 4454). |
409 events.nominate.document_cancelled | La factura está cancelada (4452). |
409 events.nominate.document_not_approved | No tiene CDC o no está approved ni approved_with_observation. |
409 events.nominate.receiver_not_innominado | El receptor de la factura no es innominado (4469). |
409 events.nominate.cancellation_pending | Una cancelación de la factura todavía puede registrarse (details.event_ids). |
409 events.nominate.already_nominated | La factura ya tiene una nominación aprobada (4453). |
409 events.nominate.already_pending | Otra nominación todavía puede registrarse (details.event_ids). |
422 request.validation_failed | motivo o receptor inválidos. El código está en details.errors[].code, por ejemplo events.nominate.receptor.innominado_not_allowed o events.nominate.receptor.tipo_operacion_not_allowed. |
Notas sobre una factura innominada
Al crear una nota de crédito o de débito cuyo documento_asociado.cdc es una
factura innominada de tu emisor creada por las rutas tipadas:
- sin una nominación aprobada responde
409 documents.documento_asociado.nomination_required, condetails.document_id,details.nomination_event_idydetails.nomination_status; - con la nominación aprobada, el
clientede la nota tiene que ser el nominado: el mismo RUC y DV, o el mismo tipo y número de documento. Si no, responde422 documents.documento_asociado.receptor_not_nominated, con el receptor esperado endetails.expected.
KilaSifen no controla que una nota nombre al receptor de una factura nominal
(2441): eso lo valida SIFEN.
Si la respuesta de SIFEN se pierde
Igual que en la cancelación: después de un intento incierto se consulta el
CDC, y si xContEv muestra la nominación el evento queda approved sin
reenviarse. 4453 («el CDC ya cuenta con un evento previo de nominación»)
nunca se toma como rechazo por sí solo: se consulta el CDC y, si la nominación
no aparece, el evento queda reconciliation_required.
Inutilizar numeración
curl -X POST https://TU_API/v1/emitters/EMITTER_ID/inutilizations \
-H "X-API-Key: $KILA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"timbrado":"12345678","document_type":"factura","establishment":"001","point":"001","numero_desde":15,"numero_hasta":20,"motivo":"Salto de numeración por error del sistema"}'| Campo | Regla |
|---|---|
timbrado | 8 dígitos. Tiene que ser un timbrado registrado del emisor (422 events.inutilize.unknown_timbrado). |
document_type | factura, autofactura, nota_credito, nota_debito o nota_remision. |
establishment, point | De 0 a 999; se normalizan a 3 dígitos ("1" pasa a "001"). |
numero_desde, numero_hasta | Desde 1. numero_hasta no puede ser menor que numero_desde (422 events.inutilize.invalid_range), y el rango admite hasta 1000 números (422 events.inutilize.range_too_large). |
motivo | De 5 a 500 caracteres, en una sola línea (sin saltos de línea ni tabulaciones). |
serie | Opcional: dos letras mayúsculas (dSerieNum), sólo si la numeración se reinició con serie (NT 10). |
El contrato también acepta fe_exportacion, fe_importacion y
comprobante_retencion (iTiDE 2, 3 y 8), pero esos tipos no son DE vigentes en
v150: no los uses. La boleta (iTiDE 9) no está disponible.
KilaSifen no comprueba que el establecimiento y el punto pertenezcan al
timbrado; si no pertenecen, SIFEN rechaza (4054 o 4055). Para un único
número (numero_desde igual a numero_hasta), el MT exige que el número final
sea mayor que el inicial (4068). Si SIFEN acepta un solo número no está
determinado: probalo en el ambiente de test.
El 201 trae event, job, inutilization (el rango guardado; el
sifen_protocol de la aprobación llega en el webhook numbering.inutilized) y
warnings.
Cuándo corresponde inutilizar
La inutilización es para números que no son DTE: saltos de numeración, errores de llenado o DE rechazados cuya corrección cambia el CDC (MT v150 §11.1.1). La normativa exige además que no se haya configurado el hecho imponible y que el DE no se haya entregado al receptor (RG 23/2019, Art. 23; Decreto 872/2023, Art. 31). KilaSifen no puede verificarlo: si descargaste el KuDE de un documento mientras estaba pendiente, pudo haberse entregado. La responsabilidad es del emisor.
Qué números se pueden inutilizar
| Documento con ese número | ¿Se inutiliza? |
|---|---|
| Ninguno (salto de numeración) | Sí. Si SIFEN acepta números todavía no alcanzados por la numeración no está determinado: probalo en test. |
rejected (rechazo de SIFEN) | Sí, si su job no lo va a reenviar (un rechazo 0161/0162, o 0160 sin detalle, con el job activo no). |
failed (validación local) | Sí, si ningún job lo va a reintentar. |
queued | Sí, si ningún job lo va a enviar (por ejemplo, intentos agotados después de un 0420). |
approved, approved_with_observation | No: es un DTE (SIFEN rechaza con 4065). |
cancelled | No, por precaución: no está determinado si SIFEN aplica 4065 a un DTE cancelado. |
inutilized | No: ya está inutilizado. |
processing, submitting, submitted, retry_pending, reconciliation_required | No: puede estar en SIFEN. Si una consulta por CDC responde 0420, vuelve a queued y se puede inutilizar cuando ningún job lo va a reenviar. |
Los números bloqueados devuelven 409 events.inutilize.range_already_used,
con details.collisions (los números) y details.documents (document_id,
numero y status de cada uno). Un rango que se superpone con una
inutilización ya aprobada devuelve 409 events.inutilize.range_already_inutilized,
con details.ranges. Una inutilización del mismo rango que todavía no fue
aprobada no se bloquea: esperá su resultado antes de repetirla, o SIFEN puede
responder 4066.
La inutilización es por timbrado: un documento firmado con otro timbrado
(según el dNumTim de su XML) no choca con el rango ni cambia de estado.
Aprobado el evento, la numeración automática del emisor saltea el rango para
ese tipo, establecimiento y punto, sin distinguir timbrado.
Cuando SIFEN aprueba el evento, los documentos del rango pasan a inutilized
y su KuDE responde 409 documents.kude_not_available. Si un job volvió a
enviar alguno mientras tanto, ese documento queda en manos de su job y SIFEN lo
rechazará (1109). El webhook numbering.inutilized trae los documentos
marcados en data.document_ids; no se publica un document.inutilized por
documento.
Plazo
La normativa pide inutilizar dentro de los primeros 15 días del mes siguiente
al error o al consumo del número (RG 23/2019, Art. 23; MT v150, Tabla J). El MT
no define un código de rechazo por plazo, y si SIFEN rechaza una inutilización
tardía no está determinado: KilaSifen no la bloquea. Si algún número del rango
tiene documento y el plazo ya pasó (contado desde la creación del documento,
en hora de Paraguay), la respuesta trae
warnings: ["inutilization.extemporaneous"] y el evento guarda la fecha límite
en input_payload.typed_contract.payload.deadline. Para los números sin
documento no se calcula plazo: controlalo vos.
Si un reintento recibe 4066 después de un intento incierto, el evento queda
reconciliation_required: ningún servicio permite saber si el rango lo
inutilizó ese intento anterior (NO DETERMINADO).