RTU — consultar por NIT

POST /rtu/nits

Consulta hasta 50 NIT por petición en el Registro Tributario Unificado.

Requisitos previos

1. Credenciales de integración válidas. No lleva x-user-nit.
2. is_rtu_enabled activo en tu integración. Lo habilita un administrador de Tributax. Sin ello, 403.

Petición

curl -sS -X POST 'https://dev.api.tributax.app/rtu/nits' \
  -H 'content-type: application/json' \
  -H 'x-integracion-login: <NOMBRE_INTEGRACION>' \
  -H 'x-integracion-token: <TOKEN_INTEGRACION>' \
  -d '{"nits":["<NIT>","<OTRO_NIT>"]}'

Campo	Tipo	¿Obligatorio?	Notas
nits	array de string	sí	Al menos uno, máximo 50.

Consultar 50 NIT de una vez cuesta una petición contra los dos límites; consultarlos uno a uno cuesta 50. Agrupa.

Respuesta

200

{
  "success": true,
  "data": [ { "nit": "<NIT>", "data": { } } ],
  "message": "Found 1 RTU records out of 1 requested",
  "responseCode": 200
}

Campo	Qué es
success	Si la consulta se resolvió.
data	Array de registros encontrados, o null. Cada registro es { nit, data }, donde data es el perfil tal como lo guarda el RTU.
message	Incluye cuántos se encontraron de cuántos se pidieron.
responseCode	El status HTTP replica este valor.

:::note Pedir 50 y recibir 3 es un 200 Los NIT sin registro simplemente no aparecen en data; no hay un array de «no encontrados». Compara los nit devueltos con los que pediste para saber cuáles faltan — el message te dice el conteo, pero no cuáles. :::

Límite: 50 por minuto

Contadas por integración, además del global de 100 por 15 minutos. Al excederlo: 429 {"error":"Rate limit exceeded."}.

La ventana se reinicia a más tardar 60 s después de la primera consulta de la ventana. No hay cabecera Retry-After. El contador vive en memoria del proceso: el límite nominal no es una garantía de capacidad.

Errores

Ojo: los dos 400 tienen formas distintas, porque los produce una capa distinta.

Situación	Status	Cuerpo
nits ausente, vacío, o no es un array	400	{"error":"Array of NITs is required"}
Más de 50 NIT	400	{"success":false,"message":"Máximo 50 NITs por petición","responseCode":400,"data":null}
Sin credenciales de integración	403	{"error":"Integration authentication required."}
RTU no habilitado en tu integración	403	{"error":"RTU access not enabled."}
Más de 50 consultas en un minuto	429	{"error":"Rate limit exceeded."}
Fallo interno	500	{"success":false,"error":"<detalle>"}

El primero lo rechaza la ruta antes de llamar al cliente RTU; el segundo lo produce el cliente y sale con la forma de una respuesta normal. Ramifica por el status, no por la forma.

Cada consulta queda registrada

Se registra la integración, el endpoint, el status, el tiempo de respuesta, los NIT consultados y la respuesta —incluidas las consultas que terminan en 400. Sirve para auditoría y para reportar tu consumo.

📄 Estado de verificación: leído del código del backend. No se ha ejercido contra el entorno desplegado en esta entrega.