Início rápido
Crie um cliente, uma oportunidade e uma atividade pela API Colmeia.
Início rápido
Este fluxo usa cURL para criar um cliente PJ, uma oportunidade e uma atividade vinculada. Ao final, você confirma os três recursos com consultas da API v1.
1. Gere uma chave de API
No painel, abra Configurações → Integrações → API, crie uma chave e copie o valor exibido. Ele começa com ea_live_ e só é mostrado integralmente na criação.
2. Exporte a chave no shell
Use uma variável de ambiente; não cole uma chave real no código, repositório ou terminal compartilhado.
Os comandos que capturam IDs usam jq. Se ele não estiver disponível — ou se a API responder um erro sem data.id — a resposta será exibida e você poderá copiar o ID manualmente antes de continuar.
export COLMEIA_API_KEY='ea_live_sua_chave_aqui'3. Crie um cliente PJ
name e type: "PJ" são obrigatórios. O comando abaixo mostra a resposta e guarda data.id em client_id para os próximos passos. Sem jq, copie o valor de data.id quando solicitado.
client_response="$(curl -sS -X POST https://app.usecolmeia.com/api/v1/clients \
-H "Authorization: Bearer $COLMEIA_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"name": "Empresa Exemplo Ltda.",
"type": "PJ"
}')"
printf '%s\n' "$client_response"
client_id=""
if command -v jq >/dev/null 2>&1; then
client_id="$(printf '%s' "$client_response" | jq -r '.data.id // empty')"
else
echo "jq não encontrado; copie data.id da resposta acima." >&2
fi
if [ -z "$client_id" ]; then
read -r -p "Cole data.id para continuar (ou Enter para interromper): " client_id
fi
if [ -z "$client_id" ]; then
echo "client_id ausente; interrompendo antes de criar recursos sem vínculo." >&2
exit 1
fi
printf 'client_id=%s\n' "$client_id"4. Crie uma oportunidade
Associe a oportunidade ao cliente e gere uma chave de idempotência por criação lógica, derivada de client_id. Para replay, repita a mesma chave e o mesmo payload; usar a mesma chave com payload diferente retorna 409. A resposta também é validada antes de avançar para a atividade.
idempotency_key="quickstart-$client_id"
deal_response="$(curl -sS -X POST https://app.usecolmeia.com/api/v1/deals \
-H "Authorization: Bearer $COLMEIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $idempotency_key" \
--data "{
\"title\": \"Oportunidade de integração\",
\"client_id\": \"$client_id\",
\"priority\": \"media\"
}")"
printf '%s\n' "$deal_response"
deal_id=""
if command -v jq >/dev/null 2>&1; then
deal_id="$(printf '%s' "$deal_response" | jq -r '.data.id // empty')"
else
echo "jq não encontrado; copie data.id da resposta acima." >&2
fi
if [ -z "$deal_id" ]; then
read -r -p "Cole data.id para continuar (ou Enter para interromper): " deal_id
fi
if [ -z "$deal_id" ]; then
echo "deal_id ausente; interrompendo antes de criar atividade sem vínculo." >&2
exit 1
fi
printf 'deal_id=%s\n' "$deal_id"5. Crie uma atividade
Registre o próximo acompanhamento com os vínculos do cliente e da oportunidade.
curl -sS -X POST https://app.usecolmeia.com/api/v1/activities \
-H "Authorization: Bearer $COLMEIA_API_KEY" \
-H "Content-Type: application/json" \
--data "{
\"type\": \"follow_up\",
\"title\": \"Acompanhar oportunidade de integração\",
\"client_id\": \"$client_id\",
\"deal_id\": \"$deal_id\"
}"6. Liste os recursos criados
curl -sS "https://app.usecolmeia.com/api/v1/clients?limit=10" \
-H "Authorization: Bearer $COLMEIA_API_KEY"
curl -sS "https://app.usecolmeia.com/api/v1/deals?client_id=$client_id" \
-H "Authorization: Bearer $COLMEIA_API_KEY"
curl -sS "https://app.usecolmeia.com/api/v1/activities?deal_id=$deal_id" \
-H "Authorization: Bearer $COLMEIA_API_KEY"Exemplo JavaScript
O mesmo fluxo cabe em chamadas fetch no servidor. Mantenha a chave em uma variável de ambiente — nunca no código do navegador.
const baseUrl = 'https://app.usecolmeia.com/api/v1';
const headers = {
Authorization: `Bearer ${process.env.COLMEIA_API_KEY}`,
'Content-Type': 'application/json',
};
const request = (path, body, extraHeaders = {}) =>
fetch(`${baseUrl}${path}`, {
method: 'POST',
headers: { ...headers, ...extraHeaders },
body: JSON.stringify(body),
}).then((response) => response.json());
const client = await request('/clients', { name: 'Empresa Exemplo Ltda.', type: 'PJ' });
const idempotencyKey = `quickstart-${client.data.id}`;
const deal = await request(
'/deals',
{ title: 'Oportunidade de integração', client_id: client.data.id, priority: 'media' },
{ 'Idempotency-Key': idempotencyKey },
);
await request('/activities', {
type: 'follow_up',
title: 'Acompanhar oportunidade de integração',
client_id: client.data.id,
deal_id: deal.data.id,
});Consulte a referência da API para os campos opcionais e filtros de cada recurso.