Probar desde Postman

1 · Descargar la colección

El botón está en dos lugares: en la portada de la documentación, donde descarga todas las funciones ejecutables, y en cada ficha, donde descarga solo esa función con los parámetros y el cuerpo que tengas en la consola en ese momento.

Antes de descargar aparece un aviso que hay que confirmar: el archivo incluye tu credencial de acceso al sandbox. Es la de tu propia sesión, autoriza únicamente el ambiente de habilitación con la empresa de pruebas y vence en una hora, pero es un token real y un archivo se comparte con demasiada facilidad.

Al confirmar, el portal renueva tu credencial y solo entonces arma el archivo, para que la colección se descargue con su hora completa de vigencia.

2 · Importarla en Postman

En Postman, pulsa Import —arriba a la izquierda, junto al árbol de colecciones— y arrastra el archivo que acabas de descargar.

La colección aparece en el árbol con el nombre *InSoft — Proveedor Tecnológico (Sandbox)* y una carpeta por grupo: Consultas, Facturación, Nómina y Eventos. Las funciones con varios escenarios traen dentro una subcarpeta Ejemplos con una petición por cada JSON de la planeación.

3 · Revisar las variables: una URL por dominio

Abre la pestaña Variables de la colección. Son pocas, y cada una tiene su descripción: urlBase con la dirección del sandbox, una URL por grupo —urlConsultas, urlFacturacion, urlNomina, urlEventos— e istoken con tu credencial ya diligenciada.

Las cuatro URL de grupo arrancan valiendo {{urlBase}}: Postman resuelve una variable dentro de otra, así que mientras pruebas en el sandbox el host se cambia en un solo lugar. Y cada petición apunta a la de su grupo, no a una común.

Eso es lo que hace el paso a producción una edición de variables y no de peticiones: allá cada dominio tiene su propia dirección, y se llena la del grupo que estés integrando sin tocar las demás. La ruta de cada petición es la misma en los dos ambientes; la URL base es lo único que cambia, y la de producción se te entrega al adquirir el servicio.

La autorización se declara una sola vez, en el nivel de la colección, y cada petición la hereda: renovar la credencial es cambiar una variable, no editar veinte peticiones.

4 · Los parámetros de la ruta van en la propia petición

Un parámetro de ruta se lee en la URL con dos puntos —{{urlConsultas}}/api/nit/:nit/:tddocumento— y aparece en la pestaña Path Variables de la petición, con su valor de ejemplo ya diligenciado y su descripción al lado. No hay que ir a buscarlo a las variables de la colección.

Cuando el dato es un código de catálogo de la DIAN, la descripción lista los valores admitidos: Postman no tiene desplegables, así que el catálogo viaja escrito y no hay que volver al portal para consultarlo.

Y si un parámetro es opcional, se puede quitar borrando su segmento de la URL. Antes cada parámetro era una variable de la colección: quedaba en otra pestaña y compartido por todas las funciones que usan ese nombre, de modo que cambiar el uuid para probar una consulta lo cambiaba también en las otras.

5 · Enviar la primera consulta

Abre Consultas → Información de un NIT y pulsa Send. No hay nada que configurar: la URL ya trae las variables resueltas y la autorización la hereda de la colección.

Es la petición con la que conviene empezar porque es una lectura: no emite nada y no gasta consecutivos. Si responde 200, la colección quedó bien importada y tu credencial está vigente.

6 · Enviar un documento

Abre Facturación, entra a una función y despliega su subcarpeta Ejemplos. Cada petición es un escenario distinto de la planeación: IVA, retenciones, IBUA, ICUI, AIU, mandato, transporte, moneda extranjera, anticipos, descuentos.

Empieza por Generar el XML sin reportarlo: recorre la verificación completa y devuelve el XML firmado sin llegar a la DIAN, de modo que no gasta consecutivos y se puede repetir cuantas veces quieras. Cuando el documento pase la verificación, pasa a los envios POST, que si reportan y devuelven el UUID.

7 · Cuando la credencial venza, copiarla o descargar otra vez

La credencial del archivo dura una hora y no se renueva sola: el portal renueva la suya, el archivo descargado no. Cuando venza, el sandbox responde 401.

Para que ese 401 no se confunda con un error de integración, la colección trae dos scripts que escriben un aviso en la consola de Postman: uno revisa la vigencia antes de cada petición y otro reacciona al 401.

Hay dos salidas, y no dan lo mismo. Si la colección está tal como se importó, descárgala otra vez desde aquí. Pero si ya le hiciste cambios propios —cuerpos ajustados, peticiones nuevas, un entorno— volver a importar los pierde: para eso está el botón Copiar la credencial de arriba, que renueva el token y lo pone en el portapapeles. Se pega en Variables → istoken → Current value y la colección queda como estaba, con la hora completa.

Las dos salidas entregan la misma credencial mientras siga vigente: el valor que copias es el que traería el archivo si lo descargaras en ese momento, no un token distinto. Es lo que te permite comparar y confirmar que pegaste lo que corresponde.

Y al reves: cuando estés ajustando un JSON en la consola del portal y quieras seguir en Postman, exporta esa función desde su ficha. El archivo sale con el cuerpo y los parámetros que tengas cargados en ese momento, no con el ejemplo por defecto.

Cuando algo no responde como esperas