API Inventario - Documentación

Introducción

API de solo lectura para consultar el catálogo de vehículos. Solo se permiten operaciones GET.

Base URL

https://tu-dominio.com

Importante: Esta API es de solo lectura. No se permiten operaciones POST, PUT, PATCH, DELETE.

Autenticación

Sistema de autenticación dual

API Key: Identifica al cliente (campo api_key de la tabla customer)

Token Secreto: Autoriza el acceso. Dos tipos:

Token Interno: Uso interno, todas las funcionalidades
Token Cliente: Clientes externos, funcionalidades limitadas

Headers requeridos en todas las peticiones

X-API-Key: tu_api_key_del_customer
X-API-Token: token_interno_o_cliente

Seguridad: Los tokens secretos deben mantenerse privados.

Endpoints de Coches

Filtrado automático: Todos los coches devueltos pertenecen al customer autenticado y están publicados en la web.

GET /coches Requiere autenticación

Lista paginada de coches del customer autenticado.

Parámetros de paginación y ordenación

Parámetro	Tipo	Default	Descripción
`per_page`	integer	16	Resultados por página
`page`	integer	1	Número de página
`sort_by`	string	id	Campo para ordenar (ver opciones abajo)
`sort_order`	string	desc	Dirección: `asc` o `desc`
`max_photos`	integer	null	Limitar número de fotos devueltas

Campos disponibles para ordenación (sort_by)

Valor	Descripción
`id`	ID del vehículo
`titulo`	Título del anuncio
`kilometros`	Kilómetros
`registration_date`	Fecha de matriculación
`price`	Precio de venta
`financing_price`	Precio financiado
`financing_monthly_fee`	Cuota mensual financiación
`multioption_financing_price`	Precio financiado multiopción
`multioption_monthly_fee`	Cuota mensual multiopción
`destacado`	Vehículos destacados primero

Ejemplo de respuesta

{
    "data": [...],
    "total": 150,
    "per_page": 16,
    "current_page": 1,
    "total_pages": 10
}

GET /coches/{id} Requiere autenticación

Obtiene un coche específico con todos sus detalles.

Parámetros opcionales

Parámetro	Tipo	Descripción
`max_photos`	integer	Limitar número de fotos devueltas

Estructura de respuesta del vehículo

Los datos del vehículo se organizan en bloques:

Bloque	Descripción	Campos principales
`data`	Datos principales	make, model, version, title, body_style, color, registration_date, kilometers...
`location`	Ubicación	name, city, postal_code, region, address
`characteristics`	Características técnicas	power, transmission, gears, doors, seats, cylinder_capacity...
`more_information`	Información adicional	number_of_owners, has_service_book, is_national, is_crashed...
`consumption`	Consumo y emisiones	fuel, average_consumption, environmental_badge, autonomy...
`dimensions`	Dimensiones	height, width, longitude, trunk_capacity, tank_capacity, tare
`prices`	Precios	price, previous_price, financing, multioption_financing...
`equipment`	Equipamiento	standard, extra, inventario
`pictures`	Fotos	original, large, medium, order, is_main

Endpoints de Renting

Endpoints para vehículos disponibles en modalidad de renting/suscripción.

GET /coches/renting Requiere autenticación

Lista paginada de coches con renting disponible. Incluye el campo renting_cuota_minima con la cuota mensual mínima.

Parámetros adicionales de filtrado

Parámetro	Descripción	Ejemplo
`BT_renting_cuota_minima`	Cuota mínima mayor o igual a	`BT_renting_cuota_minima=200`
`ST_renting_cuota_minima`	Cuota mínima menor o igual a	`ST_renting_cuota_minima=500`
`FILTR_total_months`	Meses de contrato exactos	`FILTR_total_months=36`
`FILTR_kilometers_included`	Kilómetros incluidos exactos	`FILTR_kilometers_included=15000`

Campo de ordenación adicional

renting_cuota_minima - Ordenar por cuota mínima de renting

Ejemplo de respuesta

{
    "data": [
        {
            "id": 334760,
            "titulo": "BMW Serie 3...",
            "renting_cuota_minima": 232,
            ...
        }
    ],
    "total": 15,
    "per_page": 16,
    "current_page": 1,
    "total_pages": 1
}

GET /coches/renting/{id} Requiere autenticación

Obtiene todas las subscriptions/planes de renting disponibles para un vehículo específico.

Ejemplo de respuesta

{
    "data": [
        {
            "id": 25,
            "total_months": 12,
            "kilometers_included": 2000,
            "monthly_fee": 232,
            "conditions": "Condiciones del contrato...",
            "is_professional_sale": false,
            "is_private_sale": true
        },
        {
            "id": 7,
            "total_months": 60,
            "kilometers_included": 15000,
            "monthly_fee": 500,
            "conditions": null,
            "is_professional_sale": true,
            "is_private_sale": true
        }
    ],
    "total": 2
}

Respuesta de error (vehículo no encontrado)

{"error": "Not found", "message": "Vehículo no encontrado"}

Endpoints de Filtros

Endpoints para obtener las opciones disponibles para cada filtro. Devuelven solo valores que existen en el inventario actual del customer.

Filtrado cruzado: Todos estos endpoints aceptan los mismos parámetros de filtrado dinámico (FILTR_, INC_, etc.) que el listado de coches. Esto permite obtener, por ejemplo, solo las marcas que tienen coches de gasolina: /coches/filtros/marcas?FILTR_combustible_id=3

