RENAP — consultar por CUI

POST /renap/buscar-cui

Consulta los datos de una persona por su Código Único de Identificación.

Requisitos previos

1. Credenciales de integración válidas. No lleva x-user-nit.
2. is_renap_enabled activo en tu integración. Lo habilita un administrador de Tributax; no es algo que puedas activar tú. Sin ello, 403.

Petición

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

Campo	Tipo	¿Obligatorio?	Notas
cui	string	sí	Ausente o vacío → 400 {"error":"CUI is required"}.

Respuesta

200

{
  "success": true,
  "data": { },
  "message": "<mensaje de RENAP>",
  "responseCode": 200
}

Campo	Qué es
success	true cuando el status de RENAP fue 200.
data	Los datos que devuelve RENAP. Su forma la define RENAP, no Tributax.
message	El mensaje de RENAP, tal cual.
responseCode	El código que RENAP pone dentro de su payload. No es el status HTTP.

:::caution responseCode y el status HTTP son dos valores distintos El status HTTP de esta respuesta es el status HTTP con el que contestó RENAP; responseCode es un campo del cuerpo de RENAP. Normalmente coinciden, pero no tienen por qué: si RENAP responde 200 con un responseCode de error, recibirás un 200 con success: true —porque success se calcula del status HTTP, no del responseCode— y el detalle del fallo solo estará en message y responseCode.

Comprueba responseCode además del status HTTP. En /rtu/nits no pasa: allí el status sí replica el responseCode. :::

Límite: 30 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.

Recuerda que el contador vive en memoria del proceso: el límite nominal no es una garantía de capacidad.

Errores

Situación	Status	Cuerpo
Falta el CUI	400	{"error":"CUI is required"}
Sin credenciales de integración	403	{"error":"Integration authentication required."}
RENAP no habilitado en tu integración	403	{"error":"RENAP access not enabled."}
Más de 30 consultas en un minuto	429	{"error":"Rate limit exceeded."}
Fallo al consultar RENAP	500	{"success":false,"error":"<detalle>"}

Cada consulta queda registrada

Se registra la integración, el endpoint, el status, el tiempo de respuesta, el CUI consultado 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.