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

# API de gestion des prospects

> Gérer les prospects liés aux véhicules, suivre les interactions et organiser les workflows commerciaux

## Aperçu

L'API de gestion des prospects vous aide à suivre et gérer les opportunités de vente potentielles pour chaque véhicule de votre inventaire. Créez des tâches actionnables, définissez des priorités et surveillez le statut des prospects tout au long du tunnel de vente.

## Endpoints

### Lister tous les prospects

<ParamField path="GET" type="endpoint">
  /leads
</ParamField>

Récupère tous les prospects avec filtrage et tri optionnels.

**Paramètres de requête :**

<ParamField query="search" type="string">
  Recherche globale sur action, targetName, tag
</ParamField>

<ParamField query="status" type="enum">
  Filtrer par statut : `NEW`, `COMPLETED`, `NOT_NEEDED`
</ParamField>

<ParamField query="action" type="string">
  Filtrer par type d'action
</ParamField>

<ParamField query="targetName" type="string">
  Filtrer par nom de la cible
</ParamField>

<ParamField query="tag" type="string">
  Filtrer par tag
</ParamField>

<ParamField query="carId" type="string">
  Filtrer par ID de véhicule associé
</ParamField>

<ParamField query="sortBy" type="enum">
  Champ de tri : `order`, `status`, `action`, `targetName`, `createdAt`
</ParamField>

<ParamField query="sortOrder" type="enum">
  Sens du tri : `asc`, `desc`
</ParamField>

**Réponse :**

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "carId": "car_uuid",
    "status": "NEW",
    "action": "Follow up call",
    "targetName": "John Smith",
    "targetInfo": "+212-600-123456",
    "tag": "Hot Lead",
    "note": "Customer interested in financing options",
    "order": 1,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "car": {
      "id": "car_uuid",
      "make": "Honda",
      "model": "Civic",
      "overviewYear": 2021,
      "location": "Casablanca"
    }
  }
]
```

***

### Récupérer un prospect par ID

<ParamField path="GET" type="endpoint">
  /leads/{id}
</ParamField>

Récupère les informations détaillées d'un prospect spécifique.

**Paramètres de chemin :**

<ParamField path="id" type="string" required>
  UUID du prospect
</ParamField>

**Réponse :**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "carId": "car_uuid",
  "status": "NEW",
  "action": "Follow up call",
  "targetName": "John Smith",
  "targetInfo": "+212-600-123456",
  "tag": "Hot Lead",
  "note": "Customer interested in financing options",
  "order": 1,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

***

### Créer un prospect pour un véhicule

<ParamField path="POST" type="endpoint">
  /leads/car/{carId}
</ParamField>

Crée un nouveau prospect associé à un véhicule spécifique.

**Paramètres de chemin :**

<ParamField path="carId" type="string" required>
  UUID du véhicule
</ParamField>

**Corps de la requête :**

```json theme={null}
{
  "action": "Schedule test drive",
  "targetName": "Jane Doe",
  "targetInfo": "jane.doe@email.com",
  "tag": "Test Drive",
  "note": "Prefers weekend appointments",
  "status": "NEW",
  "order": 1
}
```

<ParamField body="action" type="string" required>
  Description de l'action (max 200 caractères)
</ParamField>

<ParamField body="targetName" type="string" required>
  Nom du contact (max 200 caractères)
</ParamField>

<ParamField body="targetInfo" type="string" required>
  Informations de contact - téléphone ou email (max 500 caractères)
</ParamField>

<ParamField body="tag" type="string">
  Tag de catégorie du prospect (max 100 caractères)
</ParamField>

<ParamField body="note" type="string">
  Notes supplémentaires (max 1000 caractères)
</ParamField>

<ParamField body="status" type="enum">
  Statut du prospect : `NEW` (par défaut), `COMPLETED`, `NOT_NEEDED`
</ParamField>

<ParamField body="order" type="integer">
  Ordre d'affichage pour le tri (par défaut : 0)
</ParamField>

**Réponse :**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "carId": "car_uuid",
  "status": "NEW",
  "action": "Schedule test drive",
  "targetName": "Jane Doe",
  "targetInfo": "jane.doe@email.com",
  "tag": "Test Drive",
  "note": "Prefers weekend appointments",
  "order": 1,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

***

### Mettre à jour un prospect

<ParamField path="PATCH" type="endpoint">
  /leads/{id}
</ParamField>

Met à jour les informations d'un prospect existant.

**Paramètres de chemin :**

<ParamField path="id" type="string" required>
  UUID du prospect
</ParamField>

**Corps de la requête :**

```json theme={null}
{
  "status": "COMPLETED",
  "note": "Test drive completed. Customer very interested."
}
```

Tous les champs sont facultatifs. Seuls les champs fournis seront mis à jour.

**Réponse :**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "note": "Test drive completed. Customer very interested.",
  "updatedAt": "2024-01-16T14:20:00Z"
}
```

***

### Récupérer les prospects d'un véhicule

<ParamField path="GET" type="endpoint">
  /leads/car/{carId}
</ParamField>

Récupère tous les prospects associés à un véhicule spécifique.

**Paramètres de chemin :**

<ParamField path="carId" type="string" required>
  UUID du véhicule
</ParamField>

**Paramètres de requête :**

Mêmes options de filtrage et tri que l'endpoint `/leads`.

**Réponse :**

Tableau d'objets prospect triés par ordre (croissant par défaut).

***

### Récupérer les prospects par statut

