Integrações (API e webhooks)

Ligue o Agentti ao seu CRM ou ERP para as empresas salvas e qualificadas chegarem lá sozinhas.

Em Menu → Integrações (só administradores) você liga o Agentti a outro sistema da empresa: CRM, ERP ou planilha automatizada. Assim as empresas não precisam ser exportadas e importadas à mão. Integrações não gastam cota.

São dois jeitos, e dá para usar os dois juntos:

	Chave de API	Webhook
Quem começa	O seu sistema pergunta ao Agentti	O Agentti avisa o seu sistema
Quando	Quando o seu sistema quiser (ex.: a cada hora)	Na hora em que a empresa é salva, qualificada ou removida
Para quê	Ler os projetos e as empresas, buscar o que mudou	Receber cada novidade sem precisar perguntar

Chave de API

Em Chaves de API, dê um nome (ex.: "CRM") e clique em Criar chave.
Copie a chave na hora: ela começa com agi_ e não aparece de novo.
Entregue a chave a quem vai programar a integração.

A chave lê as empresas de todos os projetos da organização. Se ela vazar, clique em Revogar: o acesso cai na hora. A chave para também se o administrador que a criou for desativado; nesse caso, crie outra.

Webhook

Clique em Novo webhook e informe o endereço do seu sistema que vai receber os avisos (começa com https://).
Marque quando avisar: empresa salva num projeto, qualificada ou removida.
Escolha os projetos, ou deixe nenhum marcado para avisar de todos.
Copie o segredo que aparece: o seu sistema usa ele para conferir que o aviso veio mesmo do Agentti.
Clique em Enviar teste para ver se o seu sistema recebe.

Cada aviso leva até 100 empresas. Em Entregas você vê cada envio: se chegou, a resposta do seu sistema e as novas tentativas. Se o seu sistema estiver fora do ar, o Agentti tenta de novo em 1 minuto, 5 minutos, 30 minutos, 2 horas e 12 horas. Depois de 3 dias seguidos sem conseguir entregar, o webhook é desligado e a tela mostra o motivo; quando o seu sistema voltar, clique em Ligar. As empresas desse período podem ser buscadas pela API com "alteradas desde".

Para quem vai programar

API: GET /api/v1/projetos, GET /api/v1/projetos/{id}/empresas e GET /api/v1/empresas/{id}, com o cabeçalho Authorization: Bearer <chave>. Na lista de empresas: alteradas_desde (data e hora), situacao (descobertos, web ou qualificados), limite (até 200) e cursor (o proximo_cursor da página anterior). Até 120 pedidos por minuto por chave. Erros vêm como {"erro": {"codigo", "mensagem"}}.
Webhook: POST com JSON {id, evento, versao, criado_em, projeto, empresas}. A empresa vai no mesmo formato da API, como está na hora do envio. Cabeçalhos: X-Agentti-Evento, X-Agentti-Entrega (o mesmo nas novas tentativas: use para não gravar duas vezes) e X-Agentti-Assinatura (t=<horário>,v1=<HMAC-SHA256> do texto "<horário>.<corpo>" com o segredo). Responda com 2xx em até 10 segundos.
Ordem: os avisos de um mesmo momento saem em ordem (salva, qualificada, removida), mas uma nova tentativa pode chegar depois de um aviso mais recente. Grave pela situacao que vem na empresa, não pela ordem de chegada.
A página Integrações tem o exemplo pronto de como conferir a assinatura.
O identificador estável de uma empresa no Agentti é o id. O cnpj serve para casar com o cadastro do seu sistema; empresas achadas só na web podem vir sem CNPJ.