Documentación del API

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.

# 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í.

X-API-Key: rnp_su_clave

# o bien
Authorization: Bearer rnp_su_clave

Endpoints

Dos devuelven el vehículo completo. El tercero solo pregunta el vencimiento de la revisión técnica y no descuenta saldo.

# 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'

# Motocicleta: igual, la M va en el parámetro
curl 'https://rnp.egobytes.com/api/v1/vehiculos/placa/123456?clase=MOT' \
  -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'

# Solo el vencimiento de Dekra. No descuenta saldo
curl 'https://rnp.egobytes.com/api/v1/dekra/placa/BJK123' \
  -H 'X-API-Key: rnp_su_clave'

# La historia registral: movimientos, traspasos y gravámenes históricos. Cuesta una consulta
curl 'https://rnp.egobytes.com/api/v1/vehiculos/placa/BJK123/historial' \
  -H 'X-API-Key: rnp_su_clave'

La respuesta

{
  "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": [] },
    "inspeccion_tecnica": { "mes": 10, "mes_nombre": "octubre", "desde_mes": 9 },
    "vencimiento_dekra": { "fecha": "2028-02-29", "placa": "BJK120", "vigente": true, "estado": "VIGENTE" },
    "estimaciones": { "marchamo": { "total": 373043, "referencial": true, ... }, "traspaso": { "total": 809334, ... } },
    "origen": { "pais_fabricacion": "JAPAN", "fabricante": "TOYOTA", "anio_modelo": 2019 }
  },
  "completitud": "completa",
  "cobrada":     true,
  "saldo":       { "total": 248, "plan": 248, "creditos": 0 },
  "request_id":  "01J8..."
}

Lo que el Registro no publica no se inventa: el campo no viene en la respuesta o llega en null. Nunca se sustituye por un valor supuesto ni por una cadena vacía.

Todos los campos de vehiculo y motor

Van como texto, tal como los imprime el Registro y con su unidad cuando la tiene, por ejemplo "1,500.00 KG" o "22 KW". Cuáles vienen depende del vehículo: el Registro no los publica todos para todos. La descripción de cada uno está en la especificación OpenAPI.

vehiculo

placa marca estilo categoria capacidad ano_fabricacion color estado_actual valor_hacienda moneda vin chasis serie inscripcion carroceria traccion peso_vacio peso_neto pbv peso_remolque longitud cabina techo uso estado_tributario clase_tributaria valor_contrato numero_registral convertido

motor

numero_motor marca serie modelo cilindrada cilindros potencia combustible fabricante procedencia

El detalle de los levantamientos

Cuando levantamientos.posee es true, cada levantamiento trae en items la fila que imprime el Registro, típicamente de un accidente de tránsito con proceso judicial. Todo va como texto, igual que en los gravámenes; solo en_tramite se deduce, y es true cuando todavía no tiene fecha de levantamiento. Lo que la fila no trae llega en null. La placa DEMO002 del sandbox trae uno, sin gastar saldo.

"levantamientos": {
  "posee": true,
  "items": [{
    "fecha_inclusion": "15-ENE-2024", "rollo_inclusion": "12", "imagen_inclusion": "345",
    "fecha_levantamiento": "20-FEB-2024", "rollo_levantamiento": "13", "imagen_levantamiento": "346",
    "boleta": "2-024-1234", "sumaria": "24-001-234-TR",
    "autoridad_judicial": "JUZGADO DE TRANSITO DE PRUEBA", "observacion": null,
    "en_tramite": false
  }]
}

La historia registral

GET /vehiculos/placa/{placa}/historial devuelve lo que publica «Historia de Bienes» del Registro: los movimientos en orden cronológico con su cita y su fecha, los traspasos (el histórico de derechos: un renglón por derecho inscrito) y los gravamenes_historicos, los gravámenes y afectaciones que el vehículo ha tenido, vigentes o no. Cada traspaso trae en propietario a quien adquirió el vehículo con ese documento, con las mismas claves de persona que propietarios más su estado civil; una cuenta configurada sin datos del propietario recibe el nombre, la identificación y el estado civil en null. cambios_desde_ultima_vez compara con la historia que guardamos la última vez que alguien consultó esa placa.

