KilaSifen Docs

Sandbox determinístico

Probá aprobaciones, rechazos y respuestas perdidas sin transmitir el documento a SIFEN.

El sandbox recorre el flujo real de emisión de KilaSifen —validación, numeración, XML v150, CDC, firma, persistencia, job y webhook—, pero el job de emisión no transmite el documento: un simulador reemplaza el envío a SIFEN y la consulta por CDC que hace ese job.

Requisitos

  • Una instancia con KILA_SIFEN_ENVIRONMENT=test. Con cualquier otro valor, incluido development (el valor por defecto), staging y producción, el header responde 422 sandbox.test_runtime_required.
  • Un emisor con tax_environment: test, perfil fiscal completo, CSC con su csc_id (el QR también se calcula de verdad), un certificado PKCS#12 activo (la firma es real, así que el certificado tiene que estar vigente, con clave RSA de al menos 2048 bits y el RUC del emisor) y un timbrado vigente en la fecha de emisión.
  • El worker y el despachador del outbox corriendo, con KILA_SIFEN_DOCUMENT_AUTO_ENQUEUE=true en la API. Para recibir webhooks, el worker necesita KILA_SIFEN_DOCUMENT_PUBLISH_WEBHOOKS=true.
  • Un payload válido: el contrato y las reglas fiscales se validan igual que en una emisión real.

Elegir el resultado

Agregá el header a cualquier creación tipada (factura, nota de crédito o nota de débito):

POST /v1/emitters/{emitter_id}/documents/facturas
X-API-Key: ...
X-Kila-Test-Outcome: approved_with_observation
Content-Type: application/json

Resultados disponibles:

ValorResultado simulado
approvedAprobación normal, con código 0260.
approved_with_observationAprobación con observación, también con código 0260.
rejectedRechazo fiscal definitivo, con código 1330.
transport_timeoutTimeout en cada envío y 0420 en cada consulta: se consulta el CDC, se reenvía el mismo DE firmado y, tras 5 intentos (unos 43 minutos con las esperas por defecto de 30 s, 2 min, 10 min y 30 min), termina en reconciliation_required.
accepted_but_response_lostSIFEN acepta el DE pero se pierde la respuesta; la consulta posterior lo encuentra (0422) sin reenviarlo.

Los códigos son fijos y no reproducen una respuesta real de SIFEN: approved_with_observation no trae un código de observación (como 1005), y el 1330 de rejected es un código real de SIFEN con otro significado (número de casa del receptor). No pruebes con el sandbox un mapeo de motivos por código. La respuesta guardada es un XML propio del simulador (sandboxSifenResponse).

La directiva queda guardada junto a la intención, por lo que el worker produce el mismo resultado aunque procese el job más tarde. Un reintento idempotente tiene que repetir el mismo header: sin él, o con otro valor, la respuesta es 409 documents.idempotency_key_conflict. Un campo sandbox dentro del JSON tipado se rechaza con 422: sólo el header activa la simulación.

En los dos escenarios ambiguos el intento siguiente consulta el CDC antes de hacer nada. En accepted_but_response_lost la consulta lo encuentra (0422) y el documento converge sin un segundo envío. En transport_timeout la consulta responde 0420, así que vuelve a viajar el mismo DE firmado (mismo CDC y firma, dId nuevo), nunca una segunda intención. Así podés verificar que tu integración converge por consulta y nunca por doble emisión.

Qué no simula

Estas rutas van al SIFEN de pruebas real

Sólo el job de emisión usa el simulador. La consulta manual (GET .../queries/documents/{document_id}), reconcile, la cancelación, la nominación y la inutilización usan el SIFEN de pruebas real aunque el documento sea del sandbox, y SIFEN no conoce ese CDC. No las uses con documentos del sandbox. Lo mismo vale para una nota de crédito o débito creada sin el header que asocia una factura del sandbox. Con KILA_SIFEN_ENVIRONMENT=test ese tráfico nunca llega a producción.

Un documento del sandbox consume la numeración real del emisor (la misma secuencia por establecimiento, punto de expedición y tipo) y su CDC y XML llevan el RUC del emisor. Usá un emisor o un punto de expedición exclusivo para el sandbox, así no dejás huecos en la numeración de tus pruebas reales.

Barrera de ambiente

Fuera de KILA_SIFEN_ENVIRONMENT=test el header responde 422 sandbox.test_runtime_required. Además, el worker y el propio simulador vuelven a validar el ambiente, y que el emisor sea de test, antes de ejecutar la simulación.

En esta página