<ParamField path="GET" type="endpoint">
  /leads/status/{status}
</ParamField>

Filtrer les prospects par statut actuel.

**Paramètres de chemin :**

<ParamField path="status" type="enum" required>
  Statut : `NEW`, `COMPLETED`, `NOT_NEEDED`
</ParamField>

**Réponse :**

Tableau d'objets prospect correspondant au statut.

***

### Réordonner les prospects

<ParamField path="PATCH" type="endpoint">
  /leads/car/{carId}/reorder
</ParamField>

Met à jour en lot les positions d'ordre des prospects pour un véhicule.

**Paramètres de chemin :**

<ParamField path="carId" type="string" required>
  UUID du véhicule
</ParamField>

**Corps de la requête :**

```json theme={null}
{
  "leadOrders": [
    { "id": "lead_id_1", "order": 1 },
    { "id": "lead_id_2", "order": 2 },
    { "id": "lead_id_3", "order": 3 }
  ]
}
```

**Réponse :**

```json theme={null}
{
  "success": true,
  "message": "Leads reordered successfully"
}
```

***

### Mettre à jour l'ordre d'un prospect

<ParamField path="PATCH" type="endpoint">
  /leads/{id}/order
</ParamField>

Met à jour la position d'ordre d'un prospect.

**Paramètres de chemin :**

<ParamField path="id" type="string" required>
  UUID du prospect
</ParamField>

**Corps de la requête :**

```json theme={null}
{
  "order": 5
}
```

***

### Supprimer un prospect

<ParamField path="DELETE" type="endpoint">
  /leads/{id}
</ParamField>

Supprime définitivement un prospect.

**Paramètres de chemin :**

<ParamField path="id" type="string" required>
  UUID du prospect
</ParamField>

**Réponse :**

```json theme={null}
{
  "success": true,
  "message": "Lead deleted successfully"
}
```

***

## Workflow de statut des prospects

<Steps>
  <Step title="NEW">
    Le prospect est créé et nécessite une action. Statut par défaut.
  </Step>

  <Step title="COMPLETED">
    L'action a été menée à bien. Le prospect a atteint son objectif.
  </Step>

  <Step title="NOT_NEEDED">
    Le prospect n'est plus pertinent ou a été annulé.
  </Step>
</Steps>

## Cas d'usage

### Exemple 1 : Suivre les demandes d'essai

```bash theme={null}
# Créer un prospect d'essai
curl -X POST "https://api.steerai.autos/v1/leads/car/{carId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Schedule test drive",
    "targetName": "Ahmed Benali",
    "targetInfo": "+212-600-123456",
    "tag": "Test Drive",
    "note": "Prefers Saturday morning"
  }'
```

### Exemple 2 : Suivre les appels de relance

```bash theme={null}
# Créer un prospect de relance
curl -X POST "https://api.steerai.autos/v1/leads/car/{carId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Follow-up call",
    "targetName": "Sara Alami",
    "targetInfo": "sara.alami@email.com",
    "tag": "Hot Lead",
    "note": "Interested in financing. Call back Tuesday"
  }'
```

### Exemple 3 : Revue de documents

```bash theme={null}
# Créer un prospect de revue documentaire
curl -X POST "https://api.steerai.autos/v1/leads/car/{carId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Prepare sales documents",
    "targetName": "Legal Department",
    "targetInfo": "legal@dealership.com",
    "tag": "Documentation"
  }'
```

## Codes d'erreur

| Code                       | Statut | Description                            |
| -------------------------- | ------ | -------------------------------------- |
| `LEAD_NOT_FOUND`           | 404    | L'ID prospect n'existe pas             |
| `CAR_NOT_FOUND`            | 404    | Véhicule associé introuvable           |
| `UNAUTHORIZED_LEAD_ACCESS` | 403    | Accès non autorisé à ce prospect       |
| `INVALID_LEAD_STATUS`      | 400    | Statut invalide fourni                 |
| `VALIDATION_ERROR`         | 400    | Validation du corps de requête échouée |

## Bonnes pratiques

<AccordionGroup>
  <Accordion title="Utiliser des actions descriptives">
    Rédigez des descriptions claires et actionnables. Bien : "Follow up call about financing". Mauvais : "Call".
  </Accordion>

  <Accordion title="Exploiter les tags pour l'organisation">
    Utilisez des tags cohérents : "Hot Lead", "Test Drive", "Documentation", "Follow-up".
  </Accordion>

  <Accordion title="Maintenir les notes à jour">
    Ajoutez des notes après chaque interaction pour conserver le contexte et l'historique.
  </Accordion>

  <Accordion title="Réordonner les prospects par priorité">
    Utilisez le champ order pour prioriser les prospects. Les plus petits numéros apparaissent en premier.
  </Accordion>

  <Accordion title="Nettoyer les prospects terminés">
    Archivez ou supprimez régulièrement les prospects terminés pour garder un pipeline propre.
  </Accordion>
</AccordionGroup>

## Conseils d'intégration

L'API Leads s'intègre parfaitement avec :

* **API Véhicules** - Lier automatiquement les prospects à l'inventaire
* **Systèmes CRM** - Exporter les prospects vers des CRM externes
* **Services Email/SMS** - Déclencher des notifications sur les changements de statut
* **Analytics** - Suivre les taux de conversion et la performance des prospects

<Card title="Guide d'intégration CRM" icon="diagram-project" href="/fr/features/crm/overview">
  En savoir plus sur l'intégration CRM et les bonnes pratiques
</Card>