> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steerai.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# Resumen de la API de vehiculos

> Gestion completa de inventario, seguimiento de inspecciones y reportes de danos

## Introduccion

La API de vehiculos ofrece endpoints completos para gestionar tu inventario a lo largo del ciclo de vida del vehiculo, desde el alta inicial hasta la venta final. Incluye gestion de datos, seguimiento de danos, coordinacion de inspecciones y actualizaciones de estado.

## Funcionalidades clave

<CardGroup cols={2}>
  <Card title="Gestion de inventario" icon="car">
    Crea, actualiza, busca y filtra tu inventario con capacidades avanzadas de busqueda
  </Card>

  <Card title="Seguimiento de danos" icon="triangle-exclamation">
    Registra y gestiona evaluaciones de danos con reportes detallados y estimacion de costos
  </Card>

  <Card title="Integracion de inspecciones" icon="magnifying-glass">
    Conecta con inspecciones con IA para deteccion automatica de danos
  </Card>

  <Card title="Workflow de estados" icon="arrows-spin">
    Seguimiento de estados: LOADING, INSPECTED, SOLD con historial completo
  </Card>
</CardGroup>

## Ciclo de vida del vehiculo

```mermaid theme={null}
graph LR
    A[Create Vehicle] --> B[LOADING]
    B --> C[Add Images & Details]
    C --> D[Inspection]
    D --> E[INSPECTED]
    E --> F[Publish Listing]
    F --> G[SOLD]

    style A fill:#282F75
    style E fill:#4360B1
    style G fill:#28a745
```

## Endpoints de la API

### Gestion de vehiculos

| Endpoint         | Method | Descripcion                                        |
| ---------------- | ------ | -------------------------------------------------- |
| `/vehicles`      | GET    | Lista todos los vehiculos con filtros y paginacion |
| `/vehicles/{id}` | GET    | Obtiene detalles de un vehiculo por ID             |
| `/vehicles`      | POST   | Crea un vehiculo nuevo                             |
| `/vehicles/{id}` | PATCH  | Actualiza informacion del vehiculo                 |
| `/vehicles/{id}` | DELETE | Elimina un vehiculo                                |

### Busqueda y filtros

| Endpoint                        | Method | Descripcion                           |
| ------------------------------- | ------ | ------------------------------------- |
| `/vehicles/public`              | GET    | Obtiene vehiculos publicos publicados |
| `/vehicles/status/{status}`     | GET    | Filtra por estado de compra           |
| `/vehicles/make/{make}`         | GET    | Filtra por marca                      |
| `/vehicles/location/{location}` | GET    | Filtra por ubicacion                  |
| `/vehicles/search/{q}`          | GET    | Busqueda de texto completo            |

### Gestion de danos

| Endpoint                            | Method | Descripcion                          |
| ----------------------------------- | ------ | ------------------------------------ |
| `/vehicles/{id}/complete`           | PUT    | Completa datos con danos y analitica |
| `/vehicles/{id}/damages`            | POST   | Agrega dano al vehiculo              |
| `/vehicles/{id}/damages/{damageId}` | DELETE | Elimina dano                         |
| `/vehicles/{id}/estimate-damages`   | POST   | Dispara estimacion de danos con IA   |

### Flujo de inspeccion

| Endpoint                          | Method | Descripcion                     |
| --------------------------------- | ------ | ------------------------------- |
| `/vehicles/phase/preprocess/{id}` | POST   | Adjunta job de preprocesamiento |
| `/vehicles/webhooks/ml-results`   | POST   | Webhook de resultados de ML     |

## Esquema de objeto vehiculo

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "user_uuid",
  "make": "Honda",
  "model": "Civic",
  "overviewYear": 2021,
  "price": 25000,
  "km": 45000,
  "location": "Casablanca, Morocco",
  "seat": 5,
  "gearBox": "Automatic",
  "fuel": "Gasoline",
  "engineDisplacement": 1800,
  "numberCV": 140,
  "averageConsumption": "6.5L/100km",
  "outside": "Excellent",
  "inside": "Good",
  "ownerNumber": 1,
  "purchaseStatus": "INSPECTED",
  "archive": false,
  "published": true,
  "adNumber": 12345,
  "immatricule": "ABC-1234",
  "overviewImgs": "https://...",
  "postedBy": "Dealer XYZ",
  "functionalities": "GPS, Bluetooth, Cruise Control",
  "feature": "Sunroof, Leather Seats",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

