Consultas y artefactos
Recuperá estado, XML y KuDE sin depender exclusivamente de webhooks.
Estado de un documento
GET /v1/emitters/{emitter_id}/documents/{document_id}
GET /v1/emitters/{emitter_id}/documents
GET /v1/emitters/{emitter_id}/jobs/{job_id}Las tres rutas requieren el scope tenant:read y no llaman a SIFEN.
El GET de un documento responde data.document (con internal_status,
cdc, sifen_result_code, fiscal_warnings y los XML) y data.job, su job
de emisión (con status, attempts y error_snapshot), que puede ser null.
Cómo leer los dos estados está en
Estados y reintentos.
El listado devuelve data.documents, del más nuevo al más viejo, donde cada
elemento trae document y job con la misma forma, y data.pagination con
limit, offset y count (la cantidad de esta página). Filtra por
internal_status, document_type (factura, nota_credito, nota_debito),
external_id y cdc; limit va de 1 a 100 (50 por defecto). Sirve para
reconciliar tu ERP sin webhooks: por ejemplo, listá los retry_pending o buscá
por tu external_id.
GET .../jobs/{job_id} devuelve data.job para cualquier job del emisor, de
un documento o de un evento; el job_id viene en data.job.id de la
respuesta de creación.
Consultar SIFEN
GET /v1/emitters/{emitter_id}/queries/documents/{document_id}
POST /v1/emitters/{emitter_id}/queries/documents/{document_id}/reconcile
GET /v1/emitters/{emitter_id}/queries/ruc/{ruc}Estas rutas llaman a SIFEN en el momento, con el certificado activo del
emisor. Los GET requieren tenant:read; POST .../reconcile, fiscal:write.
Sandbox
Estas rutas no usan el simulador del sandbox: contactan el
SIFEN de pruebas real, que no conoce los documentos simulados. Con un
documento del sandbox no reproducen el resultado elegido, y una
reconciliación puede cambiar su estado según lo que responda ese SIFEN.
Seguí los documentos del sandbox con
GET /v1/emitters/{emitter_id}/documents/{document_id} y los webhooks.
Consulta por CDC
Sólo se consulta el CDC de un documento del emisor; no hay consulta de un CDC
arbitrario. Un documento que todavía no tiene CDC (el worker no lo preparó)
responde 409 documents.cdc_required_for_query. La respuesta viene en
data.document_query, con status:
status | Código SIFEN | Significado |
|---|---|---|
found | 0422 | El CDC es un DTE aprobado. |
not_found_or_not_approved | 0420 | No existe o no está aprobado (nunca llegó, o fue rechazado). |
error | cualquier otro (por ejemplo 0421) | La consulta falló; no dice nada del CDC. El significado de 0421 es ambiguo en el MT v150 (NO DETERMINADO) y KilaSifen lo trata como error. |
Los demás campos:
document_idycdc: el documento consultado y su CDC.result_codeyresult_message:dCodResydMsgResde la consulta.processed_at: eldFecProcde la consulta, es decir, cuándo SIFEN procesó la consulta, no cuándo aprobó el DE.- Con
found:content_xmles el contenedor que devuelve SIFEN (xContenDE), tal cual;sifen_protocol, el número de transacción del DTE (dProtAut);events, los eventos registrados del CDC (kind,cdc,protocol), ycancelled, si hay una cancelación registrada.
El GET registra la consulta en el documento (last_query_request_xml,
last_query_response_raw y last_query_at; la solicitud guardada es
exactamente la que viajó, con su dId) sin cambiar su estado.
POST .../reconcile además aplica la respuesta, sin enviar nada:
- con
0422, un documentosubmitting,submitted,retry_pendingoreconciliation_requiredquedaapproved(ocancelledsi hay una cancelación registrada) y su jobsucceeded; un documento aprobado con una cancelación registrada quedacancelled; - con
0420, un documentosubmitted,retry_pendingoreconciliation_requiredque esperaba confirmar un rechazo1001/1002quedarejected. Si no, vuelve aqueued: si su job sigue programado, el worker reenvía el mismo DE firmado; si el job ya terminó (failed), hace falta reintentar el job o inutilizar el número. Un documentosubmittingno se toca: lo resuelve su worker; - en cualquier otro estado, incluido
queued, o conerror, sólo queda registrada la consulta.
Cuando hay un cambio de estado, sifen_result_code y sifen_result_message
del documento pasan a ser los de la consulta (0422 o 0420), salvo en un
rechazo 1001/1002 confirmado, que conserva el primer error que informó
SIFEN.
La respuesta de reconcile trae sólo el resultado de la consulta, no el estado
que quedó, y la reconciliación no publica webhooks: después de reconciliar,
leé el documento con GET /v1/emitters/{emitter_id}/documents/{document_id}.
El XML firmado que emitió KilaSifen nunca se reemplaza por la copia de SIFEN.
La operación no bloquea al emisor mientras espera la respuesta de SIFEN.
Consulta RUC
GET .../queries/ruc/{ruc} acepta el RUC con o sin DV (RUC o RUC-DV).
KilaSifen descarta el DV sin validarlo y consulta el número, que tiene que tener
de 5 a 8 caracteres (MT v150 §9.6.1); si no, responde
422 queries.invalid_ruc. Nada de esta consulta se guarda.
La respuesta viene en data.ruc_query:
| Campo | Contenido |
|---|---|
queried_ruc | El RUC consultado, sin DV. |
status | found si SIFEN devolvió los datos del contribuyente (0502); not_found si el RUC no existe (0500); error con cualquier otro código, por ejemplo 0501, que no dice si el RUC existe. |
result_code, result_message | dCodRes y dMsgRes: 0502 RUC encontrado, 0500 RUC no existe, 0501 RUC sin permiso para usar el servicio de consulta (MT v150 §9.6.2, Tabla H). |
taxpayer | Con found: ruc, dv, legal_name, state_code, state (su descripción) y electronic_taxpayer (si es facturador electrónico). SIFEN no devuelve el DV: KilaSifen lo calcula con el módulo 11 oficial. |
state_code es ACT (activo), SUS (suspensión temporal), SAD (suspensión
administrativa), BLQ (bloqueado), CAN (cancelado) o CDE (cancelado
definitivo).
Si SIFEN contesta un 0160 sin detalle, o un 0161/0162, KilaSifen repite
la consulta hasta dos veces, a los 2 y a los 4 segundos: el ambiente de pruebas
contestó así a consultas válidas que pasaron segundos después. Si después de
eso no hay respuesta, o SIFEN no contesta (timeout o conexión cortada), la API
responde 503 queries.sifen_unavailable: no se sabe nada del RUC y se puede
volver a consultar más tarde.
Autocompletar un RUC
Con esta consulta tu ERP puede completar la razón social y el DV cuando el usuario carga un RUC, y avisar si el contribuyente no está activo o si es facturador electrónico. Es todo lo que da SIFEN (MT v150 §9.6): ningún servicio oficial devuelve la dirección, las actividades económicas, el teléfono ni si es persona física o jurídica.
- La consulta usa el certificado activo de un emisor: sólo funciona después de que ese emisor cargó y activó su certificado.
- Consultá cuando el RUC está completo (por ejemplo, al salir del campo), no con cada tecla, y guardá el resultado en tu ERP: cada consulta llega a SIFEN.
- Con
not_found, el RUC no existe. Conerroro un503, dejá cargar los datos a mano. - En el ambiente de pruebas,
not_foundpuede ser falso: ahí SIFEN respondió0500para RUC reales que existen, mientras encontraba otros. Dejá cargar los datos a mano también en ese caso. - La consulta masiva de RUC de la NT 11 (un archivo diario con esos mismos datos de todos los contribuyentes) no está disponible: la NT no publica la dirección del servicio ni el formato del archivo.
La consulta RUC permite comprobar información tributaria expuesta por SIFEN; no es una central de riesgo crediticio.
Errores de las consultas
| HTTP | code | Cuándo |
|---|---|---|
403 | auth.insufficient_scope | A la clave le falta el scope de la ruta. |
404 | emitters.not_found, documents.not_found | Emisor o documento inexistente, o de otro emisor. |
409 | documents.cdc_required_for_query | El documento todavía no tiene CDC. |
409 | certificates.active_required, emitters.inactive | El emisor no tiene un certificado activo, o está inactivo. |
422 | queries.invalid_cdc, queries.invalid_ruc | CDC o RUC mal formado. Hoy también sale así si el certificado activo no se puede leer; el message trae ese error. |
500 | server.internal_error | SIFEN no respondió una consulta por CDC (timeout o conexión cortada), o el ambiente del emisor no coincide con el del despliegue. Reintentá más tarde con backoff. |
503 | queries.sifen_unavailable | La consulta RUC no obtuvo respuesta de SIFEN, también después de repetir un 0160 sin detalle. Reintentá más tarde. |
Descargar artefactos
GET /v1/emitters/{emitter_id}/documents/{document_id}/xml
GET /v1/emitters/{emitter_id}/documents/{document_id}/kude
GET /v1/emitters/{emitter_id}/documents/{document_id}/kude/data/xml devuelve el rDE firmado que emitió KilaSifen o, si el documento
todavía no se firmó, su XML sin firmar; nunca el contenedor de SIFEN. Sin XML
(por ejemplo, antes de que el worker prepare el documento) responde
409 documents.xml_not_available.
El KuDE sale del XML firmado, así que sólo existe cuando KilaSifen ya firmó
el documento (si no, 409 documents.signed_xml_not_available), y el emisor
tiene que tener cargados csc y csc_id (si no, 409 emitters.csc_required;
ver Emisores). Además depende del estado del documento:
| Estado | KuDE |
|---|---|
approved, approved_with_observation | Disponible. |
queued, processing, submitting, submitted, retry_pending, reconciliation_required | Disponible: con validación posterior el KuDE puede entregarse antes de la aprobación, pero sólo vale si el SIFEN aprueba el DE (MT v150 §6.2 y §6.4). |
rejected, failed, inutilized, cancelled u otro estado | 409 documents.kude_not_available, con el estado en details.internal_status. Un DE rechazado nunca es un DTE (MT v150 §6.4; Decreto 872/2023, Arts. 4 y 29), un DTE cancelado pierde su validez (Art. 30) y un número inutilizado no tiene DE (Art. 31). |
El PDF imprime el código QR en la primera página, numera las páginas como
n/total, muestra la fecha de inicio del timbrado como DD-MM-AAAA
(NT 10) y, si la moneda no es PYG, el total en guaraníes (dTotalGs).
Cantidades y montos se imprimen con todos los dígitos del XML firmado, sin
redondear: el KuDE no puede mostrar información que no esté en el XML y
tiene que coincidir con el DTE (MT v150 §13.2 y §6.6). Sólo cambian los
separadores: un IVA de 2380.95 se imprime 2.380,95. Los totales
muestran también el subtotal exonerado y, cuando no son cero, el redondeo y
la comisión, así los subtotales impresos suman como en el XML.
/kude/data devuelve los mismos datos con el texto literal del XML firmado
(montos con todos sus decimales, fechas AAAA-MM-DD): si armás tu propio
KuDE con ellos, imprimí cada monto completo, sin redondearlo.
totales.total_general_operacion es dTotGralOpe, en la moneda de la
operación, y totales.total_general_guaranies es dTotalGs cuando la
moneda no es PYG (o dTotGralOpe en PYG). qr.url es el dCarQR del XML.