Início Rápido

Comece a usar a API Colmeia em 5 minutos

Início Rápido

Este guia mostra como fazer sua primeira integração com a API Colmeia. Ao final, você terá criado um cliente, um negócio e uma atividade via API.

Pré-requisitos

Obtenha sua API Key

  1. Acesse o painel do Colmeia
  2. Navegue até Configurações → Integrações → API
  3. Clique em Nova Chave
  4. Copie sua chave (formato: ea_live_...)

Guarde sua API Key em segurança. Ela não será exibida novamente!

Crie seu primeiro cliente

Crie um cliente Pessoa Jurídica:

curl -X POST https://app.sonarbr.io/api/v1/clients \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PJ",
    "name": "TechStore Brasil Ltda",
    "email": "marketing@techstore.com.br",
    "cnpj": "12.345.678/0001-90",
    "phone": "+55 11 99999-8888"
  }'
const response = await fetch('https://app.sonarbr.io/api/v1/clients', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SONAR_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'PJ',
    name: 'TechStore Brasil Ltda',
    email: 'marketing@techstore.com.br',
    cnpj: '12.345.678/0001-90',
    phone: '+55 11 99999-8888'
  })
});

const data = await response.json();
console.log('Cliente criado:', data.data.id);
import requests
import os

response = requests.post(
    'https://app.sonarbr.io/api/v1/clients',
    headers={
        'Authorization': f'Bearer {os.environ["SONAR_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'type': 'PJ',
        'name': 'TechStore Brasil Ltda',
        'email': 'marketing@techstore.com.br',
        'cnpj': '12.345.678/0001-90',
        'phone': '+55 11 99999-8888'
    }
)

data = response.json()
print(f"Cliente criado: {data['data']['id']}")

Resposta:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "PJ",
    "name": "TechStore Brasil Ltda",
    "email": "marketing@techstore.com.br",
    "cnpj": "12.345.678/0001-90",
    "phone": "+55 11 99999-8888",
    "status": "active",
    "tags": [],
    "address": null,
    "created_at": "2026-05-18T10:30:00Z",
    "updated_at": "2026-05-18T10:30:00Z"
  }
}

Crie um negócio no pipeline

Crie uma oportunidade comercial associada a esse cliente:

curl -X POST https://app.sonarbr.io/api/v1/deals \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Proposta de Tráfego Pago - TechStore",
    "client_id": "550e8400-e29b-41d4-a716-446655440000",
    "value": 15000,
    "priority": "high",
    "expected_close_date": "2026-06-15"
  }'

Resposta:

{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "title": "Proposta de Tráfego Pago - TechStore",
    "value": 15000,
    "currency": "BRL",
    "phase": "lead",
    "priority": "high",
    "status": "open",
    "client_id": "550e8400-e29b-41d4-a716-446655440000",
    "client": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "TechStore Brasil Ltda"
    },
    "expected_close_date": "2026-06-15",
    "created_at": "2026-05-18T10:31:00Z",
    "updated_at": "2026-05-18T10:31:00Z"
  }
}

Adicione uma atividade

Registre uma interação vinculada ao negócio:

curl -X POST https://app.sonarbr.io/api/v1/activities \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "deal_id": "770e8400-e29b-41d4-a716-446655440002",
    "type": "task",
    "title": "Enviar proposta comercial",
    "description": "Preparar e enviar proposta detalhada de tráfego pago",
    "due_date": "2026-05-25"
  }'

Liste seus clientes

Verifique os clientes cadastrados:

curl -X GET "https://app.sonarbr.io/api/v1/clients?status=active&limit=10" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Resposta:

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "PJ",
      "name": "TechStore Brasil Ltda",
      "email": "marketing@techstore.com.br",
      "cnpj": "12.345.678/0001-90",
      "status": "active",
      "created_at": "2026-05-18T10:30:00Z",
      "updated_at": "2026-05-18T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "pages": 1
  }
}

Próximos Passos

Agora que você fez sua primeira integração, explore mais recursos:

Exemplo Completo

Aqui está um cliente JavaScript reutilizável:

// sonar-client.js
class ColmeiaClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://app.sonarbr.io/api/v1';
  }

  async request(endpoint, options = {}) {
    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error?.message || 'Erro na requisição');
    }

    return response.json();
  }

  // Clientes
  createClient(data) {
    return this.request('/clients', {
      method: 'POST',
      body: JSON.stringify(data)
    });
  }

  listClients(params = {}) {
    const query = new URLSearchParams(params).toString();
    return this.request(`/clients?${query}`);
  }

  // Negócios
  createDeal(data) {
    return this.request('/deals', {
      method: 'POST',
      body: JSON.stringify(data)
    });
  }

  updateDeal(id, data) {
    return this.request(`/deals/${id}`, {
      method: 'PUT',
      body: JSON.stringify(data)
    });
  }

  // Atividades
  createActivity(data) {
    return this.request('/activities', {
      method: 'POST',
      body: JSON.stringify(data)
    });
  }
}

// Uso
const sonar = new ColmeiaClient(process.env.SONAR_API_KEY);

async function criarLead(dadosCliente, valorProposta) {
  const cliente = await sonar.createClient(dadosCliente);

  const deal = await sonar.createDeal({
    title: `Proposta - ${cliente.data.name}`,
    client_id: cliente.data.id,
    value: valorProposta,
    priority: 'high'
  });

  return { cliente: cliente.data, deal: deal.data };
}

Precisa de Ajuda?

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.

Autenticação

Como autenticar suas requisições à API Colmeia usando API Keys.

On this page

Início RápidoPré-requisitosObtenha sua API KeyCrie seu primeiro clienteCrie um negócio no pipelineAdicione uma atividadeListe seus clientesPróximos PassosExemplo CompletoPrecisa de Ajuda?