· Documentación oficial ·

VehiclesVE.api

La primera API REST de catálogo vehicular curada para Venezuela y LATAM. Datos reales, aliases locales, historial desde 1984.

26

Marcas

88

Modelos

140

Generaciones

129

Aliases locales

Quick start

bash

# 1 — Regístrate (gratis, sin tarjeta)
curl -X POST https://vehiclesveapi.red111.dev/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"registration":{"name":"Tu Nombre","email":"tu@email.com"}}'

# 2 — Usa tu API key
curl "https://vehiclesveapi.red111.dev/api/v1/vehicles/search?q=machito&market=VE" \
  -H "X-Api-Key: TU_API_KEY"

Autenticación

Todos los endpoints del catálogo requieren un API key. Los endpoints admin requieren una secret distinta.

X-Api-Key

Header · Endpoints públicos

Obtenida al registrarse en POST /register. Se envía en el header HTTP en cada request.

curl "https://vehiclesveapi.red111.dev/api/v1/vehicles" \
-H "X-Api-Key: TU_API_KEY"

X-Admin-Secret

Header · Solo endpoints admin

Variable de entorno del servidor. No es pública. Usada para gestión de clientes, analytics y NHTSA sync.

curl "https://vehiclesveapi.red111.dev/api/v1/admin/analytics" \
-H "X-Admin-Secret: $ADMIN_SECRET"

Planes y cuotas

Free · Trial

500

requests totales · 30 días

Starter

50,000

requests / mes · se renuevan

Enterprise

∞

ilimitado · custom

Errores

Manejo de errores

Todos los errores devuelven un objeto JSON consistente con status: "error" y un objeto error con code y message.

JSON · Error response

{
  "status": "error",
  "error": {
    "code":    "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Código
Significado

200OK — éxito

201Created — recurso creado

401Unauthorized — API key inválida o ausente

404Not Found — recurso no existe

422Unprocessable — parámetros inválidos

429Too Many Requests — rate limit alcanzado (Retry-After en header)

Paginación

Todos los endpoints de lista usan paginación por página. Los parámetros page y per_page son opcionales (default: página 1, 25 por página, máx. 100).

JSON · meta.pagination

"meta": {
  "pagination": {
    "page":     1,
    "per_page": 25,
    "total":    140,
    "pages":    6,
    "next":     2,
    "prev":     null
  }
}

Catálogo

Marcas, modelos, generaciones de vehículos y sus especificaciones técnicas.

GET

/makes

Listar todas las marcas

Query params

Nombre	Tipo	Ubicación	Descripción
page	integer	query	Número de página (default: 1)
per_page	integer	query	Resultados por página, máx. 100 (default: 25)

Ejemplo de request

curl

curl "https://vehiclesveapi.red111.dev/api/v1/makes" \
  -H "X-Api-Key: TU_API_KEY"

Respuesta · 200 OK

JSON

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Toyota",
      "slug": "toyota",
      "logo_url": "https://logo.clearbit.com/toyota.com",
      "country_origin": "Japan",
      "models_count": 11
    }
    // … 25 más
  ],
  "meta": { "pagination": { "total": 26, "pages": 2 } }
}

GET

/makes/:slug/models

Modelos de una marca

Nombre	Tipo	Ubicación	Descripción
slugreq	string	path	Slug de la marca: `toyota`, `chevrolet`, `ford`…
page	integer	query	Número de página
per_page	integer	query	Resultados por página (máx. 100)

curl

curl "https://vehiclesveapi.red111.dev/api/v1/makes/mitsubishi/models" \
  -H "X-Api-Key: TU_API_KEY"

Respuesta · 200 OK

JSON

{
  "status": "success",
  "data": [
    { "id": 12, "name": "L200", "slug": "l200", "body_type": "pickup" },
    { "id": 13, "name": "Montero Sport", "slug": "montero-sport", "body_type": "suv" },
    { "id": 14, "name": "Lancer", "slug": "lancer", "body_type": "sedan" }
  ],
  "meta": { "pagination": { "total": 4, "pages": 1 } }
}

GET

/models/:slug/years

Rangos de años disponibles para un modelo

Nombre	Tipo	Ubicación	Descripción
slugreq	string	path	Slug del modelo: `hilux`, `corolla`…

