# API REST para CRM com webhooks assinados | AiCrm

> CRM com API REST pública: crie e consulte contatos com um cabeçalho X-Api-Key, até 20 chaves por integração e webhooks de saída assinados com HMAC-SHA256. Cadastro de leads do seu site sem duplicatas.

- **Fonte (source):** https://aistohire.com/pt/aicrm-crm-leve-com-api-109/f/api-rest-crm-webhooks-assinados
- **Plataforma (platform):** AIstoHire
- **Idioma (language):** pt

## Em resumo

- API REST pública com várias API keys e webhooks assinados
- Registe customers a partir do seu site, formulário ou backend com uma chamada HTTP, e receba cada alteração no seu servidor assinada com HMAC-SHA256.
- Registo de customers com uma única chamada
- Sem duplicados por design
- Até 20 chaves nomeadas

## API REST pública com várias API keys e webhooks assinados

AiCrm, a app de CRM da AIsToHire, expõe uma API REST pública sobre os seus próprios customers. Com uma API key na cabecera «X-Api-Key» pode criar, listar, consultar, atualizar e apagar customers, e adicionar atividades a qualquer um deles, a partir do formulário do seu site, do seu chatbot, de um Zap, de um script Python ou do seu próprio backend. As respostas são JSON com o formato `{ success, data }`, e o limite é de 100 pedidos por minuto e API key.

O registo via API não duplica: se o email que envia já existe na sua base, o AiCrm atualiza a ficha que já tinha (completa o telefone, o nome ou a empresa que faltavam, une as tags/labels de contacto) e regista um novo envio na sua timeline, devolvendo HTTP 200; se for novo, cria-o e devolve 201. Cada customer que entra via API é automaticamente etiquetado como `api-lead`, mantém as tags/labels de contacto que enviar e guarda o `subId` de origem, além do país, do IP e do navegador de onde chegou.

Pode ter até 20 API keys com nome próprio, além da chave interna da app. Assim, atribui uma API key diferente a cada integração —o site, o formulário da campanha de maio, o estagiário, o fornecedor— e revoga-a individualmente quando essa integração termina, sem afetar as outras. O valor completo de uma API key é mostrado uma única vez, ao criá-la; depois só é visível mascarado na listagem.

Na outra direção, os webhooks avisam os seus sistemas. Configura até 10 destinos, escolhe a que eventos cada um se subscreve (`customer.created`, `customer.updated`, `customer.deleted`, `activity.created`) e o AiCrm faz um POST para o seu URL com as cabeceras `X-AiCrm-Event` e `X-AiCrm-Signature: sha256=…`, a assinatura HMAC-SHA256 do corpo com o segredo desse webhook, para que verifique que a entrega é legítima. Ao guardar o URL, uma proteção anti-SSRF rejeita localhost, 127.0.0.0/8, 10.x, 192.168.x, 172.16-31.x, ::1, 0.0.0.0 e os domínios «.local» e «.internal».

## O que inclui

- **Registo de customers com uma única chamada** — um POST para `/api/apps/public/crm/customers` com o email e as tags/labels de contacto que quiser, e o lead já está no seu CRM classificado.
- **Sem duplicados por design** — se o email já existe, a ficha é atualizada e o novo envio é registado na sua timeline em vez de criar uma segunda ficha.
- **Até 20 chaves nomeadas** — uma por integração, revogável separadamente. Se uma chave for vazada, você apaga essa e nada mais para de funcionar.
- **Webhooks assinados com HMAC-SHA256** — você verifica o cabeçalho HTTP `X-AiCrm-Signature` com seu segredo e sabe que o aviso vem do seu CRM e não de um terceiro.
- **Proteção anti-SSRF incluída** — o aplicativo se recusa a entregar webhooks para localhost ou para faixas de rede privadas, assim, seu CRM não pode ser usado para sondar uma rede interna.
- **CRUD completo, não apenas adições** — listar com paginação e filtros (busca, status, tags, país), consultar um contato com sua atividade, atualizá-lo, excluí-lo e registrar atividades para ele.
- **Origem rastreada automaticamente** — cada adição via API salva o `subId` que você envia mais o país, o IP e o navegador, e é marcada como `api-lead` para filtrá-la depois no aplicativo.
- **Testes sem adivinhação** — o aplicativo traz a documentação dos endpoints com um exemplo de `curl` copiável e um botão para enviar uma entrega de teste a cada webhook, com o status e a hora da última tentativa.

## Perguntas frequentes

### Como crio um contato no CRM a partir do meu site?

Você faz um POST para `/api/apps/public/crm/customers` com o cabeçalho `X-Api-Key` e um JSON com pelo menos o e-mail ou o telefone. Pode enviar também nome, telefone, empresa, país, status, notas, tags e um `subId` para identificar a campanha ou o formulário de origem. O AiCrm retorna 201 se o criar e 200 se esse contato já existia.

### O que acontece se o mesmo e-mail for enviado duas vezes pela API?

Não é duplicado. O AiCrm procura o e-mail (ou o telefone, se não enviar e-mail) e, se o encontrar, atualiza o registro existente preenchendo os campos que estavam vazios, combina as novas tags com as que já tinha e registra o novo envio na sua timeline de atividade. A resposta indica que o contato já existia e retorna o seu id.