Filtros con opciones (devuelven lista con conteo)

GET /coches/filtros/marcas

Marcas disponibles

[{"id": 1, "name": "BMW", "total": 15}]

GET /coches/filtros/modelos/{marcaId}

Modelos de una marca específica

[{"id": 10, "name": "Serie 3", "total": 5}]

GET /coches/filtros/combustibles

Tipos de combustible

[{"id": 1, "name": "Gasolina", "total": 45}]

GET /coches/filtros/colores

Colores disponibles

[{"id": 5, "name": "Negro", "total": 30}]

GET /coches/filtros/cambios

Tipos de transmisión

[{"id": 1, "name": "Manual", "total": 60}]

GET /coches/filtros/asientos

Número de asientos

[{"value": 5, "total": 80}]

GET /coches/filtros/puertas

Número de puertas

[{"value": 5, "total": 70}]

GET /coches/filtros/years

Años de matriculación

[{"value": 2024, "total": 25}]

GET /coches/filtros/ad-subtypes

Tipos de carrocería (SUV, Sedán...)

[{"id": 1, "name": "SUV", "total": 40}]

GET /coches/filtros/distintivos

Distintivos ambientales

[{"id": 4, "name": "ECO", "total": 20}]

GET /coches/filtros/tipos

Tipo de oferta (Ocasión, Nuevo, KM0...)

[{"id": 1, "name": "Ocasión", "total": 100}]

Filtros de rango (devuelven min/max)

GET /coches/filtros/precios

Rango de precios de venta

{"min": 5000, "max": 150000}

GET /coches/filtros/precios-financiados

Rango de precios financiados

{"min": 4500, "max": 140000}

GET /coches/filtros/cuotas

Rango de cuotas mensuales (financiación básica)

{"min": 99, "max": 1500}

GET /coches/filtros/cuotas-multioption

Rango de cuotas mensuales (multiopción)

{"min": 149, "max": 1200}

GET /coches/filtros/kilometros

Rango de kilómetros

{"min": 0, "max": 250000}

GET /coches/filtros/potencias

Rango de potencia (CV)

{"min": 75, "max": 500}

Sistema de Filtrado Dinámico

El listado de coches y los endpoints de filtros soportan un sistema de filtrado dinámico mediante prefijos en los parámetros de query. Esto permite construir consultas complejas de forma flexible.

Prefijos disponibles

Prefijo	Operación	Ejemplo	SQL Equivalente
`FILTR_`	Igualdad exacta	`FILTR_combustible_id=3`	`WHERE combustible_id = 3`
`INC_`	Incluir (IN)	`INC_marca_id[]=1&INC_marca_id[]=2`	`WHERE marca_id IN (1, 2)`
`EXC_`	Excluir (NOT IN)	`EXC_color_id[]=5&EXC_color_id[]=6`	`WHERE color_id NOT IN (5, 6)`
`BTW_`	Entre (BETWEEN)	`BTW_kilometros[]=0&BTW_kilometros[]=50000`	`WHERE kilometros BETWEEN 0 AND 50000`
`BT_`	Mayor o igual (>=)	`BT_price=15000`	`WHERE price >= 15000`
`ST_`	Menor o igual (<=)	`ST_kilometros=100000`	`WHERE kilometros <= 100000`
`LIKE_`	Búsqueda parcial	`LIKE_titulo=mercedes`	`WHERE titulo LIKE 'mercedes%'`

Campos permitidos

Campos del vehículo (coche)

marca_id, modelo_id, combustible_id, color_id, cambio_id, tipo_id, estado_id, disponibilidad_id, ad_subtype_id, location_id, emisiones_id, distintivo_ambiental, kilometros, potencia, puertas, asientos, cilindrada, marchas, registration_date, manufacturing_year, titulo, version, referencia, accidentado, nacional, clasico, competicion, metalizado

Campos de precios (ads_pricings)

price, previous_price, financing_price, repair_price, professional_price, new_price, financing_monthly_fee, financing_number_fees, multioption_financing_price, multioption_monthly_fee, multioption_number_fees, multioption_tin, multioption_tae, multioption_entry, multioption_final_installment

Campo especial

destacado - Indica si el vehículo está destacado (1 o 0)

Ejemplos de uso

Coches BMW o Audi de gasolina

GET /coches?INC_marca_id[]=1&INC_marca_id[]=2&FILTR_combustible_id=3

Coches entre 15.000€ y 30.000€ con menos de 50.000km

GET /coches?BT_price=15000&ST_price=30000&ST_kilometros=50000

Coches automáticos matriculados desde 2020

GET /coches?FILTR_cambio_id=2&BT_registration_date=2020-01-01

Buscar coches que contengan "mercedes" en el título, ordenados por precio

GET /coches?LIKE_titulo=mercedes&sort_by=price&sort_order=asc

Obtener marcas disponibles para coches de gasolina

GET /coches/filtros/marcas?FILTR_combustible_id=3

Códigos de Estado

Código	Descripción
200	Petición exitosa
401	No autorizado (falta auth, API Key o Token inválido)
404	Recurso no encontrado

Ejemplos de errores

{"error": "No autorizado", "message": "Se requieren los headers X-API-Key y X-API-Token"}

{"error": "No autorizado", "message": "Token inválido"}

{"error": "No autorizado", "message": "API Key inválida"}