Ir al contenido

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}).

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": true desde 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.

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: 900373115

Acepta 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.