API de Leads
Endpoints para gerenciar leads programaticamente no SalesOS.
Listar leads
Parâmetros de query:
| Parâmetro | Tipo | Descrição |
|---|
page | integer | Página atual (padrão: 1) |
per_page | integer | Itens por página (padrão: 20, máx: 100) |
status | string | Filtrar por status: new, contacted, qualified, converted, discarded |
assigned_to | uuid | Filtrar por responsável |
created_after | datetime | Leads criados após esta data (ISO 8601) |
created_before | datetime | Leads criados antes desta data |
sort | string | Campo de ordenação. Prefixo - para decrescente |
search | string | Busca por nome, e-mail ou empresa |
{
"data": [
{
"id": "uuid",
"name": "Maria Silva",
"email": "maria@empresa.com",
"phone": "+5511999999999",
"company": "Empresa ABC",
"status": "qualified",
"source": "website",
"assigned_to": "uuid",
"custom_fields": {
"segmento": "Tecnologia",
"porte": "Médio"
},
"created_at": "2026-03-01T10:00:00Z",
"updated_at": "2026-03-10T15:30:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 85,
"total_pages": 5
}
}
Buscar lead por ID
Resposta (200): Objeto do lead com todos os campos, incluindo histórico de atividades.
Criar lead
Body:
{
"name": "João Santos",
"email": "joao@empresa.com",
"phone": "+5511988888888",
"company": "Empresa XYZ",
"source": "api",
"assigned_to": "uuid",
"custom_fields": {
"segmento": "Varejo"
}
}
name, email
Resposta (201): Objeto do lead criado.
Se um lead com o mesmo e-mail já existir, a API retorna 409 Conflict com o ID do lead existente.
Atualizar lead
Body: Apenas os campos que deseja alterar.
{
"status": "contacted",
"phone": "+5511977777777"
}
Excluir lead
Resposta (204): Sem conteúdo.
A exclusão é permanente. Para manter o histórico, prefira alterar o status para discarded em vez de excluir.
Converter lead em oportunidade
POST /v1/leads/:id/convert
{
"deal_name": "Projeto XYZ",
"deal_value": 50000,
"pipeline_stage": "qualification"
}
Exemplos de uso
# Listar leads qualificados
curl -X GET "https://api.play2sell.com/v1/leads?status=qualified&sort=-created_at" \
-H "Authorization: Bearer SEU_TOKEN"
const response = await fetch('https://api.play2sell.com/v1/leads?status=qualified', {
headers: {
'Authorization': 'Bearer SEU_TOKEN',
'Content-Type': 'application/json'
}
});
const data = await response.json();
import requests
response = requests.get(
'https://api.play2sell.com/v1/leads',
params={'status': 'qualified', 'sort': '-created_at'},
headers={'Authorization': 'Bearer SEU_TOKEN'}
)
data = response.json()
Próximos passos