### Quantas API keys posso ter e posso revogar apenas uma?

Pode criar até 20 chaves com nome próprio, além da chave interna da app, que não pode ser apagada. Cada chave é eliminada de forma independente, assim, pode dar uma diferente a cada integração e revogá-la sem afetar as restantes. O valor completo é mostrado apenas no momento da criação; depois aparece mascarado na lista. Todas as chaves partilham o limite de 100 pedidos por minuto por chave.

### Como verifico que um webhook vem realmente do meu CRM?

Cada entrega inclui o cabeçalho `X-AiCrm-Signature: sha256=<firma>`, que é o HMAC-SHA256 do corpo exato do pedido, usando o segredo que a app lhe mostra ao criar o webhook. Calcule esse HMAC no seu servidor sobre o corpo recebido e compare-o. Além disso, viaja o cabeçalho `X-AiCrm-Event` com o nome do evento: `customer.created`, `customer.updated`, `customer.deleted` ou `activity.created`.

### O que acontece se o meu endpoint de webhook estiver inativo?

A entrega é feita com o melhor esforço: o AiCrm espera até 5 segundos e, se falhar, tenta novamente após um segundo e meio. Não há fila persistente de novas tentativas, por isso, uma falha prolongada do seu servidor pode fazer com que perca avisos; nesse caso, reconcilie com um GET para `/api/apps/public/crm/customers`. A app mostra-lhe o estado e a hora da última tentativa de cada webhook, e pode lançar uma entrega de teste quando quiser.

- [AiCrm — CRM leve com API para cadastrar clientes de qualquer sistema](https://aistohire.com/pt/aicrm-crm-leve-com-api-109)

## Sobre a plataforma

**AiCrm — CRM leve com API para cadastrar clientes de qualquer sistema** — uma aplicação de AIstoHire. Disponível em: https://aistohire.com/pt/aicrm-crm-leve-com-api-109/f/api-rest-crm-webhooks-assinados

### Outros idiomas

- `es`: https://aistohire.com/es/aicrm-crm-ligero-con-api-109/f/api-rest-crm-webhooks-firmados
- `en`: https://aistohire.com/aicrm-lightweight-crm-with-api-109/f/api-rest-crm-signed-webhooks
- `fr`: https://aistohire.com/fr/aicrm-crm-leger-avec-api-109/f/api-rest-crm-webhooks-signes
- `it`: https://aistohire.com/it/aicrm-crm-leggero-con-api-109/f/api-rest-crm-webhook-firmati
- `de`: https://aistohire.com/de/aicrm-leichtes-crm-mit-api-109/f/api-rest-crm-signierte-webhooks
- `bg`: https://aistohire.com/bg/aicrm-lesen-crm-s-api-za-upravlenie-na-klienti-i-liydove-109/f/rest-api-crm-podpisani-uebhukove
- `ja`: https://aistohire.com/ja/aicrm-lightweight-crm-with-api-109/f/crm-rest-api-signed-webhooks
- `nl`: https://aistohire.com/nl/aicrm-eenvoudige-crm-met-api-om-klanten-en-leads-te-beheren-109/f/rest-api-crm-ondertekende-webhooks
- `ko`: https://aistohire.com/ko/aicrm-api-gyeongnyang-crm-109/f/crm-rest-api-seomyeong-webhook
- `sv`: https://aistohire.com/sv/aicrm-enkelt-crm-med-api-for-att-hantera-kunder-och-leads-109/f/rest-api-crm-signerade-webhooks
- `da`: https://aistohire.com/da/aicrm-enkelt-crm-med-api-til-at-styre-kunder-og-leads-109/f/rest-api-crm-signerede-webhooks
- `ar`: https://aistohire.com/ar/aicrm-nzam-crm-bsit-ma-api-lidara-alamla-walamla-almhtmlin-109/f/crm-rest-api-webhooks
- `no`: https://aistohire.com/no/aicrm-enkelt-crm-med-api-for-a-styre-kunder-og-leads-109/f/rest-api-crm-signerte-webhooks
- `fi`: https://aistohire.com/fi/aicrm-yksinkertainen-crm-rajapinnalla-asiakkaille-ja-liideille-109/f/crm-rest-api-allekirjoitetut-webhookit
- `zh`: https://aistohire.com/zh/ai-crm-rest-api-webhooks-109/f/crm-rest-api-webhook
- `pl`: https://aistohire.com/pl/aicrm-prosty-crm-z-api-do-zarzadzania-klientami-i-leadami-109/f/api-rest-crm-podpisane-webhooki
- `he`: https://aistohire.com/he/aicrm-crm-pshot-am-api-lnihol-lkochot-vlidim-109/f/api-rest-crm-webhooks-chatumim
- `cs`: https://aistohire.com/cs/aicrm-jednoduche-crm-s-api-pro-spravu-klientu-a-leadu-109/f/rest-api-crm-podepsane-webhooky
- `id`: https://aistohire.com/id/aicrm-crm-sederhana-dengan-api-untuk-mengelola-pelanggan-dan-lead-109/f/api-rest-crm-webhook-bertanda-tangan
