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, incluidodevelopment(el valor por defecto), staging y producción, el header responde422 sandbox.test_runtime_required. - Un emisor con
tax_environment: test, perfil fiscal completo, CSC con sucsc_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=trueen la API. Para recibir webhooks, el worker necesitaKILA_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/jsonResultados disponibles:
| Valor | Resultado simulado |
|---|---|
approved | Aprobación normal, con código 0260. |
approved_with_observation | Aprobación con observación, también con código 0260. |
rejected | Rechazo fiscal definitivo, con código 1330. |
transport_timeout | Timeout 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_lost | SIFEN 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.