Consultas generales
Lecturas contra la DIAN: terceros, eventos de un documento y su XML. Se ejecutan sin gastar consecutivos.
Esta página se lee antes de ejecutar: explica qué vas a enviar y qué se hace con ello. Al final están los enlaces a las funciones, en el orden en que conviene probarlas.
1 · Qué se puede consultar en la DIAN
Las consultas son lecturas: preguntan a la DIAN por algo que ya existe. No emiten nada, no modifican nada y —esto es lo importante al empezar— no gastan consecutivos. Es por donde conviene arrancar una integración: compruebas la forma de la respuesta y la conectividad antes de escribir la primera línea del documento electrónico.
Hay cinco, y se distinguen por lo que las identifica: una identificación de tercero, un NIT de emisor, un número de resolución o el identificador único de un documento ya reportado.
2 · Qué identifica cada consulta
Faltan dos lecturas en esa lista: las de resolución de numeración. Están en Facturación electrónica porque es donde vive la numeración — en producción llegan por ese dominio, y la clave técnica que entregan interviene en el cálculo del CUFE. Se ejecutan igual que estas y tampoco gastan consecutivos.
3 · Lo que hay que tener presente
Es la trampa más común de este grupo. Un tercero que la DIAN no tiene registrado responde 200 con el nombre y el correo vacíos; un NIT sin
rangos autorizados responde 200 con la lista vacía;
y una resolución que no existe responde 200 con los
campos vacíos, no 404. Tu integración tiene
que evaluar el contenido de la respuesta, no solo el código HTTP.
El catálogo de terceros y de documentos de habilitación no coincide con el de producción: un NIT real puede responder vacío aquí y con datos allá, y el CUFE de una factura de producción no devuelve nada. Lo natural es consultar el CUFE de una factura que hayas emitido antes desde el propio portal. Algunas rutas reciben un parámetro de ambiente: se recibe pero no se aplica, y está en el contrato para que la URL que integres hoy sea la misma de producción.
Cuatro de las cinco consultas devuelven el envoltorio JSON del Proveedor Tecnológico, con encabezado y respuesta. El XML de un UUID es la excepción: devuelve el documento con Content-Type: application/xml, y se procesa como texto.
4 · Cómo las resuelve el sandbox
Las consultas comparten la misma forma: los datos van en la ruta, no llevan cuerpo y no gastan consecutivos ni dejan nada reportado en la DIAN. Por eso son las funciones con las que conviene empezar: se pueden repetir tantas veces como haga falta. La consulta se resuelve ante la DIAN, y si hay registro responde 200 con los datos encontrados. Si no hay registro también responde 200, con los mismos campos vacíos: la ausencia de resultado también es un resultado, y una integración que espere un 404 para decidir «no encontrado» no lo va a recibir nunca. **La consulta del XML de un documento es la excepción**: esa sí responde 404, y tiene su propio diagrama.
Desliza el diagrama para verlo completo.
Ver la fuente Mermaid del diagrama
flowchart TD
A(["La consulta llega con sus datos en la ruta"]) --> B["Consulta ante la DIAN"]
B --> C{"¿Hay registro?"}
C -- Sí --> D(["200 · los datos encontrados"])
C -- No --> E(["200 · los mismos campos, vacíos"])Antes de resolver la consulta, toda función del portal pasa por la misma verificación. Es lo que explica
un 401 en una consulta que está bien escrita: no es
el dato que preguntaste, es la credencial o el perfil.
Toda función del sandbox pasa por la misma verificación. Si no llega el encabezado Authorization responde 400. Si llega pero el token no es válido, responde 401. Con el token válido comprueba que el desarrollador tenga perfil registrado y activo: si no lo tiene responde 401, y el mensaje distingue las tres causas —cuenta sin correo, perfil inexistente y perfil suspendido— para que no haya que adivinar cuál es. Lo observable es que un token válido no alcanza: la identidad sale siempre del token, y nada de lo que se envíe en la ruta o en el cuerpo cambia de qué desarrollador se trata. En la etapa productiva la compuerta comprueba además dos cosas contra el documento que se envía, y las dos responden 401: que el NIT del emisor sea el autorizado en la credencial, y que el tipo de documento electrónico corresponda al servicio autorizado —facturación no emite nómina, y al revés—. En el sandbox esas dos no se alcanzan a ver, porque el emisor lo fuerza el propio sandbox.
Desliza el diagrama para verlo completo.
Ver la fuente Mermaid del diagrama
flowchart TD
R(["Petición del desarrollador<br/>Authorization: Bearer idToken"]) --> T{"¿Viene el token?"}
T -- No --> E1(["400 · No se especificó el token<br/>de autenticación"])
T -- Sí --> F{"¿El token es válido?"}
F -- No --> E2(["401 · Token de autenticación no válido"])
F -- Sí --> Q{"¿Perfil registrado y activo?"}
Q -- No --> E4(["401 · Perfil no registrado o suspendido,<br/>con el motivo en el mensaje"])
Q -- Sí --> OK(["200 · Autorizado, continúa la operación"])