{"openapi":"3.0.3","info":{"title":"APIVehículo","version":"1.0.0","description":"## Introducción\n\nAPIVehículo te permite consultar datos técnicos completos de cualquier vehículo a partir de su **matrícula** o **número de bastidor (VIN)**.\n\n---\n\n## Autenticación\n\nTodas las peticiones requieren una API key en la cabecera `Authorization`:\n\n```http\nAuthorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxx\n```\n\nLas API keys tienen el prefijo `av_`. Puedes generar y revocar tus claves desde el **dashboard**.\n\n> ⚠️ Nunca expongas tu API key en código del lado del cliente. Realiza todas las llamadas desde tu backend.\n\n---\n\n## Base URL\n\n```\nhttps://api.apivehiculo.com/v1\n```\n\n---\n\n## Errores\n\nLa API usa códigos HTTP estándar. Los errores devuelven siempre un objeto con `message` y `status`.\n\n| Código | Significado |\n|--------|-------------|\n| `400` | Parámetros incorrectos o faltantes |\n| `401` | API key inválida o ausente |\n| `404` | Recurso no encontrado |\n| `429` | Límite de consultas del plan alcanzado |\n| `500` | Error interno del servidor |\n\n---\n\n## Rate limiting y cuotas\n\nCada plan incluye un número mensual de consultas. Al alcanzar el límite recibirás un `429`. Puedes ampliar tu cuota desde el dashboard sin cambiar de plan.","contact":{"name":"Soporte APIVehículo","url":"https://apivehiculo.com","email":"hola@apivehiculo.com"}},"servers":[{"url":"https://api.apivehiculo.com/v1","description":"Producción"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Vehículos","description":"Consulta de datos técnicos por matrícula o VIN."},{"name":"Usuario","description":"Perfil y estadísticas de uso del usuario autenticado."},{"name":"Suscripción","description":"Estado del plan activo, cuota consumida y fechas de renovación."}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"av_...","description":"API key con prefijo `av_`. Obtenla en el dashboard y pásala como `Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxx`."}},"schemas":{"UserProfile":{"type":"object","properties":{"_id":{"type":"string","example":"664f1a2b3c4d5e6f7a8b9c0d"},"email":{"type":"string","format":"email","example":"usuario@ejemplo.com"},"name":{"type":"string","example":"Juan García"}}},"UserStats":{"type":"object","properties":{"lastHour":{"type":"integer","example":3},"today":{"type":"integer","example":12},"yesterday":{"type":"integer","example":25},"last30Days":{"type":"integer","example":180},"last90Days":{"type":"integer","example":520},"total":{"type":"integer","example":1340}}},"Subscription":{"type":"object","properties":{"_id":{"type":"string","example":"664f1a2b3c4d5e6f7a8b9c0e"},"userId":{"type":"string","example":"664f1a2b3c4d5e6f7a8b9c0d"},"planId":{"type":"string","example":"664f1a2b3c4d5e6f7a8b9c0f"},"status":{"type":"string","enum":["trialing","active","past_due","cancelled","incomplete","incomplete_expired","unpaid"],"example":"active"},"currentPeriodStart":{"type":"string","format":"date-time","example":"2026-05-01T00:00:00.000Z"},"currentPeriodEnd":{"type":"string","format":"date-time","example":"2026-06-01T00:00:00.000Z"},"cancelAtPeriodEnd":{"type":"boolean","example":false},"requestsUsed":{"type":"integer","example":42},"additionalRequests":{"type":"integer","example":0},"planMonthlyRequests":{"type":"integer","example":500},"totalRequests":{"type":"integer","example":500,"description":"planMonthlyRequests + additionalRequests"},"remainingRequests":{"type":"integer","example":458,"description":"totalRequests - requestsUsed (mínimo 0)"},"stripeSubscriptionId":{"type":"string","example":"sub_1QxAbcDeFgHiJkLm","nullable":true},"pendingPlanId":{"type":"string","example":null,"nullable":true},"cancelledAt":{"type":"string","format":"date-time","example":null,"nullable":true}}},"Tire":{"type":"object","properties":{"name":{"type":"string","example":"Front"},"width":{"type":"integer","example":205},"height":{"type":"integer","example":55},"diameter":{"type":"integer","example":16},"loadIndex":{"type":"integer","example":91},"speedIndex":{"type":"string","example":"V"}}},"VehicleData":{"type":"object","properties":{"plate":{"type":"string","example":"1234ABC"},"country":{"type":"string","example":"ES"},"brand":{"type":"string","example":"Volkswagen"},"model":{"type":"string","example":"Golf"},"modelEn":{"type":"string","example":"Golf"},"version":{"type":"string","example":"2.0 TDI 150 CV"},"modelStartDate":{"type":"string","example":"2017-01"},"modelEndDate":{"type":"string","example":"2020-06"},"firstRegistrationDate":{"type":"string","example":"2018-03-15"},"firstRegistrationDateEs":{"type":"string","example":"15/03/2018"},"co2":{"type":"string","example":"119"},"fuelCode":{"type":"integer","example":2,"enum":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19],"description":"1=Bioethanol, 2=Diesel, 3=Gasoline+LPG, 4=Gasoline, 5=Gasoline/Electric Hybrid, 6=Gasoline/Electric Plug-in, 7=Flexfuel Hybrid, 8=Natural Gas, 9=Diesel/Electric Hybrid, 10=Diesel/Electric Plug-in, 11=LPG, 12=Electric, 13=Gasoline/Ethanol, 14=Gasoline/Electric, 15=Diesel/Electric, 16=Gasoline/Natural Gas, 17=Electric/Ethanol Hybrid, 18=Gasoline/Electric Rechargeable, 19=Hydrogen/Electric"},"fuelType":{"type":"string","example":"Diesel","enum":["Bioethanol","Diesel","Gasoline + LPG","Gasoline","Gasoline / Electric Hybrid","Gasoline / Electric Plug-in","Flexfuel Hybrid","Natural Gas","Diesel / Electric Hybrid","Diesel / Electric Plug-in","LPG","Electric","Gasoline / Ethanol","Gasoline / Electric","Diesel / Electric","Gasoline / Natural Gas","Electric / Ethanol Hybrid","Gasoline / Electric Rechargeable","Hydrogen / Electric"]},"vehicleTypeCode":{"type":"integer","example":1,"enum":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20],"description":"1=Passenger Car, 2=Light Van, 3=Specialized Motor Vehicle, 4=Truck, 5=Motorcycle, 6=Moped/Cyclomotor (≤50cc), 7=Motor Quadricycle, 8=Agricultural Vehicle, 9=Motor Tricycle, 10=Three-wheel Moped, 11=Public Transport Vehicle, 12=Road Tractor, 13=Trailer/Semi-trailer, 14=Specific Reserve, 15=Agricultural Trailer, 16=Agricultural Semi-trailer, 17=Specific Semi-trailer, 18=Special Semi-trailer, 19=Light Utility Vehicle, 20=Minibus (9–16 seats)"},"vehicleType":{"type":"string","example":"Passenger Car","enum":["Passenger Car","Light Van","Specialized Motor Vehicle","Truck","Motorcycle","Moped / Cyclomotor (≤50cc)","Motor Quadricycle","Agricultural Vehicle","Motor Tricycle","Three-wheel Moped","Public Transport Vehicle","Road Tractor","Trailer / Semi-trailer","Specific Reserve","Agricultural Trailer","Agricultural Semi-trailer","Specific Semi-trailer","Special Semi-trailer","Light Utility Vehicle","Minibus (9–16 seats)"]},"fiscalPower":{"type":"string","example":"7"},"bodyTypeCode":{"type":"integer","example":25,"enum":[21,25,27,28,29,30,31,32,33,34,38,39,40,42,46,48,51,52,53,54,55,56],"description":"21=Van/Estate, 25=Hatchback (3 or 5 doors), 27=Sedan (3 volumes), 28=Estate/Station Wagon, 29=Coupe, 30=Convertible, 31=Targa, 32=Pickup, 33=Bus/Coach, 34=Van, 38=Open Off-road, 39=Closed Off-road, 40=Minivan/MPV, 42=Flatbed/Chassis, 46=Municipal Vehicle, 48=Mobile Cabin, 51=Motorcycle, 52=Light Van/Hatchback, 53=SUV, 54=Light Van/SUV, 55=Light Van/Off-road, 56=Light Van/Minivan"},"bodyType":{"type":"string","example":"Hatchback (3 or 5 doors)","enum":["Van / Estate","Hatchback (3 or 5 doors)","Sedan (3 volumes)","Estate / Station Wagon","Coupe","Convertible","Targa","Pickup","Bus / Coach","Van","Open Off-road","Closed Off-road","Minivan / MPV","Flatbed / Chassis","Municipal Vehicle","Mobile Cabin","Motorcycle","Light Van / Hatchback","SUV","Light Van / SUV","Light Van / Off-road","Light Van / Minivan"]},"transmissionTypeCode":{"type":"string","example":"1","enum":["1","2","3"],"description":"1=FWD, 2=RWD, 3=AWD"},"transmissionType":{"type":"string","example":"FWD","enum":["FWD","RWD","AWD"]},"engineCapacityLiters":{"type":"string","example":"1.968"},"fuelSystemCode":{"type":"string","example":"21","enum":["1","11","18","21","24","25","26","27"],"description":"1=Carburetor, 11=Direct Injection, 18=Multipoint Injection, 21=Common Rail (CR), 24=Indirect Injection Engine, 25=Fuel Cell, 26=Intake Manifold Injection/Carburetor, 27=Intake Manifold Injection + Direct Injection"},"fuelSystem":{"type":"string","example":"Common Rail (CR)","enum":["Carburetor","Direct Injection","Multipoint Injection","Common Rail (CR)","Indirect Injection Engine","Fuel Cell","Intake Manifold Injection / Carburetor","Intake Manifold Injection, Direct Injection"]},"valves":{"type":"string","example":"4"},"powerKW":{"type":"string","example":"110"},"powerHP":{"type":"string","example":"150"},"vin":{"type":"string","example":"WVWZZZ1KZAM123456"},"variant":{"type":"string","example":"BD"},"gearboxType":{"type":"string","example":"Manual","enum":["Automatic","Manual","Sequential","CVT (Continuously Variable)","Automated Manual (Robotic)"]},"gearboxCode":{"type":"string","example":"BVM6"},"passengerCount":{"type":"integer","example":5},"doorCount":{"type":"integer","example":5},"weight":{"type":"string","example":"1370"},"grossVehicleWeight":{"type":"string","example":"1920"},"displacementCcm":{"type":"string","example":"1968"},"cylinders":{"type":"string","example":"4"},"brandLogo":{"type":"string","format":"uri","nullable":true,"description":"URL del logo de la marca. null si no hay imagen disponible.","example":"https://api.apivehiculo.com/assets/brands/volkswagen.png"},"engineCode":{"type":"string","example":"CRBC"},"platformCodes":{"type":"string","example":"MQB"},"tires":{"type":"array","items":{"$ref":"#/components/schemas/Tire"}}}},"LookupResponse":{"type":"object","properties":{"code":{"type":"integer","example":200},"message":{"type":"string","example":"Vehicle found"},"data":{"$ref":"#/components/schemas/VehicleData"}}},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string","example":"Indica matrícula o vin como query param"},"status":{"type":"integer","example":400}}}}},"paths":{"/vehicles/lookup":{"get":{"summary":"Consultar vehículo","description":"Devuelve los datos técnicos completos de un vehículo a partir de su matrícula o VIN.\n\nProporciona **uno de los dos** (`plate` o `vin`), nunca ambos.\n\nConsume **1 consulta** del plan por petición exitosa (`200`).","operationId":"lookupVehicle","tags":["Vehículos"],"parameters":[{"name":"plate","in":"query","description":"Matrícula del vehículo (ej. `1234ABC`). Incompatible con `vin`.","required":false,"schema":{"type":"string","example":"1234ABC"}},{"name":"vin","in":"query","description":"Número de bastidor VIN (17 caracteres). Incompatible con `plate`.","required":false,"schema":{"type":"string","example":"WVWZZZ1KZAM123456"}},{"name":"country","in":"query","description":"Código de país ISO 3166-1 alpha-2. Por defecto `ES`. Países soportados: `ES` (España), `PT` (Portugal). En la búsqueda por VIN no es necesario indicar este parámetro.","required":false,"schema":{"type":"string","enum":["ES","PT"],"default":"ES","example":"ES"}}],"responses":{"200":{"description":"Vehículo encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResponse"}}}},"400":{"description":"Parámetros incorrectos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missing":{"summary":"Sin parámetros","value":{"message":"Indica matrícula o vin como query param","status":400}},"both":{"summary":"Ambos a la vez","value":{"message":"Indica matrícula o vin, no ambos","status":400}},"unsupportedCountry":{"summary":"País no soportado","value":{"message":"País no soportado: FR","status":400}}}}}},"401":{"description":"API key inválida o ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Authentication token missing","status":401}}}},"404":{"description":"Vehículo no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Vehicle not found","status":404}}}},"429":{"description":"Límite de consultas del plan alcanzado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Has alcanzado el límite de búsquedas de este periodo","status":429}}}}}}},"/users/me":{"get":{"summary":"Perfil del usuario autenticado","description":"Devuelve los datos del usuario asociado a la API key.","operationId":"getMyProfile","tags":["Usuario"],"responses":{"200":{"description":"Perfil del usuario","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfile"}}}},"401":{"description":"API key inválida o ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Authentication token missing","status":401}}}}}}},"/users/me/stats":{"get":{"summary":"Estadísticas de uso","description":"Devuelve contadores de consultas exitosas agrupadas por ventana temporal: última hora, hoy, ayer, últimos 30 días, últimos 90 días y total acumulado.","operationId":"getMyStats","tags":["Usuario"],"responses":{"200":{"description":"Estadísticas de uso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserStats"}}}},"401":{"description":"API key inválida o ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Authentication token missing","status":401}}}}}}},"/subscriptions/me":{"get":{"summary":"Suscripción activa","description":"Devuelve el plan vigente del usuario: estado, consultas consumidas, consultas restantes y fechas del periodo de facturación.","operationId":"getMySubscription","tags":["Suscripción"],"responses":{"200":{"description":"Suscripción activa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"401":{"description":"API key inválida o ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Authentication token missing","status":401}}}},"404":{"description":"No se encontró suscripción activa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"No active subscription found","status":404}}}}}}}}}