Criar uma chave de API e conectar o seu sistema

A API deixa o seu sistema (um ERP, uma planilha, uma automação do n8n, Make ou Zapier) perguntar ao Hades o que ele já sabe: os contatos, as reuniões com a análise, os negócios e os pipelines. Ela é do plano Oráculo pra cima. Quem cria e revoga chaves é o dono ou um gestor, em Integrações. Cada sistema ganha a sua chave, e você revoga quando quiser.

Criar a chave

1. Clique na sua foto (ou nas iniciais), no pé do menu da esquerda, e escolha Integrações.
2. Role até a seção API e MCP.
3. Em Nome da chave, escreva pra que ela serve, por exemplo ERP, n8n ou Claude. Serve só pra você reconhecer depois.
4. Marque as permissões extras só se o seu sistema precisa delas (veja a seção abaixo). Sem marcar nada, a chave só lê.
5. Clique em Criar chave.
6. A chave aparece uma vez só, começando com hdk_. Clique em Copiar, cole no lugar seguro do seu sistema e clique em Já guardei.

Usar a chave

Em todo pedido, mande a chave no cabeçalho Authorization. Esta é a conferência mais simples (copie o endereço base que a tela mostra pra sua conta):

curl https://hades-copilot.com.br/api/v1 \
  -H "Authorization: Bearer hdk_..."

A resposta diz de qual empresa é a chave e o que ela pode fazer. As rotas que existem hoje:

• GET /api/v1/clientes — os contatos. Aceita busca, criado_desde, limite e pagina.
• GET /api/v1/clientes/{id} — a ficha: dados do contato, reuniões, negócios e propostas.
• GET /api/v1/reunioes — as reuniões com resumo e desfecho. Aceita desde, ate e contato_id.
• GET /api/v1/reunioes/{id} — a análise completa de uma reunião.
• GET /api/v1/negocios — os negócios. Aceita pipeline_id, etapa e contato_id.
• GET /api/v1/pipelines — os pipelines e as etapas de cada um (use pra saber os nomes das etapas).
• POST /api/v1/clientes — cria um contato (só com a permissão de escrita).
• PATCH /api/v1/negocios/{id} — muda a etapa e/ou o valor de um negócio (só com a permissão de escrita).

As listas vêm de 50 em 50 por padrão, e o máximo é 100 por página (use limite e pagina). Datas são AAAA-MM-DD e dinheiro vem em centavos.

As permissões da chave

• Leitura — sempre ligada. Lê contatos, reuniões, negócios e pipelines.
• Pode ler a transcrição das reuniões — desligada de fábrica. A transcrição é a fala do seu cliente: ligue só se o seu sistema precisa dela. Sem essa permissão, pedir ?transcricao=1 volta o erro 403.
• Pode criar contatos e mover negócios — desligada de fábrica. Com ela, a chave cria contato (POST /api/v1/clientes) e muda etapa ou valor de um negócio (PATCH /api/v1/negocios/{id}). Nada é apagado, e cada escrita fica registrada na lista Últimas escritas pela API e pelo MCP, no fim da seção.

Criar contato com um telefone ou e-mail que já existe na sua conta não cria um repetido: a resposta devolve o contato que já estava lá. Mover negócio segue as mesmas regras da tela de Negócios: a etapa precisa existir no pipeline daquele negócio, e uma etapa que registra a venda no pixel pede o valor. Veja o quadro de negócios.

Limites

• Até 60 pedidos por minuto por chave (a API e o MCP contam juntos). O limite zera a cada minuto.
• Até 30 escritas a cada 10 minutos por chave.
• A chave só enxerga a sua empresa. Pedir um id que é de outra conta responde "não encontrado".
• A chave não apaga nada e não mexe em plano, cobrança ou equipe.

Se deu erro

• 401 — faltou a chave, ou ela está errada ou foi revogada. Confira o cabeçalho Authorization: Bearer hdk_....
• 402 — o plano da empresa não inclui a API. Ela é do Oráculo pra cima. Veja o que cada plano tem.
• 403 — a chave não tem a permissão que esse pedido exige (transcrição ou escrita). Crie outra chave com a permissão marcada.
• 404 — não achou aquele id nesta conta.
• 400 — um parâmetro está errado; a resposta diz qual.
• 422 — na escrita: a etapa não existe no pipeline do negócio, ou a etapa exige valor.
• 429 — passou do limite de pedidos. A resposta traz Retry-After com os segundos de espera.
• 503 — o Hades não conseguiu conferir agora. Tente de novo em instantes; nada foi gravado.

Revogar

Em Integrações, na linha da chave, clique em Revogar e confirme. O sistema que usa aquela chave para de conseguir acessar na hora, e não dá pra desfazer. Revogar é sempre possível, mesmo se a empresa mudar de plano.

Quer que o Hades avise o seu sistema quando algo acontecer, sem você perguntar? Veja receber avisos no seu sistema. Quer conectar um assistente de IA? Veja conectar um assistente de IA (MCP).