Introdução
Bem-vindo à documentação da API Colmeia. Integre gestão de campanhas, clientes e automação de marketing digital em sua aplicação.
Documentação da API Colmeia
Integre a gestão de marketing digital diretamente em suas aplicações. Acesse CRM, tarefas, projetos, atividades e WhatsApp de forma programática.
API RESTful
A API Colmeia é RESTful, utiliza JSON para requests/responses e autenticação via API Key no header Authorization.
O que a API oferece
┌─────────────────────────────────────────────────────────────┐
│ Sua Aplicação │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ API Colmeia │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ • Autenticação por API Key │ │
│ │ • CRM de Clientes (PF/PJ) │ │
│ │ • Pipeline de Negócios (Deals) │ │
│ │ • Projetos e Tarefas (Kanban) │ │
│ │ • Gestão de Campanhas │ │
│ │ • Atividades e Interações │ │
│ │ • WhatsApp (contatos + envio de mensagens) │ │
│ │ • Webhooks para eventos em tempo real │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘Por que usar a API Colmeia?
| Benefício | Descrição |
|---|---|
| Integração Completa | Conecte seu sistema ao Colmeia sem precisar acessar a interface web |
| Automação | Crie clientes, deals, tarefas e atividades automaticamente |
| Sincronização | Mantenha seus sistemas sincronizados via webhooks |
| Segurança | Autenticação via API Key com escopo por time |
Primeiros Passos
Obtenha suas credenciais
Acesse Configurações → Integrações → API no painel do Colmeia e gere sua chave de API.
Cada chave está vinculada ao seu time e tem acesso completo aos recursos do time.
Configure a autenticação
Todas as requisições devem incluir o header Authorization com sua API Key.
Authorization: Bearer ea_live_sua_chave_aquiFaça sua primeira requisição
Teste a conexão listando seus clientes:
curl -X GET https://app.sonarbr.io/api/v1/clients \
-H "Authorization: Bearer ea_live_sua_chave_aqui" \
-H "Content-Type: application/json"Base URL
Todas as requisições devem ser feitas para:
https://app.sonarbr.io/api/v1Fluxo Típico de Integração
1. Criar Cliente → POST /v1/clients
↓
2. Criar Negócio (Deal) → POST /v1/deals
↓
3. Criar Projeto → POST /v1/projects
↓
4. Adicionar Tarefas → POST /v1/tasks
↓
5. Enviar WhatsApp → POST /v1/whatsapp/messages
↓
6. Acompanhar Eventos → Webhooks configuradosRecursos Disponíveis
Autenticação
Como autenticar suas requisições e gerenciar API Keys
Clientes
Gerenciar clientes (Pessoa Física e Jurídica)
Negócios
Gerenciar pipeline de vendas
Projetos
Gerenciar projetos por squad
Tarefas
Gerenciar tarefas em kanban
Campanhas
Gerenciar campanhas de marketing vinculadas a projetos
Atividades
Registrar e acompanhar atividades e interações
Gerenciar contatos e enviar mensagens via WhatsApp
Webhooks
Configurar endpoints para receber eventos
Conceitos Importantes
Times (Teams)
Todos os recursos pertencem a um time. Sua API Key está vinculada a um time específico e só pode acessar recursos desse time.
Campanhas vs Negócios
- Campanha (Campaign): Um projeto de marketing em execução (campanha de mídia paga, produção de conteúdo, gestão de redes sociais, etc.)
- Negócio (Deal): Uma oportunidade comercial no pipeline (potencial cliente interessado nos serviços da agência)
Clientes
Clientes podem ser:
- Pessoa Física (PF): CPF, RG, dados pessoais
- Pessoa Jurídica (PJ): CNPJ, razão social, dados empresariais
Fases e Status
- Campanhas: Fases configuráveis no kanban (briefing → planejamento → execução → análise → concluída)
- Negócios: Pipeline comercial (lead → qualificado → proposta → negociação → ganho/perdido)
- Projetos: Status
backlog,active,completed - Tarefas: Organizadas em colunas customizáveis por projeto (
backlog,a-fazer,em-andamento,revisao,concluidopor padrão)
Limites de Uso
A API aplica rate limit por IP de origem:
| Escopo | Limite |
|---|---|
/api/* | 60 requisições/minuto por IP |
Exceder o limite resulta em resposta 429 Too Many Requests. Implemente retry com backoff exponencial.