API de Vendas
Endpoints para gerenciar oportunidades de venda e o pipeline comercial programaticamente.
Listar oportunidades
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) |
stage | string | Filtrar por etapa do pipeline |
status | string | open, won, lost |
assigned_to | uuid | Filtrar por responsável |
min_value | number | Valor mínimo |
max_value | number | Valor máximo |
sort | string | Campo de ordenação |
{
"data": [
{
"id": "uuid",
"name": "Projeto ERP - Empresa ABC",
"value": 75000.00,
"stage": "proposal",
"status": "open",
"probability": 60,
"expected_close_date": "2026-04-15",
"lead_id": "uuid",
"assigned_to": "uuid",
"company": "Empresa ABC",
"contact": "Maria Silva",
"tags": ["enterprise", "erp"],
"created_at": "2026-02-20T14:00:00Z",
"updated_at": "2026-03-12T09:45:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 42,
"total_pages": 3
}
}
Buscar oportunidade por ID
Retorna a oportunidade com histórico completo de atividades e movimentações de etapa.
Criar oportunidade
Body:
{
"name": "Implementação CRM - Cliente Y",
"value": 120000.00,
"stage": "qualification",
"lead_id": "uuid",
"assigned_to": "uuid",
"expected_close_date": "2026-06-30",
"tags": ["crm", "mid-market"]
}
name, value, stage
Resposta (201): Objeto da oportunidade criada.
Atualizar oportunidade
{
"stage": "negotiation",
"value": 110000.00,
"probability": 75
}
Ao alterar a etapa (stage), o histórico de movimentação é registrado automaticamente com data e hora.
Fechar oportunidade
Deal ganho
{
"closed_value": 110000.00,
"notes": "Contrato assinado em 15/03/2026"
}
Deal perdido
{
"loss_reason": "competitor",
"notes": "Cliente optou pelo concorrente X"
}
Listar etapas do pipeline
Resposta (200):
{
"data": [
{
"id": "uuid",
"name": "Prospecção",
"order": 1,
"default_probability": 10
},
{
"id": "uuid",
"name": "Qualificação",
"order": 2,
"default_probability": 25
}
]
}
Atividades da oportunidade
Listar atividades
GET /v1/deals/:id/activities
Criar atividade
POST /v1/deals/:id/activities
{
"type": "call",
"description": "Ligação de follow-up sobre proposta",
"date": "2026-03-15T14:00:00Z",
"duration_minutes": 15
}
note, call, email, meeting, task
Use filtros combinados para criar relatórios customizados. Por exemplo, ?status=won&sort=-closed_value&per_page=10 retorna os 10 maiores deals ganhos.
Próximos passos