El historial completo, con todos sus dueños, cuesta una consulta. Si algún dueño no se pudo leer, la respuesta sale parcial, lo dice en secciones_ausentes y no se cobra. La placa DEMO001 del sandbox trae dos cambios de dueño, una corrección de datos del dueño, una prenda y una denuncia de tránsito, sin gastar saldo.

La categoría de cada acto

El Registro describe cada acto con texto libre y no publica la lista, así que cada renglón de movimientos y de traspasos trae además categoria. El texto original sigue en descripcion o en tipo, tal cual. Para relacionar un renglón con otro, crúcelos por su cita —tomo, asiento y secuencia—, no contando textos.

No todo renglón de traspasos es un cambio de dueño. total_traspasos cuenta los renglones y total_cambios_de_dueno los cambios de dueño de verdad; un acto OTRO se cuenta como cambio, para no afirmar «dueño único» sin certeza. Si nunca cambió de dueño, dueno_unico es true y nota lo dice.

{
  "datos": {
    "placa": "BJK123",
    "inscripcion": { "tomo": "2019", "asiento": "00123456", "secuencia": "001", "fecha": "14-mar-2019" },
    "gravamenes_historicos": [
      { "tomo": "2021", "asiento": "00998877", "secuencia": "002", "tipo": "CONTRATO PRENDARIO", "categoria": "PRENDA" },
      { "tomo": "2001", "asiento": "00071234", "secuencia": "001", "tipo": "CANCELACION DE CONCESION DE TAXI (MOPT) LEY 7969 22-12-1999", "categoria": "AFECTACION" }
    ],
    "traspasos": [
      { "tomo": "2019", "asiento": "00123456", "secuencia": "001", "tipo": "TRASPASO DE UN BIEN MUEBLE", "categoria": "CAMBIO_DE_DUENO",
        "propietario": { "nombre": "PERSONA DE EJEMPLO", "tipo_identificacion": "CEDULA FISICA", "numero_identificacion": "100000001",
                         "estado_civil": "SOLTERO", "derecho": "DOMINIO", "causa_adquisitiva": "ONEROSA", "proporcion": "1.0/1.0",
                         "fecha_constitucion": "14-mar-2019", "adquisicion": { "tomo": "2019", "asiento": "00123456", "secuencia": "001", "fecha": "13-mar-2019" } } },
      { "tomo": "2022", "asiento": "00334455", "secuencia": "001", "tipo": "TRASPASO DE UN BIEN MUEBLE", "categoria": "CAMBIO_DE_DUENO", "propietario": { "nombre": "EMPRESA DE EJEMPLO S.A.", "...": "..." } },
      { "tomo": "2024", "asiento": "00556677", "secuencia": "001", "tipo": "MODIFICACIÓN DE DATOS DE PROPIETARIO", "categoria": "DATOS_DEL_DUENO", "propietario": { "nombre": "EMPRESA DE EJEMPLO S.A.", "...": "..." } }
    ],
    "movimientos": [
      { "tomo": "2015", "asiento": "00011223", "secuencia": "001", "subsecuencia": "000", "descripcion": "INSCRIPCION DE UN BIEN MUEBLE", "fecha": "03-jun-2015", "categoria": "INSCRIPCION" },
      { "tomo": "2021", "asiento": "00998877", "secuencia": "002", "subsecuencia": "000", "descripcion": "INSCRIPCION DE CONTRATO PRENDARIO", "fecha": "05-ago-2021", "categoria": "PRENDA" },
      { "tomo": "2022", "asiento": "00334455", "secuencia": "001", "subsecuencia": "000", "descripcion": "TRASPASO DE UN BIEN MUEBLE", "fecha": "20-ene-2022", "categoria": "CAMBIO_DE_DUENO" },
      { "tomo": "2024", "asiento": "00556677", "secuencia": "001", "subsecuencia": "000", "descripcion": "MODIFICACIÓN DE DATOS DE PROPIETARIO", "fecha": "08-may-2024", "categoria": "DATOS_DEL_DUENO" }
    ],
    "total_traspasos": 3,
    "total_cambios_de_dueno": 2,
    "dueno_unico": false,
    "nota": null,
    "cambios_desde_ultima_vez": { "primera_vez": false, "vista_por_ultima_vez_en": "2026-09-01T10:00:00-06:00", "traspasos_nuevos": 1, "gravamenes_nuevos": 0, "movimientos_nuevos": 1 }
  },
  "cobrada": true,
  "saldo": { "total": 247, "plan": 247, "creditos": 0 }
}