curl

curl "https://vehiclesveapi.red111.dev/api/v1/models/hilux/years" \
  -H "X-Api-Key: TU_API_KEY"

Respuesta · 200 OK

JSON

{
  "status": "success",
  "data": {
    "model": { "name": "Hilux", "slug": "hilux", "body_type": "pickup" },
    "year_ranges": [
      { "from": 1997, "to": 2004 },
      { "from": 2005, "to": 2015 },
      { "from": 2016, "to": null }
    ]
  }
}

GET

/vehicles

Listar y filtrar vehículos

El endpoint principal del catálogo. Soporta múltiples filtros combinables.

Nombre	Tipo	Descripción
market	string	VE · CO · EC · PE — Mercado a filtrar
make	string	Slug de la marca: `toyota`
model	string	Slug del modelo: `hilux`
year	integer	Vehículos disponibles en ese año exacto
fuel	string	gasoline · diesel · hybrid · electric · gas
transmission	string	manual · automatic · cvt · semi_auto
drive_type	string	fwd · rwd · awd · 4wd
min_hp / max_hp	integer	Rango de potencia en HP (min ≤ max)
min_cc / max_cc	integer	Rango de cilindrada en cc (min ≤ max)
doors / passengers	integer	Número de puertas / pasajeros
page / per_page	integer	Paginación (default: 1 / 25)

curl · Toyota diesel Venezuela

curl "https://vehiclesveapi.red111.dev/api/v1/vehicles?market=VE&make=toyota&fuel=diesel" \
  -H "X-Api-Key: TU_API_KEY"

Respuesta · 200 OK

JSON

{
  "status": "success",
  "data": [{
    "id": 7,
    "year_from": 1990,  "year_to": null,
    "engine_type": "inline",  "engine_cylinders": 6,
    "engine_displacement_cc": 4200,
    "fuel_type": "diesel",  "transmission_type": "manual",
    "horsepower": 131,  "torque_nm": 300,
    "drive_type": "4wd",  "doors": 4,  "passengers": 5,
    "model": { "name": "Land Cruiser 70", "body_type": "pickup",
              "make": { "name": "Toyota", "slug": "toyota" } },
    "popularity_score": 92,
    "vehicle_aliases": [
      { "alias_name": "Machito", "market": "VE" }
    ]
  }]
}

GET

/vehicles/:id

Ficha técnica completa de un vehículo

Nombre	Tipo	Ubicación	Descripción
idreq	integer	path	ID del vehículo
market	string	query	Filtrar aliases y popularidad por mercado

curl

curl "https://vehiclesveapi.red111.dev/api/v1/vehicles/7?market=VE" \
  -H "X-Api-Key: TU_API_KEY"

GET

/vehicles/stats

Estadísticas globales del catálogo

Respuesta cacheada 1 hora. No requiere parámetros adicionales.

curl

curl "https://vehiclesveapi.red111.dev/api/v1/vehicles/stats" \
  -H "X-Api-Key: TU_API_KEY"

Respuesta · 200 OK

JSON

{
  "data": {
    "total_makes":    26,
    "total_models":   88,
    "total_vehicles": 140,
    "markets_count":  1,
    "by_fuel_type": { "gasoline": 110, "diesel": 30 },
    "by_drive_type": { "fwd": 65, "4wd": 52, "rwd": 8, "awd": 15 },
    "by_body_type": {  "sedan": 48, "suv": 45, "pickup": 30, "hatchback": 14 }
  }
}

Búsqueda por alias

GET

/vehicles/search

Buscar vehículo por alias local

La búsqueda es por nombre de alias, no por nombre técnico del vehículo. Máximo 100 caracteres. Devuelve 422 si el query es más largo.

Nombre	Tipo	Descripción
qreq	string	Alias o nombre local a buscar. Ej: `kavak`, `machito`, `tsuru`
market	string	Filtrar aliases por mercado: `VE`
page / per_page	integer	Paginación

curl · buscar "kavak"

curl "https://vehiclesveapi.red111.dev/api/v1/vehicles/search?q=kavak&market=VE" \
  -H "X-Api-Key: TU_API_KEY"

Respuesta · 200 OK

JSON

