API — Contatos (/contacts)
CRUD completo de contatos via API: listar com filtros, criar, atualizar, excluir, buscar por telefone e listar negócios e conversas do contato. Inclui todos os parâmetros e o formato da resposta.
API — Contatos
Gerenciamento de contatos (leads, clientes, fornecedores). Base: /api/v1/contacts.

Endpoints
| Método | Path | Descrição |
|---|---|---|
| GET | /contacts | Listar contatos (paginado) |
| POST | /contacts | Criar contato |
| GET | /contacts/by-phone | Buscar contato por telefone |
| GET | /contacts/{id} | Detalhes do contato |
| PUT | /contacts/{id} | Atualizar contato |
| DELETE | /contacts/{id} | Excluir (soft delete) |
| GET | /contacts/{id}/deals | Negócios do contato |
| GET | /contacts/{id}/conversations | Conversas do contato |
GET /contacts — filtros
| Parâmetro | Tipo | Descrição |
|---|---|---|
| search | string | Busca por nome, nome fantasia, e-mail, telefone, celular ou documento |
| type | string | lead, customer, prospect, supplier |
| person_type | string | individual ou company |
| group_id | integer | Grupo do contato |
| assigned_to | integer | Responsável (user_id) |
| source | string | Origem |
| tags | array|string | Tags (array ou separadas por vírgula; combina com AND) |
| is_active | boolean | Ativo/inativo |
| sort_by | string | name, email, type, created_at, updated_at, last_contact_at |
| sort_dir | string | asc ou desc (padrão desc) |
| per_page | integer | Padrão 50, máx 100 |
GET /api/v1/contacts?type=customer&search=joao&per_page=25
POST /contacts — campos
Obrigatório: name. Demais opcionais. Padrões: type=lead, person_type=individual.
| Campo | Tipo | Regras |
|---|---|---|
| name | string | obrigatório, máx 255 |
| trading_name | string | nome fantasia |
| string | e-mail válido | |
| phone / mobile | string | telefone / celular |
| website, company, position | string | dados profissionais |
| document | string | CPF ou CNPJ |
| state_registration / municipal_registration | string | IE / IM |
| person_type | string | individual | company |
| type | string | lead | customer | prospect | supplier |
| source | string | origem |
| contact_group_id | integer | grupo |
| assigned_to | integer | responsável |
| parent_id | integer | contato pai (empresa do funcionário) |
| address, address_number, address_complement, neighborhood, city, state, zip_code, country | string | endereço |
| birth_date | date | data de nascimento |
| tags | array | lista de tags |
| notes | string | máx 5000 |
| custom_fields | object | campos personalizados (chave/valor) |
| notification_settings | object | preferências de notificação |
POST /api/v1/contacts
{
"name": "João Silva",
"email": "joao@email.com",
"phone": "11999887766",
"type": "lead",
"tags": ["vip", "indicação"]
}
Resposta 201 com o contato detalhado e "message": "Contact created successfully."
PUT /contacts/{id}
Aceita os mesmos campos do POST (todos opcionais), mais is_active e bot_protected (boolean). Tags enviadas substituem as anteriores.
GET /contacts/by-phone
Localiza um contato pelos dígitos do telefone/celular (ignora máscara). Útil para resolver o contato a partir do remote_jid recebido em webhooks. Mínimo 8 dígitos, senão 422.
GET /api/v1/contacts/by-phone?phone=558597096994
Retorna o mesmo objeto detalhado do GET /contacts/{id}. Não encontrado ⇒ 404.
Formato da resposta (resumido)
{
"id": 42,
"name": "João Silva",
"trading_name": null,
"display_name": "João Silva",
"person_type": "individual",
"type": "customer",
"email": "joao@email.com",
"phone": "1133334444",
"mobile": "11999887766",
"document": "000.000.000-00",
"source": "whatsapp",
"tags": ["vip"],
"is_active": true,
"group": { "id": 3, "name": "Clientes VIP" },
"assigned_to": { "id": 5, "name": "Maria" },
"deals_count": 2,
"contracts_count": 1,
"created_at": "2026-01-05T08:00:00-03:00",
"updated_at": "2026-03-10T12:00:00-03:00"
}
O detalhe (show, store, update, by-phone) acrescenta: website, company, position, state_registration, municipal_registration, endereço completo, birth_date, notes, custom_fields, notification_settings, parent_id, bot_protected, last_contact_at e employees[] (funcionários vinculados).
GET /contacts/{id}/deals e /conversations
Listas paginadas (padrão 25, máx 100) com os negócios e as conversas do contato, respectivamente. Cada negócio traz id, title, value, currency, status, stage, responsável e datas. Cada conversa traz id, remote_jid, display_name, status, canal, responsável, unread_count e prévia da última mensagem.