Consultas

Tributax ofrece cinco consultas a integradores habilitados, en dos grupos con contratos distintos:

Consulta	Endpoint	Por qué
RENAP por CUI	POST /renap/buscar-cui	Validar la identidad de una persona
RTU por NIT	POST /rtu/nits	Resolver hasta 50 contribuyentes por NIT ante SAT
CUI/NIT	POST /catalogos/cui-nit	Resolver la correspondencia entre el CUI y el NIT de un contribuyente
RTU (catálogo)	POST /catalogos/rtu	El registro de un contribuyente en el RTU, uno a la vez
Omisos	POST /catalogos/omisos	Si un contribuyente está listado como omiso

Estas no son las APIs de RENAP ni de la SAT: son endpoints de Tributax que hacen la consulta por ti, con su propio control de acceso, su propio límite y su propio registro de consumo. No necesitas contratar con RENAP ni con SAT por tu cuenta.

Lo que comparten las cinco

Solo piden las credenciales de tu integración. Ninguna lleva x-user-nit: no se opera por cuenta de nadie, se consulta un registro.

Son opt-in por integración, una bandera por consulta. Las activa un administrador de Tributax, no tú. Sin la habilitación correspondiente, la respuesta es 403 aunque tus credenciales sean correctas — tener una activa no habilita las demás.

Tienen su propio límite por minuto, además del global de 100 por 15 minutos:

Consulta	Límite	Se cuenta por
RENAP	30 / min	nombre de la integración
RTU (/rtu/nits)	50 / min	nombre de la integración
CUI/NIT, RTU y Omisos (/catalogos/*)	30 / min, compartido entre los tres	integración

Cada consulta que llega a la fuente queda registrada —integración, endpoint, status, tiempo de respuesta y parámetro consultado— para auditoría. Los rechazos anteriores a la consulta, como unas credenciales inválidas o el límite por minuto, no dejan registro.

No todas responden igual

RENAP y RTU (/rtu/nits) responden con la clave error, no message. A diferencia del resto de la API. Es una de las razones por las que el catálogo de errores insiste en que el discriminante fiable es el status HTTP, no la forma del cuerpo.

Los tres catálogos (/catalogos/*) responden con message, como el resto de la API. Ver el detalle en Catálogos.

Errores comunes a RENAP y RTU (/rtu/nits)

Situación	Status	Cuerpo
Sin credenciales de integración	403	{"error":"Integration authentication required."}
Credenciales de integración incorrectas	401	{"message":"Integración no encontrada con estas credenciales."} — lo rechaza la cadena general antes de llegar aquí
Servicio no habilitado en tu integración	403	{"error":"RENAP access not enabled."} / {"error":"RTU access not enabled."}
Límite por minuto excedido	429	{"error":"Rate limit exceeded."}

Los errores de los tres catálogos (/catalogos/*) tienen su propia tabla en Catálogos.

Para habilitar cualquiera de estas cinco consultas en tu integración, escríbenos desde Contacto.

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