Endpoint: catálogo de marcas, modelos y versiones
El catálogo vehicular es la lista de todas las marcas, líneas y versiones de vehículos que circulan en Colombia, con el valor comercial de cada una por año. Este endpoint lo devuelve en cascada para poblar un selector: marca, luego año, luego la versión concreta con su código, su precio y su ficha técnica. No pide placa ni documento del propietario.
¿Qué cubre el catálogo?
Para automóviles hay 130 marcas y cerca de 2.950 líneas, con años de 1970 a 2027. El catálogo se divide en seis categorías —automóvil, pickup y camioneta de carga, motocicleta y motocarro, pesado de carga, bus y remolque— y cada una tiene su propio universo de marcas: las de moto no aparecen entre las de automóvil.
El nivel útil no es la línea sino la versión. Un Toyota Corolla 2024 no es un dato: son 44 versiones distintas, cada una con su código y su valor. Por eso el endpoint no se detiene en la referencia.
¿Cómo se encadena la consulta?
Cada llamada devuelve lo necesario para pintar el paso siguiente, y su resultado es la entrada del que viene. Cuatro pasos:
- Sin filtros — las marcas y los años disponibles de la categoría elegida.
- Con
marca— las listas se recortan a esa marca y aparecen susreferencias, que son las líneas. - Con
marcaymodelo— aparecen lasversiones: cada acabado de esa marca en ese año, con código, valor y ficha. - Añadiendo
referencia— acota las versiones a una sola línea.
Las versiones no se devuelven con la marca sola: una marca grande tiene miles y la respuesta sería inmanejable. Hay que acotar por año o por referencia.
Marcas, modelos, referencias y versiones de vehículos en Colombia, en cascada para poblar un selector: sin filtros trae las marcas y los años; con `marca`, sus referencias; con `marca` + `modelo` (o + `referencia`), las versiones. Cada versión trae su código —el mismo que acepta `/api/avaluo-por-codigo`—, el valor de mercado (`valorUsado`), el precio 0km (`valorNuevo`, solo en años que aún se venden nuevos) y la ficha técnica: cilindraje, potencia, airbags, puertas y tracción. No pide placa ni documento del propietario. Cada lista viene `null` cuando su filtro ya está decidido; con `listas=todas` vuelven todas. Un filtro que no existe en el catálogo responde 404 y no cobra.
Cuerpo de la solicitud
{
"marca": "Toyota",
"modelo": "2026"
}| Campo | Tipo | Qué es |
|---|---|---|
| categoria | string | Tipo de vehículo: `automovil` (default, incluye las SUV de pasajeros), `camioneta` (pickup y camioneta de carga), `moto` (incluye motocarro), `carga` (pesado de carga), `bus` (bus, buseta y microbús) o `remolque`. Los tres pesados comparten catálogo de marcas en la fuente, así que al elegir uno la lista de marcas puede incluir las de los otros dos; las versiones sí salen separadas. |
| soloConPrecio | boolean | `true` por defecto: solo devuelve las versiones con valor publicado para el año pedido. En `false` aparecen también las que existen sin precio para ese año (Toyota 2024 pasa de 44 a 401 versiones, casi todas en 0). |
| marca | string | Marca por nombre (`Toyota`) o por id del catálogo (`178`). Sin tildes ni mayúsculas importa. |
| modelo | string | Año del modelo (`2024`). En el catálogo vehicular colombiano «modelo» es el año, no la línea. |
| referencia | string | Referencia/línea por nombre o id, resuelta dentro de la marca elegida. Admite prefijo: `Corolla` encuentra `COROLLA [12] [FL]`. |
| listas | string | `todas` devuelve `marcas`, `modelos` y `referencias` aunque su filtro ya esté decidido. Útil para repintar los tres selectores de un formulario con una sola llamada; por defecto cada lista se omite cuando ya elegiste ese filtro. |
| pagina | number | Página de versiones (default 1). |
| porPagina | number | Versiones por página (default 50, máximo 200). |
| refresh | boolean | Ignora la caché y vuelve a consultar la fuente oficial. Ojo: una consulta refrescada con datos siempre cobra (el hit de caché no). |
Ejemplos por lenguaje
curl -X POST 'https://placapi.com/api/catalogo' \
-H 'x-api-key: pk_live_TU_CLAVE' \
-H 'content-type: application/json' \
-d '{"marca":"Toyota","modelo":"2026"}'const res = await fetch("https://placapi.com/api/catalogo", {
method: "POST",
headers: {
"x-api-key": "pk_live_TU_CLAVE",
"content-type": "application/json",
},
body: JSON.stringify({"marca":"Toyota","modelo":"2026"}),
});
const data = await res.json();import requests
res = requests.post(
"https://placapi.com/api/catalogo",
headers={"x-api-key": "pk_live_TU_CLAVE"},
json={"marca":"Toyota","modelo":"2026"},
)
data = res.json()Respuesta exitosa
{
"source": "catalogo",
"status": "info",
"data": {
"filtros": {
"categoria": {
"nombre": "automovil",
"etiqueta": "Automóvil"
},
"soloConPrecio": true,
"marca": {
"id": 178,
"nombre": "Toyota"
},
"modelo": {
"id": 41009,
"nombre": "2026"
},
"referencia": null
},
"marcas": null,
"modelos": null,
"referencias": [
{
"id": 211000,
"nombre": "Corolla [12] [fl]"
}
],
"versiones": [
{
"codigo": "09033079",
"marca": "TOYOTA",
"referencia": "COROLLA [12] [FL]",
"version": "XE-I HYBRID",
"detalle": "TP 1800CC 7AB ABS",
"linea": "COROLLA [12] [FL] XE-I HYBRID TP 1800CC 7AB ABS",
"modelo": 2026,
"valorUsado": 130600000,
"valorNuevo": 122200000,
"valorComercial": 130600000,
"clase": "AUTOMOVIL",
"categoria": "LIVIANO PASAJEROS",
"tipologia": "SEDAN",
"combustible": "GASOLINA",
"transmision": "4X2",
"tipoCaja": "TIPTRONICA",
"cilindraje": 1798,
"potencia": 168,
"puertas": 4,
"airbags": 7,
"traccion": "DELANTERA",
"capacidadPasajeros": 5,
"peso": 1370
}
],
"paginacion": {
"pagina": 1,
"porPagina": 50,
"paginas": 1,
"total": 4
}
},
"mode": "live",
"fetchedAt": "2026-07-24T15:04:05.000Z"
}Errores y cobro
Cuesta 1 crédito cuando devuelve datos. Códigos posibles: 400 401 402 404 429 500 502 — qué significa cada uno, cuál reintentar y cuál cobra, en errores y rate limits. Autenticación por x-api-key: cómo generar la clave.
Preguntas frecuentes
- ¿Qué diferencia hay entre modelo, referencia y versión?
- En el catálogo vehicular colombiano el modelo es el AÑO (2024, 2025), no la línea. La referencia es la línea comercial: Corolla, Sandero, Duster. La versión es el acabado concreto dentro de esa línea y ese año —XE-I HYBRID, SE-G, GR-S—, y es el nivel que tiene código y precio propios. Dos versiones de la misma línea y el mismo año pueden diferenciarse en varios millones de pesos.
- ¿Qué es el código que trae cada versión?
- Es el identificador de ocho dígitos que la guía de valores del país le asigna a cada versión de vehículo. Las aseguradoras lo usan para tarifar una póliza y los peritos para avaluar. Cada versión que devuelve este endpoint trae el suyo en el campo codigo, y con él se puede pedir el valor directamente al endpoint de avalúo por código, sin resolver la placa.
- ¿Por qué una versión trae dos precios distintos?
- Porque la guía publica dos valores para los modelos que todavía se venden 0km: valorUsado es el valor comercial de mercado —el que se usa para avalúos, primas e impuesto vehicular— y valorNuevo es el precio de lista del vehículo sin estrenar. En un modelo de 2018 solo existe el de usado y valorNuevo sale en 0.
- ¿El catálogo necesita la placa del vehículo?
- No. El catálogo describe modelos, no vehículos concretos, así que no pide placa ni documento del propietario y no consulta el RUNT. Para los datos de un vehículo específico —propietario, SOAT, tecnomecánica, multas— se usan los endpoints de consulta vehicular.
¿Para qué se usa?
- Cotizadores de seguros: los tres selectores de marca, año y versión que pide todo formulario de póliza, con el código que la aseguradora necesita para tarifar.
- Portales de compraventa: publicar un vehículo con marca, línea y versión normalizadas contra el catálogo oficial, en vez de texto libre que después nadie puede filtrar.
- Avalúos y peritajes: el valor de mercado por año y versión, que es la base de una indemnización o de una negociación. Cuando el código ya lo tienes, la API de avalúo por código FASECOLDA devuelve el valor sin pasar por la placa ni por el RUNT.
- Concesionarios y flotas: comparar el precio 0km contra el valor de mercado del mismo modelo para estimar la depreciación.
Última revisión: 10 de agosto de 2026 · PlacApi opera desde Colombia. PlacApi no es una entidad oficial del Gobierno.