API REST do CRM: o dia em que pediram acesso ao meu banco
Um integrador pediu usuário e senha do banco para puxar dados. A resposta certa era outra, e ela já estava pronta no sistema.
Um parceiro nos pediu usuário e senha do banco. Foi tão natural na conversa que eu quase mandei. "É só leitura, a gente puxa direto da tabela." Parei porque alguém do time perguntou como a gente ia revogar aquilo depois, e eu não soube responder. A API REST do CRM existe exatamente para essa conversa não precisar acontecer.
Acesso direto ao banco não tem escopo, não tem prazo de validade, não tem registro de quem usou e não tem como cortar sem trocar a senha do mundo inteiro. Token de API tem tudo isso. Aprendi do jeito difícil que a diferença entre os dois só aparece no dia em que você precisa desligar o acesso às pressas.
Aqui você vai ver o que a API entrega, como o token é guardado, o que o filtro de autenticação verifica em cada chamada e como eu organizo a entrega para um integrador externo. Para o lado de eventos em tempo real, o complemento está em webhooks do CRM.
O que a API REST do CRM expõe
As rotas ficam no grupo v1 do CRM, protegidas pelo filtro de autenticação. A tabela abaixo é o mapa do que dá para consultar e do que dá para criar ou acionar.
| Recurso | Consulta | Escrita e ação |
|---|---|---|
| Contatos | Listagem e consulta por id | Criação de contato |
| Mensagens | Mensagens de uma conversa | Envio de mensagem |
| Conversas | Listagem e consulta por id | Sem escrita |
| Tags | Listagem | Sem escrita |
| Fluxos | Listagem e consulta por id | Criação de fluxo |
| Campanhas | Listagem e consulta por id | Criação, disparo e pausa |
| Usuários | Listagem e consulta por id | Sem escrita |
| Contratos | Listagem e consulta por id | Sem escrita |
O token e por que ele fica guardado por hash
O token é armazenado por hash, com um prefixo que permite identificar qual credencial é qual sem guardar o segredo em texto. Isso resolve um problema chato do dia a dia: quando existem seis integrações ativas e uma delas está sendo abusada, você precisa saber qual desligar. O prefixo te diz. O hash garante que nem quem lê a tabela consegue reconstruir a chave.
- Geração e revogação do token acontecem dentro do próprio CRM.
- Escopos por endpoint, para que um parceiro de leitura não consiga disparar campanha.
- Status ativo, que permite desligar sem apagar o histórico da credencial.
- Expiração, para que token esquecido morra sozinho em vez de viver para sempre.
- Limitação de requisições, que segura integração mal comportada antes de virar problema.
- Auditoria de uso e atualização de último acesso, para saber quem ainda está consumindo.
O que o filtro verifica em cada chamada
O filtro de autenticação aplica escopo, expiração, limite de requisições e isolamento de empresa quando o schema e a configuração exigidos estão disponíveis. Esse "quando" merece atenção durante a implantação: os recursos de hash com prefixo, escopos e auditoria dependem das estruturas dos scripts SQL correspondentes do CRM. Se os scripts não foram aplicados, você acha que está protegido e não está.
Como eu entrego acesso para um integrador
- Pergunte o caso de uso primeiroAntes de gerar qualquer coisa, escreva o que o parceiro vai fazer. Metade dos pedidos de acesso amplo vira acesso a dois endpoints quando você pergunta.
- Gere um token por integraçãoNunca compartilhe o mesmo token entre dois sistemas. No dia de revogar, você vai derrubar os dois e descobrir isso no pior momento.
- Restrinja o escopo ao mínimoLeitura de contatos não precisa de permissão para disparar campanha. Escopo largo é conveniência hoje e incidente depois.
- Defina expiração desde o começoColoque prazo mesmo em integração permanente. Renovar de tempos em tempos força alguém a revisar se aquilo ainda é usado.
- Teste o limite de requisiçõesPeça para o parceiro rodar a carga real antes do go-live. Descobrir o limite em produção é uma experiência que dispensa repetição.
- Marque uma revisão na agendaA cada trimestre, olhe a auditoria de uso e o último acesso. Token sem uso há meses é token para revogar.
Campanha por API pede combinado extra
Consultar dado é uma coisa. Disparar campanha por API é outra, porque o efeito sai do sistema e chega no cliente. Aqui a gente combinou uma regra simples: quem tem escopo de disparo precisa ter dono nomeado dentro da empresa, e não só do lado do parceiro. Já vi campanha ser disparada por integração em horário ruim porque ninguém tinha combinado janela.
O mesmo raciocínio vale para pausar. A rota de pausa é o freio de emergência, e alguém do seu time precisa saber usar sem depender do integrador estar acordado. Testar o freio antes de precisar dele é a diferença entre incidente e susto.
Isolamento de empresa também na integração
A verificação de empresa acontece no filtro, junto com escopo e expiração. Em grupo com várias empresas, esse é o ponto que eu testo primeiro e testo sempre: gerar um token numa empresa e tentar puxar dado de outra. O resultado precisa ser negativo. O tratamento completo do tema está em isolamento multiempresa em relatórios.
- Token de teste com escopo insuficiente recebe recusa.
- Token expirado recebe recusa.
- Chamada acima do limite recebe recusa.
- Consulta cruzando empresa recebe recusa.
- A auditoria registra a chamada e atualiza o último acesso.
Quando API não é a resposta
Se o parceiro quer apenas olhar número, ele não precisa de API. Precisa de relatório publicado ou de um arquivo exportado, que custa muito menos para manter dos dois lados. A API vale quando existe troca contínua de dado entre sistemas. As alternativas mais leves estão em formatos de exportação, e a rotina automatizada do lado de dentro está em comandos CLI e rotinas agendadas. Para entender o CRM que está por trás desses endpoints, comece por CRM e WhatsApp.
Por onde eu começaria
Liste hoje quantos acessos externos existem na sua empresa e como cada um seria revogado se precisasse ser cortado em dez minutos. Se algum deles for "trocar a senha do banco", você achou o próximo item da lista de tarefas. Comece por ele.