## Parametros de consulta

### Opciones de filtrado

Todos los endpoints de listado soportan estos filtros:

* `search` - Busqueda global por marca, modelo, ubicacion
* `make` - Filtra por marca
* `model` - Filtra por modelo
* `minPrice` / `maxPrice` - Rango de precio
* `minYear` / `maxYear` - Rango de ano
* `minKm` / `maxKm` - Rango de kilometraje
* `fuel` - Filtra por combustible
* `gearBox` - Filtra por transmision
* `location` - Filtra por ubicacion
* `purchaseStatus` - Filtra por estado (LOADING, INSPECTED, SOLD)
* `published` - Filtra por estado de publicacion
* `archive` - Filtra por estado de archivo

### Paginacion y ordenamiento

* `page` - Numero de pagina (default: 1)
* `limit` - Items por pagina (default: 10, max: 100)
* `sortBy` - Campo de orden (price, overviewYear, km, createdAt)
* `sortOrder` - Direccion (asc, desc)

## Flujo de estado de compra

### Transiciones de estado

<Steps>
  <Step title="LOADING">
    Se esta agregando el vehiculo al inventario. Se recopilan imagenes y detalles.
  </Step>

  <Step title="INSPECTED">
    Vehiculo inspeccionado. Reportes de danos y condicion completos.
  </Step>

  <Step title="SOLD">
    Vehiculo vendido. Transaccion completada.
  </Step>
</Steps>

## Esquema de objeto dano

```json theme={null}
{
  "id": "damage_uuid",
  "type": "Dent",
  "severity": "moderate",
  "location": "Front Right Door",
  "description": "Small dent approximately 5cm diameter",
  "estimatedCost": 350,
  "imageUrls": [
    "https://...",
    "https://..."
  ]
}
```

### Niveles de severidad

* `minor` - Dano cosmetico, reparacion minima
* `moderate` - Dano visible que requiere reparacion profesional
* `severe` - Dano estructural que requiere trabajo significativo

## Limites de tasa

Los endpoints de vehiculos siguen los limites estandar:

| Plan         | Solicitudes/Hora | Limite de rafaga |
| ------------ | ---------------- | ---------------- |
| Free         | 1,000            | 50               |
| Starter      | 10,000           | 200              |
| Professional | 100,000          | 1,000            |
| Enterprise   | Unlimited        | Custom           |

## Codigos de error

| Code                          | Descripcion                               |
| ----------------------------- | ----------------------------------------- |
| `VEHICLE_NOT_FOUND`           | El ID del vehiculo no existe              |
| `VEHICLE_ALREADY_SOLD`        | No se puede modificar un vehiculo vendido |
| `UNAUTHORIZED_VEHICLE_ACCESS` | El usuario no es propietario              |
| `INVALID_PURCHASE_STATUS`     | Transicion de estado invalida             |
| `DUPLICATE_IMMATRICULE`       | La placa ya existe                        |

## Mejores practicas

<AccordionGroup>
  <Accordion title="Valida datos antes de crear">
    Asegura que los campos requeridos sean validos. Usa validacion de esquema para evitar errores.
  </Accordion>

  <Accordion title="Usa paginacion para inventarios grandes">
    Para inventarios de 1000+ vehiculos, usa paginacion con tamanos razonables (10-50).
  </Accordion>

  <Accordion title="Aprovecha caching para listados publicos">
    Los listados publicos se cachean por 5 minutos. Usalo para optimizar rendimiento.
  </Accordion>

  <Accordion title="Rastrea transiciones de estado">
    Mantén auditorias de cambios de estado para cumplimiento y BI.
  </Accordion>
</AccordionGroup>

## Siguientes pasos

<CardGroup cols={2}>
  <Card title="Listar vehiculos" icon="list" href="/es/api-reference/vehicles/list">
    Aprende a obtener y filtrar tu inventario
  </Card>

  <Card title="Crear vehiculo" icon="plus" href="/es/api-reference/vehicles/create">
    Agrega nuevos vehiculos a tu inventario
  </Card>

  <Card title="Gestion de danos" icon="wrench" href="/es/api-reference/vehicles/damages">
    Gestiona reportes y estimaciones de danos
  </Card>

  <Card title="Busqueda y filtros" icon="filter" href="/es/api-reference/vehicles/search">
    Opciones avanzadas de busqueda y filtrado
  </Card>
</CardGroup>