Lo que se deduce del vehículo

Junto a lo que publica el Registro, datos trae claves que se calculan a partir de ello. No gastan consultas, no cambian ninguna de las claves anteriores y, cuando no se pueden calcular, llegan en null.

inspeccion_tecnica

Cuándo toca la inspección técnica vehicular (Dekra). El mes lo fija el último dígito de la placa —1 enero, 2 febrero … 9 setiembre, 0 octubre— y va en mes y mes_nombre; en desde_mes va el mes anterior, desde el que ya se puede hacer. null si la placa no termina en dígito.

vencimiento_dekra

El día en que vence esa revisión, el que tiene registrado Dekra para la placa. fecha es un día AAAA-MM-DD y placa es con la que contestó, sin espacios. Llega en null si Dekra no la publica o la consulta falla. Dekra no calcula la fecha al momento: contesta lo que registró la última vez que revisó la placa, y calculada_el dice cuándo fue. Tras una revisión favorable la actualiza con la próxima (tipo: REVISION); tras una desfavorable deja el plazo de un mes para la reinspección (tipo: REINSPECCION) y no siempre lo actualiza cuando el vehículo la pasa. Por eso, para decidir, use estado y no vigente: VIGENTE, VENCIDA cuando pasó una revisión que no se hizo, o SIN_CONFIRMAR cuando lo que pasó fue un plazo de reinspección. nota trae el texto para mostrar. No reemplaza a inspeccion_tecnica: aquella dice el mes que toca por el último dígito; esta, la fecha registrada. Cuando el estado es SIN_CONFIRMAR, el mes de inspeccion_tecnica es la mejor guía. La placa DEMO002 enseña ese caso. También se puede pedir sola, sin el resto del vehículo, en /dekra/placa/{placa}.

estimaciones

Cuánto costarían, más o menos, el marchamo del año y el traspaso, calculados sobre el valor fiscal que publica el Registro (base) con las tarifas oficiales de ese anio: el impuesto a la propiedad por tramos, el seguro obligatorio según el tipo_vehiculo y los rubros fijos; el impuesto de traspaso, los timbres, los honorarios notariales por el arancel y su IVA. Cada una trae sus rubros en colones, que suman el total. null cuando el Registro no publica el valor fiscal.

origen

De dónde viene el vehículo según su VIN, decodificado por el vPIC de la NHTSA (la agencia de seguridad vial de Estados Unidos): pais_fabricacion, ciudad_planta, estado_planta, fabricante y anio_modelo. Sabe mucho de lo que se vendió en ese mercado y poco del resto: cuando no conoce el VIN, o el VIN no tiene 17 caracteres, llega en null; y cada campo puede venir en null por separado.

imagen

Una foto ilustrativa del mismo modelo y año, de Wikimedia Commons. No es la foto del vehículo consultado. Solo se eligen fotos con licencias que permiten el uso comercial —dominio público, CC0, CC BY o CC BY-SA— y esas licencias piden dar crédito: si la muestra, muestre también atribucion, idealmente enlazada a pagina. Trae url en tamaño web, url_original, licencia y autor. Entre las del mismo modelo y año se prefiere la del color del vehículo, y mismo_color dice si se logró: true, false si no hay una de ese color, o null si el Registro no trae un color que se pueda buscar. Es aproximado, porque sale de cómo está clasificada la foto en Commons. La clave llega en null cuando no hay una foto del modelo y año que sirva. La placa DEMO001 trae una.

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.

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:

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.

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.

Errores

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

{
  "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
}

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.

composer require egobytes/rnp-api

npm install @egobytes/rnp-api