{
  "status": "success",
  "data": [{
    "id": 42,
    "year_from": 1997, "year_to": 2004,
    "engine_displacement_cc": 2700,
    "fuel_type": "gasoline",
    "transmission_type": "manual",
    "horsepower": 150, "drive_type": "4wd",
    "model": { "name": "Hilux", "make": { "name": "Toyota" } },
    "popularity_score": 88,
    "vehicle_aliases": [
      { "alias_name": "Kavak",       "market": "VE" },
      { "alias_name": "Hilux Kavak", "market": "VE" }
    ]
  }]
}

Mercados

GET

/markets

Mercados LATAM activos

Respuesta · 200 OK

JSON

{
  "data": [
    { "market": "VE", "name": "Venezuela", "active_vehicles": 140 }
  ]
}

Registro

POST

/register

Crear cuenta y obtener API key

El API key se muestra UNA sola vez en la respuesta y no se puede recuperar. Guárdala inmediatamente. También la recibirás por email.

Campo	Tipo	Descripción
registration.namereq	string	Nombre de la persona u organización
registration.emailreq	string	Email único — se usa para identificar la cuenta

curl · POST /register

curl -X POST "https://vehiclesveapi.red111.dev/api/v1/register" \
  -H "Content-Type: application/json" \
  -d '{"registration":{"name":"Acme Corp","email":"dev@acme.com"}}'

Respuesta · 201 Created

JSON

{
  "status": "success",
  "data": {
    "message":  "Registration successful. Copy your API key now — it will not be shown again.",
    "api_key":  "97875c80aa0d462c12d076781d25334ec0156e...",
    "client": {
      "plan":             "free",
      "monthly_limit":    500,
      "trial_expires_at": "2026-05-24T00:00:00.000Z"
    }
  }
}

Uso y cuotas

GET

/usage

Cuota actual del mes

Respuesta · 200 OK

JSON

{
  "data": {
    "plan":                 "starter",
    "requests_this_month":  1240,
    "monthly_limit":        50000,
    "quota_percentage":     2.48,
    "quota_exceeded":       false,
    "rate_limit_per_hour":  1000,
    "last_used_at":         "2026-04-24T21:44:17.000Z"
  }
}

GET

/usage/history

Historial de uso últimos 12 meses

Respuesta · 200 OK

JSON

{
  "data": [
    {
      "month":               "2026-04",
      "requests":           1240,
      "errors":             3,
      "avg_response_time_ms": 45
    }
  ]
}

Admin · API Keys

Gestión de clientes (Admin)

Requieren el header X-Admin-Secret. No son endpoints públicos.

POST

/api_keys

Crear cliente con plan específico

Campo	Tipo	Descripción
api_client.namereq	string	Nombre del cliente
api_client.emailreq	string	Email único
api_client.planreq	string	free · starter · enterprise
api_client.rate_limit_per_hour	integer	Override del rate limit por hora

PATCH

/api_keys/:id/rotate

Rotar API key de un cliente

La key anterior queda invalidada inmediatamente. La nueva se muestra una sola vez en la respuesta.

DELETE

/api_keys/:id

Revocar API key de un cliente

Respuesta · 200 OK

JSON

{ "status": "success", "data": { "id": 5, "active": false } }

Admin · Sistema

Analytics y Sync

Endpoints de administración del sistema. Requieren X-Admin-Secret.

GET

/admin/analytics

Analytics de la plataforma

Respuesta · 200 OK (resumen)

JSON

{
  "data": {
    "overview": {
      "total_clients":        10,
      "active_clients":       8,
      "requests_this_month":  4820,
      "avg_response_ms":      136.3
    },
    "by_plan":     [ /* … */ ],
    "top_clients": [ /* … */ ],
    "top_endpoints":[ /* … */ ],
    "error_summary":{ "total_errors": 3 }
  }
}

POST

/admin/sync

Disparar sync NHTSA en background

El job corre de forma asíncrona vía Solid Queue. Tarda ~8 minutos en sincronizar todas las marcas prioritarias desde NHTSA vPIC. También se ejecuta automáticamente el día 2 de cada mes.

Respuesta · 200 OK

JSON

{
  "data": {
    "message": "NHTSA sync enqueued. Worker will process all priority makes.",
    "makes":   ["Toyota", "Chevrolet", "Ford", /* + 11 más */]
  }
}