> ## 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 de leads

> Gestiona leads, sigue interacciones y organiza workflows de ventas

## Resumen

La API de gestion de leads te ayuda a rastrear y gestionar oportunidades de venta para cada vehiculo en tu inventario. Crea tareas accionables, define prioridades y monitorea el estado de los leads en el embudo de ventas.

## Endpoints

### Listar todos los leads

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

Obtiene todos los leads con filtros y orden opcionales.

**Query Parameters:**

<ParamField query="search" type="string">
  Busqueda global por action, targetName, tag
</ParamField>

<ParamField query="status" type="enum">
  Filtrar por estado: `NEW`, `COMPLETED`, `NOT_NEEDED`
</ParamField>

<ParamField query="action" type="string">
  Filtrar por tipo de accion
</ParamField>

<ParamField query="targetName" type="string">
  Filtrar por nombre del objetivo
</ParamField>

<ParamField query="tag" type="string">
  Filtrar por tag
</ParamField>

<ParamField query="carId" type="string">
  Filtrar por ID de vehiculo asociado
</ParamField>

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

<ParamField query="sortOrder" type="enum">
  Direccion: `asc`, `desc`
</ParamField>

**Response:**

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

***

### Obtener lead por ID

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

Obtiene informacion detallada de un lead.

**Path Parameters:**

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

**Response:**

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

***

### Crear lead para vehiculo

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

Crea un nuevo lead asociado a un vehiculo.

**Path Parameters:**

<ParamField path="carId" type="string" required>
  Vehicle UUID
</ParamField>

**Request Body:**

```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>
  Descripcion de accion (max 200 caracteres)
</ParamField>

<ParamField body="targetName" type="string" required>
  Nombre del contacto (max 200 caracteres)
</ParamField>

<ParamField body="targetInfo" type="string" required>
  Contacto (telefono o email) (max 500 caracteres)
</ParamField>

<ParamField body="tag" type="string">
  Categoria del lead (max 100 caracteres)
</ParamField>

<ParamField body="note" type="string">
  Notas adicionales (max 1000 caracteres)
</ParamField>

<ParamField body="status" type="enum">
  Estado: `NEW` (default), `COMPLETED`, `NOT_NEEDED`
</ParamField>

<ParamField body="order" type="integer">
  Orden de visualizacion (default: 0)
</ParamField>

**Response:**

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

***

### Actualizar lead

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

Actualiza la informacion de un lead existente.

**Path Parameters:**

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

**Request Body:**

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

Todos los campos son opcionales. Solo se actualizan los proporcionados.

**Response:**

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

***

### Obtener leads por vehiculo

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

Obtiene todos los leads asociados a un vehiculo.

**Path Parameters:**

<ParamField path="carId" type="string" required>
  Vehicle UUID
</ParamField>

**Query Parameters:**

Las mismas opciones de filtros y orden que `/leads`.

**Response:**

Arreglo de leads ordenados por `order` (ascendente por default).

***

### Obtener leads por estado

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

Filtra leads por estado actual.

**Path Parameters:**

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

**Response:**

Arreglo de leads con ese estado.

***

### Reordenar leads

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

Actualiza en bloque el orden de leads de un vehiculo.

**Path Parameters:**

<ParamField path="carId" type="string" required>
  Vehicle UUID
</ParamField>

**Request Body:**

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

**Response:**

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

***

### Actualizar orden de lead

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

Actualiza el orden de un lead individual.

**Path Parameters:**

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

**Request Body:**

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

***

### Eliminar lead

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

Elimina un lead permanentemente.

**Path Parameters:**

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

**Response:**

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

***

## Flujo de estado de leads

<Steps>
  <Step title="NEW">
    Lead creado y requiere accion. Estado por defecto.
  </Step>

  <Step title="COMPLETED">
    Accion completada exitosamente. Objetivo alcanzado.
  </Step>

  <Step title="NOT_NEEDED">
    Lead ya no es relevante o fue cancelado.
  </Step>
</Steps>

## Casos de uso

### Ejemplo 1: Seguimiento de solicitudes de test drive

```bash theme={null}
# Create test drive lead
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"
  }'
```

### Ejemplo 2: Seguimiento de llamadas

```bash theme={null}
# Create follow-up lead
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"
  }'
```

### Ejemplo 3: Revision de documentos

```bash theme={null}
# Create document review lead
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"
  }'
```

## Codigos de error

| Code                       | Status | Description                     |
| -------------------------- | ------ | ------------------------------- |
| `LEAD_NOT_FOUND`           | 404    | El ID del lead no existe        |
| `CAR_NOT_FOUND`            | 404    | Vehiculo asociado no encontrado |
| `UNAUTHORIZED_LEAD_ACCESS` | 403    | Sin acceso a este lead          |
| `INVALID_LEAD_STATUS`      | 400    | Estado invalido                 |
| `VALIDATION_ERROR`         | 400    | Validacion del body fallo       |

## Mejores practicas

<AccordionGroup>
  <Accordion title="Usa acciones descriptivas">
    Haz que las acciones sean claras. Bien: "Follow up call about financing". Mal: "Call".
  </Accordion>

  <Accordion title="Aprovecha tags para organizar">
    Usa tags consistentes: "Hot Lead", "Test Drive", "Documentation", "Follow-up".
  </Accordion>

  <Accordion title="Mantén notas actualizadas">
    Agrega notas tras cada interaccion para mantener contexto.
  </Accordion>

  <Accordion title="Reordena leads por prioridad">
    Usa el campo order para priorizar leads. Numeros menores primero.
  </Accordion>

  <Accordion title="Limpia leads completados">
    Archiva o elimina leads completados para mantener limpio el pipeline.
  </Accordion>
</AccordionGroup>

## Tips de integracion

La API de leads se integra con:

* **API de vehiculos** - Vincula leads al inventario
* **Sistemas CRM** - Exporta leads a CRMs externos
* **Servicios de Email/SMS** - Notifica cambios de estado
* **Analitica** - Seguimiento de conversion y rendimiento

<Card title="Guia de integracion CRM" icon="diagram-project" href="/es/features/crm/overview">
  Aprende mas sobre integracion CRM y mejores practicas
</Card>