Referência da API

Documentação completa de todos os endpoints disponíveis na API Colmeia.

Base URL

https://app.sonarbr.io/api/v1

Endpoints Disponíveis

Clientes

Gerenciar clientes Pessoa Física e Jurídica.

GET /v1/clients — Listar clientes
POST /v1/clients — Criar cliente
GET /v1/clients/:id — Buscar cliente
PUT /v1/clients/:id — Atualizar cliente
DELETE /v1/clients/:id — Desativar cliente

Negócios (Deals)

Gerenciar pipeline comercial.

GET /v1/deals — Listar negócios
POST /v1/deals — Criar negócio
GET /v1/deals/:id — Buscar negócio
PUT /v1/deals/:id — Atualizar negócio
DELETE /v1/deals/:id — Arquivar negócio

Projetos

Gerenciar projetos vinculados a squads.

GET /v1/projects — Listar projetos
POST /v1/projects — Criar projeto
GET /v1/projects/:id — Buscar projeto
PUT /v1/projects/:id — Atualizar projeto
DELETE /v1/projects/:id — Arquivar projeto

Tarefas

Gerenciar tarefas em kanban.

GET /v1/tasks — Listar tarefas
POST /v1/tasks — Criar tarefa
GET /v1/tasks/:id — Buscar tarefa
PUT /v1/tasks/:id — Atualizar tarefa
DELETE /v1/tasks/:id — Excluir tarefa

Campanhas

Gerenciar campanhas de marketing vinculadas a projetos.

GET /v1/campaigns — Listar campanhas
POST /v1/campaigns — Criar campanha
GET /v1/campaigns/:id — Buscar campanha
PUT /v1/campaigns/:id — Atualizar campanha
DELETE /v1/campaigns/:id — Cancelar campanha

Atividades

Registrar e acompanhar atividades e interações.

GET /v1/activities — Listar atividades
POST /v1/activities — Criar atividade
GET /v1/activities/:id — Buscar atividade
PUT /v1/activities/:id — Atualizar atividade
DELETE /v1/activities/:id — Excluir atividade

Gerenciar contatos e enviar mensagens via WhatsApp.

GET /v1/whatsapp/contacts — Listar contatos
POST /v1/whatsapp/contacts — Criar contato
PUT /v1/whatsapp/contacts/:id — Atualizar contato
POST /v1/whatsapp/messages — Enviar mensagem

Webhooks

Configurar endpoints para receber eventos.

GET /v1/webhooks — Listar webhooks
POST /v1/webhooks — Criar webhook
GET /v1/webhooks/:id — Buscar webhook
PUT /v1/webhooks/:id — Atualizar webhook
DELETE /v1/webhooks/:id — Excluir webhook

Formato das Respostas

Sucesso

{
  "success": true,
  "data": {
    // Dados da resposta
  }
}

Sucesso com Paginação

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Erro

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Campo 'title' é obrigatório"
  }
}

Códigos HTTP

Código	Descrição
`200`	OK — Requisição bem-sucedida
`201`	Created — Recurso criado com sucesso
`400`	Bad Request — Parâmetros inválidos
`401`	Unauthorized — Falha na autenticação
`404`	Not Found — Recurso não encontrado
`409`	Conflict — Operação bloqueada por dependências (ex: DELETE de contato com conversas)
`422`	Unprocessable Entity — Registro duplicado
`429`	Too Many Requests — Rate limit excedido
`500`	Internal Server Error — Erro interno
`502`	Bad Gateway — Falha em serviço externo (ex: WhatsApp)

Códigos de Erro

Código	Descrição
`UNAUTHORIZED`	Autenticação falhou
`NOT_FOUND`	Recurso não encontrado
`VALIDATION_ERROR`	Erro de validação
`DUPLICATE_ENTRY`	Registro duplicado
`CONFLICT`	Operação bloqueada por dependências
`BAD_GATEWAY`	Falha em serviço externo
`INTERNAL_ERROR`	Erro interno

Autenticação

Todas as requisições requerem autenticação via header Authorization:

Authorization: Bearer ea_live_sua_chave_aqui
Content-Type: application/json

Veja mais em Autenticação.

Paginação

Endpoints que retornam listas suportam paginação:

Parâmetro	Padrão	Máximo	Descrição
`page`	1	—	Número da página
`limit`	20	100	Itens por página

Ordenação

Use o parâmetro sort para ordenar resultados:

# Ordenar por data de criação (mais recente primeiro)
GET /v1/clients?sort=-created_at

# Ordenar por nome (alfabético)
GET /v1/clients?sort=full_name

Prefixo	Direção
(nenhum)	Ascendente (A-Z, 0-9)
`-`	Descendente (Z-A, 9-0)

Datas e Horários

Datas usam formato ISO 8601: YYYY-MM-DD
Timestamps incluem timezone: 2026-02-04T10:30:00Z
Sempre retornamos em UTC