Autenticación
Cada petición lleva una API key en el header Authorization:
Authorization: Bearer sk_test_…sk_test_…: llaves de habilitación (pruebas ante la DIAN).sk_live_…: producción.sk_sandbox_…: modo sandbox (DIAN simulada, sin consumir documentos de tus bolsas).- La llave completa se muestra una sola vez, al crearla. La plataforma guarda solo su hash; si la
pierdes, crea otra y revoca la anterior (
DELETE /v1/api-keys/{id}).
Modo sandbox (sk_sandbox_…)
Sección titulada «Modo sandbox (sk_sandbox_…)»Crea una llave con "environment": "sandbox" (POST /v1/api-keys) para integrar y probar sin consumir
bolsas ni enviar nada a la DIAN real. No necesitas tener software, certificado ni rangos configurados:
basta con registrar el facturador. El documento se construye, numera y firma (puedes descargar su XML,
PDF, ApplicationResponse y AttachedDocument), pero:
- Se numera con el prefijo
SBX(SBX1,SBX2…), aparte de tus rangos de la DIAN: nunca consume tu numeración autorizada. - Se firma con un certificado de prueba de la plataforma (“SANDBOX - SIN VALIDEZ LEGAL”), nunca con el tuyo; el PDF lleva la marca de agua “SANDBOX — SIN VALIDEZ”.
- El envío va a una DIAN simulada y determinista donde eliges el resultado con la cabecera
X-Sandbox-Outcome.
Valor de X-Sandbox-Outcome |
Qué simula |
|---|---|
accepted (por defecto) |
La DIAN acepta el documento (statusCode: "00"). |
rejected:<REGLA> |
La DIAN rechaza con la regla indicada, p. ej. rejected:FAD06. |
timeout |
La DIAN no responde (DIAN_UNAVAILABLE), útil para probar reintentos y document.failed. |
rule90:accepted |
El primer envío devuelve regla 90 (“procesado anteriormente”) y GetStatus confirma aceptación. |
rule90:rejected:<REGLA> |
Regla 90 en el envío y rechazo en GetStatus con la regla indicada. |
rule90:pending |
Regla 90 en el envío y GetStatus aún en proceso (se reintenta). |
Si envías X-Sandbox-Outcome con una llave sk_test_… o sk_live_…, la API responde 422. Los
documentos emitidos en sandbox llevan "sandbox": true.
Aislamiento. Una llave sandbox solo puede emitir documentos sandbox, consultarlos y reintentarlos,
leer la cuenta y los facturadores, y consultar la DIAN simulada (/v1/tenant/acquirer,
/v1/tenant/numbering-ranges/dian). Todo lo demás (configuración, llaves, bolsas, consumo, webhooks)
responde 403. Los documentos sandbox no se ven con las demás llaves, ni los reales con la sandbox.
- Sus eventos solo llegan a los webhooks de sandbox (créalos con
"sandbox": truedesde una llave de cuenta); los demás webhooks nunca los reciben. - Las peticiones sandbox tienen su propio límite por minuto: probar no gasta el de tu cuenta.
- Los documentos sandbox se borran a los 30 días.
Llaves de cuenta y llaves de facturador
Sección titulada «Llaves de cuenta y llaves de facturador»Una llave de cuenta opera sobre todos tus facturadores. En las rutas de un facturador
(/v1/tenant/…, la emisión y la consulta de documentos) indica cuál con:
X-Tenant-Id: 900373115Acepta el id del facturador o su NIT.
Una llave restringida (POST /v1/api-keys con tenantId) solo opera sobre ese facturador: no
necesita X-Tenant-Id y no puede administrar la cuenta (crear llaves, registrar facturadores, ver el
consumo). Es la que se le entrega a un cliente final.
Si falta la llave o no es válida, la respuesta es 401 UNAUTHORIZED; si la llave no puede hacer lo
pedido, 403 FORBIDDEN. Ver Errores.