Registro Nacional CR

Referencia · v1.0.0

Documentación del API

Una llamada HTTP con su clave en un encabezado. Sin OAuth, sin tokens que renovar, sin SDK obligatorio.

Empezar

  1. 1

    Cree su cuenta

    Gratis, sin tarjeta. Incluye 10 consultas.

  2. 2

    Genere una clave

    En su portal, sección Credenciales. Se muestra completa una sola vez.

  3. 3

    Llame al endpoint

    Con la clave en el encabezado X-API-Key.

¿Evaluando si automatizar el sitio del Registro usted mismo? Lo que implica hacerlo a mano, contado por quien lo mantiene en producción.

Su primera consulta 
# Una placa de prueba: no toca el Registro ni consume saldo
curl 'https://rnp.egobytes.com/api/v1/vehiculos/placa/DEMO001' \
  -H 'X-API-Key: rnp_su_clave'

Autenticación

Cada petición lleva su clave en el encabezado X-API-Key. También se acepta Authorization: Bearer para los clientes HTTP que solo saben hablar así.

Las dos formas 
X-API-Key: rnp_su_clave

# o bien
Authorization: Bearer rnp_su_clave

No la mande por la URL

Pasar la clave como ?api_key= todavía funciona, pero está obsoleto y responde con una cabecera de advertencia. Las URL quedan escritas en registros de servidores, historiales y encabezados Referer: una clave ahí es una clave filtrada.

Endpoints

Dos, y ambos devuelven exactamente la misma forma.

GET /vehiculos/placa/{placa}

Busca por placa. Sin el parámetro clase se busca en particulares; para carga liviana envíe ?clase=CL y en la ruta solo el número, sin el CL.

GET /vehiculos/vin/{vin}

Busca por número de VIN o chasis. No lleva parámetro de clase.

Los dos, en cURL 
# Particular
curl 'https://rnp.egobytes.com/api/v1/vehiculos/placa/BJK123' \
  -H 'X-API-Key: rnp_su_clave'

# Carga liviana: el CL va en el parámetro, no en la placa
curl 'https://rnp.egobytes.com/api/v1/vehiculos/placa/272490?clase=CL' \
  -H 'X-API-Key: rnp_su_clave'

# Por VIN
curl 'https://rnp.egobytes.com/api/v1/vehiculos/vin/8AJHA8CD704309461' \
  -H 'X-API-Key: rnp_su_clave'

La respuesta

200 OK 
{
  "datos": {
    "vehiculo":     { "marca": "TOYOTA", "estilo": "COROLLA", "ano_fabricacion": "2019" },
    "motor":        { "cilindrada": "1800 C.C", "combustible": "GASOLINA" },
    "propietarios": [{ "nombre": "...", "numero_identificacion": "..." }],
    "gravamenes":   { "posee": true, "items": [ ... ] },
    "anotaciones":  { "posee": false, "items": [] }
  },
  "completitud": "completa",
  "cobrada":     true,
  "saldo":       { "total": 248, "plan": 248, "creditos": 0 },
  "request_id":  "01J8..."
}

posee tiene tres estados, no dos

true y false son lo que el Registro afirma. null significa que no lo dijo, y tratarlo como un «no» es afirmar que un vehículo está libre de gravámenes cuando en realidad no se sabe. Distíngalos siempre.

Un campo que el Registro no publica llega como null. Nunca se sustituye por un valor supuesto ni por una cadena vacía.

Saldo y cobro

Se descuenta una consulta por cada respuesta completa. Todo lo demás —el Registro caído, una respuesta a medias, un límite excedido— no se cobra, y cada respuesta lo dice.

Situación cobrada
Respuesta completa true
El Registro no tiene ese vehículo (404) true
Respuesta parcial: faltaron secciones false
El Registro no respondió o rechazó (502, 504) false
Sin capacidad momentánea (503) false
Límite por minuto excedido (429) false
Placa de prueba DEMO* false

El 404 se cobra porque el Registro sí respondió: la consulta se hizo y gastó un cupo real. Es el único error que descuenta.

El saldo viaja también en encabezados, para quien no quiera abrir el cuerpo:

Encabezados de saldo 
X-Consultas-Restantes: 248
X-Consultas-Plan:      248
X-Consultas-Creditos:  0
X-Plan-Renueva:        2026-09-27

Vehículos de prueba

Estas placas devuelven datos ficticios sin tocar el Registro y sin consumir saldo. Úselas para programar su integración: detrás de una placa real hay una persona con nombre y cédula.

DEMO001 Vehículo con dos gravámenes activos
DEMO002 Vehículo con anotaciones y un levantamiento
DEMO003 Vehículo sin gravámenes ni anotaciones
DEMO404 Placa inexistente: responde 404 vehiculo_no_encontrado

Límites

Cada plan define su propio máximo de consultas por minuto. Al superarlo se recibe 429 con los segundos de espera en error.reintentar_en. Esa consulta no se cobra.

Guarde en caché lo que consulte

Los datos de un vehículo casi no cambian de un día para otro. Guardar cada respuesta al menos 24 horas de su lado le baja la factura y le quita dependencia de que el Registro esté disponible en ese instante.

Errores

Todos comparten la misma forma. El texto de message puede cambiar; code no. Ramifique siempre por el código.

402 · saldo_agotado 
{
  "error": {
    "code":        "saldo_agotado",
    "message":     "Se agotó la cuota del plan y no hay créditos disponibles.",
    "doc_url":     "https://rnp.egobytes.com/docs/errores#saldo_agotado",
    "recarga_url": "https://rnp.egobytes.com/portal/recargar"
  },
  "cobrada": false
}
401 credencial_invalida 403 credencial_revocada 403 cuenta_suspendida 402 prueba_finalizada 402 saldo_agotado 404 vehiculo_no_encontrado 429 limite_excedido 502 origen_no_disponible 503 sin_capacidad 504 tiempo_agotado

Referencia completa de errores →

OpenAPI y SDKs

La especificación completa está publicada. Impórtela en Postman, en su editor, o genere un cliente con ella.

JSON openapi.json

composer

PHP

composer require egobytes/rnp-api

npm

JavaScript · TypeScript

npm install @egobytes/rnp-api

¿Algo no cuadra?

Escriba a [email protected] con el request_id de la respuesta. Con eso encontramos exactamente qué pasó en esa consulta.