API de gestion de leads - Steer Autos Documentation

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

GET

endpoint

/leads

Obtiene todos los leads con filtros y orden opcionales. Query Parameters:

string

Busqueda global por action, targetName, tag

status

enum

Filtrar por estado: NEW, COMPLETED, NOT_NEEDED

action

string

Filtrar por tipo de accion

targetName

string

Filtrar por nombre del objetivo

tag

string

Filtrar por tag

carId

string

Filtrar por ID de vehiculo asociado

sortBy

enum

Campo de orden: order, status, action, targetName, createdAt

sortOrder

enum

Direccion: asc, desc

Response:

[
  {
    "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

GET

endpoint

/leads/

Obtiene informacion detallada de un lead. Path Parameters:

string

requerido

Lead UUID

Response:

{
  "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

POST

endpoint

/leads/car/

Crea un nuevo lead asociado a un vehiculo. Path Parameters:

carId

string

requerido

Vehicle UUID

Request Body:

{
  "action": "Schedule test drive",
  "targetName": "Jane Doe",
  "targetInfo": "[email protected]",
  "tag": "Test Drive",
  "note": "Prefers weekend appointments",
  "status": "NEW",
  "order": 1
}

action

string

requerido

Descripcion de accion (max 200 caracteres)

targetName

string

requerido

Nombre del contacto (max 200 caracteres)

targetInfo

string

requerido

Contacto (telefono o email) (max 500 caracteres)

tag

string

Categoria del lead (max 100 caracteres)

note

string

Notas adicionales (max 1000 caracteres)

status

enum

Estado: NEW (default), COMPLETED, NOT_NEEDED

order

integer

Orden de visualizacion (default: 0)

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "carId": "car_uuid",
  "status": "NEW",
  "action": "Schedule test drive",
  "targetName": "Jane Doe",
  "targetInfo": "[email protected]",
  "tag": "Test Drive",
  "note": "Prefers weekend appointments",
  "order": 1,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Actualizar lead

PATCH

endpoint

/leads/

Actualiza la informacion de un lead existente. Path Parameters:

string

requerido

Lead UUID

Request Body:

{
  "status": "COMPLETED",
  "note": "Test drive completed. Customer very interested."
}

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

{
  "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

GET

endpoint

/leads/car/

Obtiene todos los leads asociados a un vehiculo. Path Parameters:

carId

string

requerido

Vehicle UUID

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

GET

endpoint

/leads/status/

Filtra leads por estado actual. Path Parameters:

status

enum

requerido

Status: NEW, COMPLETED, NOT_NEEDED

Response: Arreglo de leads con ese estado.

Reordenar leads

PATCH

endpoint

/leads/car//reorder

Actualiza en bloque el orden de leads de un vehiculo. Path Parameters:

carId

string

requerido

Vehicle UUID

Request Body:

{
  "leadOrders": [
    { "id": "lead_id_1", "order": 1 },
    { "id": "lead_id_2", "order": 2 },
    { "id": "lead_id_3", "order": 3 }
  ]
}

Response:

{
  "success": true,
  "message": "Leads reordered successfully"
}

Actualizar orden de lead

PATCH

endpoint

/leads//order

Actualiza el orden de un lead individual. Path Parameters:

string

requerido

Lead UUID

Request Body:

{
  "order": 5
}

Eliminar lead

DELETE

endpoint

/leads/

Elimina un lead permanentemente. Path Parameters:

string

requerido

Lead UUID

Response:

{
  "success": true,
  "message": "Lead deleted successfully"
}

Flujo de estado de leads

NEW

Lead creado y requiere accion. Estado por defecto.

COMPLETED

Accion completada exitosamente. Objetivo alcanzado.

NOT_NEEDED

Lead ya no es relevante o fue cancelado.

Casos de uso

Ejemplo 1: Seguimiento de solicitudes de test drive

# 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

# 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": "[email protected]",
    "tag": "Hot Lead",
    "note": "Interested in financing. Call back Tuesday"
  }'

Ejemplo 3: Revision de documentos

# 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": "[email protected]",
    "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

Usa acciones descriptivas

Haz que las acciones sean claras. Bien: “Follow up call about financing”. Mal: “Call”.

Aprovecha tags para organizar

Usa tags consistentes: “Hot Lead”, “Test Drive”, “Documentation”, “Follow-up”.

Mantén notas actualizadas

Agrega notas tras cada interaccion para mantener contexto.

Reordena leads por prioridad

Usa el campo order para priorizar leads. Numeros menores primero.

Limpia leads completados

Archiva o elimina leads completados para mantener limpio el pipeline.

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

Guia de integracion CRM

Aprende mas sobre integracion CRM y mejores practicas

Documentacion de la API

​Resumen

​Endpoints

​Listar todos los leads

​Obtener lead por ID

​Crear lead para vehiculo

​Actualizar lead

​Obtener leads por vehiculo

​Obtener leads por estado

​Reordenar leads

​Actualizar orden de lead

​Eliminar lead

​Flujo de estado de leads

​Casos de uso

​Ejemplo 1: Seguimiento de solicitudes de test drive

​Ejemplo 2: Seguimiento de llamadas

​Ejemplo 3: Revision de documentos

​Codigos de error

​Mejores practicas

​Tips de integracion

Guia de integracion CRM

Resumen

Endpoints

Listar todos los leads

Obtener lead por ID

Crear lead para vehiculo

Actualizar lead

Obtener leads por vehiculo

Obtener leads por estado

Reordenar leads

Actualizar orden de lead

Eliminar lead

Flujo de estado de leads

Casos de uso

Ejemplo 1: Seguimiento de solicitudes de test drive

Ejemplo 2: Seguimiento de llamadas

Ejemplo 3: Revision de documentos

Codigos de error

Mejores practicas

Tips de integracion