> ## 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.

# Aperçu de l'API Véhicules

> Gestion complète de l'inventaire, suivi des inspections et rapports de dommages

## Introduction

L'API Véhicules fournit des endpoints complets pour gérer votre inventaire tout au long du cycle de vie du véhicule, de la mise en ligne initiale à la vente finale. Cela inclut la gestion des données véhicules, le suivi des dommages, la coordination des inspections et les mises à jour de statut.

## Fonctionnalités clés

<CardGroup cols={2}>
  <Card title="Gestion d'inventaire" icon="car">
    Créez, mettez à jour, recherchez et filtrez votre inventaire avec des capacités de recherche avancées
  </Card>

  <Card title="Suivi des dommages" icon="triangle-exclamation">
    Enregistrez et gérez les évaluations de dommages avec des rapports détaillés et des estimations de coûts
  </Card>

  <Card title="Intégration d'inspection" icon="magnifying-glass">
    Connectez-vous aux services d'inspection IA pour la détection automatique des dommages
  </Card>

  <Card title="Workflow de statut" icon="arrows-spin">
    Suivez les véhicules via les statuts : LOADING, INSPECTED, SOLD avec un historique complet
  </Card>
</CardGroup>

## Cycle de vie du véhicule

```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 API

### Gestion des véhicules

| Endpoint         | Méthode | Description                                          |
| ---------------- | ------- | ---------------------------------------------------- |
| `/vehicles`      | GET     | Lister tous les véhicules avec filtres et pagination |
| `/vehicles/{id}` | GET     | Récupérer les détails d'un véhicule par ID           |
| `/vehicles`      | POST    | Créer un nouveau véhicule                            |
| `/vehicles/{id}` | PATCH   | Mettre à jour les informations d'un véhicule         |
| `/vehicles/{id}` | DELETE  | Supprimer un véhicule                                |

### Recherche et filtrage

| Endpoint                        | Méthode | Description                             |
| ------------------------------- | ------- | --------------------------------------- |
| `/vehicles/public`              | GET     | Récupérer les véhicules publiés publics |
| `/vehicles/status/{status}`     | GET     | Filtrer par statut d'achat              |
| `/vehicles/make/{make}`         | GET     | Filtrer par marque                      |
| `/vehicles/location/{location}` | GET     | Filtrer par localisation                |
| `/vehicles/search/{q}`          | GET     | Recherche plein texte sur les véhicules |

### Gestion des dommages

| Endpoint                            | Méthode | Description                                      |
| ----------------------------------- | ------- | ------------------------------------------------ |
| `/vehicles/{id}/complete`           | PUT     | Compléter les données avec dommages et analytics |
| `/vehicles/{id}/damages`            | POST    | Ajouter un dommage à un véhicule                 |
| `/vehicles/{id}/damages/{damageId}` | DELETE  | Supprimer un dommage                             |
| `/vehicles/{id}/estimate-damages`   | POST    | Déclencher l'estimation IA des dommages          |

### Workflow d'inspection

| Endpoint                          | Méthode | Description                                   |
| --------------------------------- | ------- | --------------------------------------------- |
| `/vehicles/phase/preprocess/{id}` | POST    | Associer un job de pré-traitement au véhicule |
| `/vehicles/webhooks/ml-results`   | POST    | Webhook pour résultats du traitement ML       |

## Schéma de l'objet véhicule

```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"
}
```

## Paramètres de requête

### Options de filtrage

Tous les endpoints de liste prennent en charge les filtres suivants :

* `search` - Recherche globale sur marque, modèle, localisation
* `make` - Filtrer par marque
* `model` - Filtrer par modèle
* `minPrice` / `maxPrice` - Filtrer par plage de prix
* `minYear` / `maxYear` - Filtrer par plage d'année
* `minKm` / `maxKm` - Filtrer par plage de kilométrage
* `fuel` - Filtrer par type de carburant
* `gearBox` - Filtrer par type de transmission
* `location` - Filtrer par localisation
* `purchaseStatus` - Filtrer par statut (LOADING, INSPECTED, SOLD)
* `published` - Filtrer par statut de publication
* `archive` - Filtrer par statut d'archivage

### Pagination et tri

* `page` - Numéro de page (par défaut : 1)
* `limit` - Éléments par page (par défaut : 10, max : 100)
* `sortBy` - Champ de tri (price, overviewYear, km, createdAt)
* `sortOrder` - Sens de tri (asc, desc)

## Workflow de statut d'achat

### Transitions de statut

<Steps>
  <Step title="LOADING">
    Le véhicule est en cours d'ajout à l'inventaire. Les images et les détails sont collectés.
  </Step>

  <Step title="INSPECTED">
    Le véhicule a été inspecté. Les rapports de dommages et les évaluations d'état sont terminés.
  </Step>

  <Step title="SOLD">
    Le véhicule est vendu. Transaction finalisée.
  </Step>
</Steps>

## Schéma de l'objet dommage

```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://..."
  ]
}
```

### Niveaux de gravité

* `minor` - Dommage cosmétique, réparation minimale
* `moderate` - Dommage visible nécessitant une réparation professionnelle
* `severe` - Dommage structurel nécessitant des travaux importants

## Limites de débit

Les endpoints de l'API Véhicules suivent les limites standards :

| Plan         | Requêtes/heure | Limite burst |
| ------------ | -------------- | ------------ |
| Free         | 1,000          | 50           |
| Starter      | 10,000         | 200          |
| Professional | 100,000        | 1,000        |
| Enterprise   | Unlimited      | Custom       |

## Codes d'erreur

| Code                          | Description                              |
| ----------------------------- | ---------------------------------------- |
| `VEHICLE_NOT_FOUND`           | L'ID véhicule n'existe pas               |
| `VEHICLE_ALREADY_SOLD`        | Impossible de modifier un véhicule vendu |
| `UNAUTHORIZED_VEHICLE_ACCESS` | L'utilisateur ne possède pas ce véhicule |
| `INVALID_PURCHASE_STATUS`     | Transition de statut invalide            |
| `DUPLICATE_IMMATRICULE`       | La plaque d'immatriculation existe déjà  |

## Bonnes pratiques

<AccordionGroup>
  <Accordion title="Toujours valider les données avant création">
    Assurez-vous que tous les champs requis sont fournis et valides. Utilisez la validation du schéma pour éviter les erreurs.
  </Accordion>

  <Accordion title="Utiliser la pagination pour de grands inventaires">
    Pour les inventaires de 1000+ véhicules, utilisez toujours la pagination avec des tailles de page raisonnables (10-50).
  </Accordion>

  <Accordion title="Exploiter le cache pour les annonces publiques">
    Les annonces publiques de véhicules sont mises en cache 5 minutes. Utilisez cela pour optimiser les performances.
  </Accordion>

  <Accordion title="Suivre les transitions de statut">
    Conservez des journaux d'audit des changements de statut pour la conformité et l'analyse métier.
  </Accordion>
</AccordionGroup>

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Lister les véhicules" icon="list" href="/fr/api-reference/vehicles/list">
    Apprenez à récupérer et filtrer votre inventaire de véhicules
  </Card>

  <Card title="Créer un véhicule" icon="plus" href="/fr/api-reference/vehicles/create">
    Ajoutez de nouveaux véhicules à votre inventaire
  </Card>

  <Card title="Gestion des dommages" icon="wrench" href="/fr/api-reference/vehicles/damages">
    Gérez les rapports de dommages et les estimations
  </Card>

  <Card title="Recherche et filtres" icon="filter" href="/fr/api-reference/vehicles/search">
    Options avancées de recherche et filtrage
  </Card>
</CardGroup>