Guía técnica
Consultar el Registro Nacional de Costa Rica desde código
El Registro Nacional no publica un API. Si necesita los datos de un vehículo dentro de su sistema, tiene dos caminos: automatizar el sitio web usted mismo, o llamar a uno que ya lo hace. Esta página explica en detalle lo primero, porque es la decisión que conviene tomar informado.
Escrito por quien mantiene esa automatización en producción. Los números y los obstáculos de abajo salen del código que la sostiene, no de una estimación.
Qué hay del otro lado
El sitio de consultas del Registro Nacional es una aplicación JavaServer Faces. Eso decide casi todo lo demás:
-
El estado vive en el servidor
Cada petición carga un
javax.faces.ViewStateque hay que extraer de la respuesta anterior y devolver en la siguiente. No se puede pedir la página de resultados directamente: hay que caminar la secuencia —abrir el formulario, autenticarse, navegar, enviar— en orden y con la misma sesión. -
Campos ocultos que cambian
Además del ViewState, el formulario lleva campos generados cuyo nombre varía. Hay que localizarlos en el HTML de cada respuesta, no cablearlos.
-
Hay un WAF delante
Cuando algo en la petición no le gusta, la respuesta no es un error legible: es una página que dice Request Rejected. Distinguir eso de una consulta sin resultados es trabajo aparte, y confundirlos significa cobrarle a un cliente por una consulta que nunca se hizo.
-
Cuenta con credenciales, y con tope
La consulta exige sesión iniciada, y una cuenta soporta unas 9 consultas cada 2 minutos antes de que la bloqueen. Son 4,5 por minuto. Si su volumen supera eso, necesita varias cuentas y algo que reparta entre ellas sin pasarse con ninguna.
El parser es lo que se rompe
Lo anterior se resuelve una vez. Lo que no termina nunca es leer el HTML del resultado.
El Registro no avisa cuando una placa no existe: devuelve la misma página con todos los campos en NO INDICADO. Sin una comprobación específica, una placa inexistente se ve exactamente igual que una consulta buena, y su sistema guarda un vehículo fantasma.
Y hay una trampa peor, de las que solo se descubren cuando un cliente reclama: los
estados registrales —gravámenes, anotaciones, infracciones— tienen tres
valores posibles, no dos. El Registro puede decir que sí, decir que no, o no decir nada.
Si su código colapsa los dos últimos en un false,
va a informar que un vehículo está libre de gravámenes cuando en realidad no se pudo
determinar. Eso, en una compraventa, es un problema de verdad.
Lo que cambia sin avisar
El inventario completo
Puesto en lista, esto es lo que hay que escribir y después mantener:
| Pieza | Por qué hace falta |
|---|---|
| Cliente HTTP con cookies por sesión | El estado de JSF no sobrevive sin la misma sesión |
| Extracción de ViewState y campos ocultos | Cambian en cada respuesta |
| Secuencia de navegación | No se puede saltar al resultado |
| Detección del WAF | Su respuesta no es un error legible |
| Pool de cuentas con reparto | Una sola cuenta da 4,5 consultas por minuto |
| Control de ventana por cuenta | Pasarse del tope la bloquea |
| Parser de cada sección | Vehículo, motor, propietarios, situación registral |
| Detección de placa inexistente | El Registro no lo dice: devuelve todo en NO INDICADO |
| Tres estados en gravámenes | Colapsarlos informa vehículos libres que no lo están |
| Vigilancia de respuestas parciales | El sitio cambia y el parser deja de ver secciones |
| Interruptor de corte | Para dejar de responder cuando el parser está degradado |
| Reintentos y tiempos de espera | El Registro tarda entre 3 y 10 segundos y a veces no responde |
En nuestra implementación eso son más de mil líneas solo en la capa que habla con el Registro, sin contar la contabilidad ni las pruebas. Y el costo real no es escribirlas: es que hay que atenderlas cada vez que el sitio del Registro cambia.
Cuándo sí conviene hacerlo usted
No siempre es mala idea, y sería deshonesto decir lo contrario:
- Si es una consulta ocasional y manual, el sitio del Registro ya sirve.
- Si su volumen es enorme y sostenido, en algún punto le sale a cuenta operar su propio pool de cuentas.
- Si necesita datos que este API no expone, no le sirve de nada.
Para todo lo demás —integrar la consulta dentro de un sistema que ya tiene que hacer otras cosas— es una llamada HTTP contra el mantenimiento indefinido de un scraper.
La misma consulta, en una llamada
curl 'https://rnp.egobytes.com/api/v1/vehiculos/placa/DEMO001' \ -H 'X-API-Key: rnp_su_clave'
Todo lo de la tabla de arriba está del otro lado de esa llamada: el pool, el reparto, la detección del WAF, los tres estados, el interruptor. Si el Registro falla, la respuesta lo dice con un código que su código puede distinguir, y esa consulta no se cobra.
Sea cual sea el camino que elija: lo que obtiene del Registro Nacional es información publicada, no certificada. No sustituye una certificación registral, y para un trámite legal se requiere el documento oficial.