Ambientes y URLs

Todo el API cuelga del prefijo /v1. La única excepción es /health, que va en la raíz.

Ambiente	URL base	Para qué
Sandbox	https://sandbox.facturacion.misofk.com/v1	Integrar sin tocar la DIAN
QA	https://qa.facturacion.misofk.com/v1	Pruebas contra la DIAN de habilitación
Producción	https://facturacion.misofk.com/v1	Facturar de verdad

La diferencia que importa

Los ambientes de esta API no son lo mismo que el ambiente DIAN del emisor. Son dos ejes distintos y conviene no confundirlos:

• El ambiente de la API decide contra qué instalación hablas: sandbox, QA o producción.
• El ambiente DIAN del emisor (HABILITACION o PRODUCCION) decide a qué servicio de la DIAN se transmiten sus documentos, y entra en el cálculo del CUFE y en la URL del QR.

Un emisor en HABILITACION dentro de producción emite documentos que la DIAN recibe y valida de verdad, pero sin efecto fiscal. Es el estado normal mientras se completa la habilitación.

No mezcles credenciales

Las credenciales de un ambiente no sirven en otro. Un client_id de sandbox contra producción responde 401.

Cabeceras

Todas las peticiones autenticadas llevan:

Authorization: Bearer <access_token>
Content-Type: application/json

El esquema Bearer se compara respetando mayúsculas: bearer abc no entra.

Límite de peticiones

300 peticiones por minuto y por IP. Es un límite global, no por endpoint ni por emisor. Si lo superas recibes 429.

El API confía en un salto de proxy (trust proxy: 1), así que la IP que cuenta es la de X-Forwarded-For.

Salud

GET /health

Fuera del prefijo /v1 y sin autenticación. Sirve para los chequeos del balanceador, no como parte de la integración.