Autenticación

Esta es la página que ninguna colección de Postman trae, y la que explica la mayoría de los fallos al integrar por primera vez.

Los dos headers

Header	¿Obligatorio?	Qué es
x-integracion-login	sí	El nombre de tu integración. Se compara en minúsculas.
x-integracion-token	sí	El secreto de tu integración. Se compara con bcrypt; nunca viaja por query string ni por cuerpo.

curl -sS -X POST 'https://dev.api.tributax.app/catalogos/cui-nit' \
  -H 'content-type: application/json' \
  -H 'x-integracion-login: <NOMBRE_INTEGRACION>' \
  -H 'x-integracion-token: <TOKEN_INTEGRACION>' \
  -d '{"nit":"<NIT>"}'

Las credenciales las crea un administrador de Tributax, por entorno. Escríbenos desde Contacto.

Las cinco consultas de este portal se resuelven solo con esas credenciales. No se opera por cuenta de ningún contribuyente, así que ninguna pide el NIT de un tercero en un header ni depende de que alguien apruebe tu integración: el NIT o el CUI que consultas viaja en el cuerpo de la petición, como dato de la operación.

No envíes Authorization

No hay token que pedir, guardar, refrescar ni rotar: tus credenciales viajan en sus dos headers y el servidor resuelve el resto internamente.

Si ves un 401 con resetLogin —{"error":true,"message":"Error de autenticación. Por favor vuelva a iniciar sesión.","resetLogin":true}— es el fallo de un token Bearer inválido o vencido. Como tú no envías Authorization, verlo significa que algo por el camino está añadiendo esa cabecera: revisa tu proxy o tu cliente HTTP.

Orden de evaluación

1 ·  ¿Llegó alguno de los dos headers de integración?
        ↓ sí                              ↓ no
2 ·  ¿Abren una integración real?      la petición sigue sin integración
        ↓ sí            ↓ no: 401              ↓
3 ·  ¿La consulta está habilitada en tu integración?      → no: 403
        ↓ sí
4 ·  Se atiende la consulta.

El paso 2 tiene una consecuencia poco intuitiva: enviar solo uno de los dos headers también da 401, porque la validación arranca en cuanto aparece cualquiera de ellos. No enviar ninguno es distinto: la petición sigue sin credenciales y la rechaza la consulta con un 403.

Tabla de fallos

Situación	Status	Cuerpo
Credenciales de integración inválidas, o solo uno de los dos headers	401	{"message":"Integración no encontrada con estas credenciales."}
Sin ningún header, en los catálogos	403	{"message":"Se requieren credenciales de integracion."}
Sin ningún header, en RENAP o RTU por NIT	403	{"error":"Integration authentication required."}
La consulta no está habilitada en tu integración	403	Ver Consultas

:::caution La clave del error cambia según la consulta Los tres catálogos responden {"message":"…"}; RENAP y RTU por NIT responden {"error":"…"}. Es la diferencia que más código rompe al reusar el mismo parseo para las cinco. El detalle, en Catálogo de errores. :::

Qué se habilita y quién lo habilita

Credenciales válidas no bastan: cada consulta se activa por separado en tu integración, y solo puede activarla un administrador de Tributax. Tener RENAP activo no habilita el RTU, y tener el RTU por NIT no habilita el catálogo de RTU: son banderas distintas.

Pide la habilitación nombrando la ruta exacta desde Contacto.

📄 Estado de verificación: leído del código del backend. Las respuestas de esta página no se han ejercido contra el entorno desplegado en esta entrega.