API, webhooks e MCP: ligue o seu sistema e o seu agente de IA ao FluxiaCRM

Três jeitos de ligar o CRM ao resto da empresa

Os três usam a mesma chave, criada por um admin da conta em Configurações › Chaves de API e MCP. Cada chave tem um nome e escopos, que dizem o que ela pode ler e mexer. Tudo o que uma chave muda aparece no Histórico de ações com o nome dela.

• API REST (v1): o seu sistema chama o CRM. São 92 rotas em 14 grupos, de leads e conversas a funis, disparos e fluxos.
• Webhooks: o CRM chama o seu sistema quando algo acontece (mensagem recebida, negócio ganho, solicitação aberta), com assinatura para você conferir a origem.
• MCP: o seu agente de IA conversa com o CRM por 48 ferramentas e faz o trabalho por você.

O que a API REST faz

• Leads e captação: POST /leads acha ou cria o contato pelo telefone, abre o card no funil, cria a tarefa e pode mandar a primeira mensagem no WhatsApp. O CORS é aberto, então o formulário do site posta direto.
• Conversas e mensagens: ler o histórico, mandar mensagem pelo número certo, deixar nota interna para a equipe, atribuir a conversa e ligar ou desligar a IA nela.
• Negócios, funis e tarefas: criar, mover de etapa, editar, ver o histórico do card.
• Disparos, cadências e mensagens agendadas, com o mesmo ritmo e o mesmo descadastro da tela.
• Memória do cliente: o histórico de compras e os sinais de recompra de cada contato.
• Fluxos (o chatbot visual), automação de comentário do Instagram, canais, etiquetas e agentes de IA.

Do formulário do site ao WhatsApp, pela API

1. 1

   O formulário manda o lead

   Nome e telefone vão para POST /leads, com uma chave que só pode criar contato. Se a pessoa já existe, o CRM acha pelo telefone em vez de duplicar.

2. 2

   O CRM organiza

   O card abre no funil e na etapa que você escolheu, com a origem e os UTMs na observação, e a tarefa de atender nasce junto.

3. 3

   O WhatsApp abre a conversa

   Com send_whatsapp ligado, o lead recebe a sua mensagem de abertura. Quando ele responde, o agente de IA do canal assume.

Webhooks: o CRM avisa o seu sistema

Você inscreve uma URL https e escolhe os eventos: mensagem recebida, status de entrega, conversa criada, contato criado, atualizado ou mesclado, negócio criado, atualizado, com etapa nova, ganho ou perdido, e solicitação aberta ou com status novo.

Cada aviso vai assinado com HMAC-SHA256 no header X-Wacrm-Signature: o seu sistema confere que veio do Fluxia antes de agir. Responda em até 5 segundos. Se o seu sistema cair, o CRM reenvia sozinho (de 1 minuto até 24 horas), avisa no sino quando começa a falhar e guarda cada entrega por 7 dias, com o botão Reenviar.

• Negócio ganho no CRM vira pedido no ERP.
• Mensagem recebida aciona o seu próprio robô ou alimenta uma planilha.
• Solicitação aberta, com protocolo, cai no sistema do suporte.

MCP: o seu agente de IA opera o CRM

MCP (Model Context Protocol) é o padrão aberto que os agentes de IA usam para chamar ferramentas. Ligado ao Fluxia, o agente que você já usa no dia a dia configura e opera o CRM a partir de um pedido em português: montar um funil com as etapas da sua operação, achar os negócios parados, marcar um compromisso no horário livre, puxar o relatório de vendas do mês.

• Funis e etapas: criar, renomear, reordenar.
• Negócios: criar, mover, atribuir, ganhar, perder, reabrir.
• Contatos e etiquetas: buscar, criar, editar, etiquetar.
• Agenda: ver agendas e horários livres, marcar, remarcar, desmarcar.
• Tarefas, conversas (leitura, nota interna e atribuição) e relatórios de funil, vendas, leads, tarefas e atendimento.
• Automação de comentário do Instagram: listar e salvar as regras.

1. 1

   Crie a chave do agente

   Em Configurações › Chaves de API e MCP, crie uma chave com o modelo «Agente pessoal (MCP)» ou «Só leitura» e dê a ela o nome do agente.

2. 2

   Aponte o agente para o Fluxia

   No Claude Code, no Codex, no Cursor ou no Hermes, adicione o servidor https://crm.salestecnologia.com.br/api/v1/mcp com a chave no header Authorization. A tela mostra o trecho pronto de cada um.

3. 3

   Peça em português

   «Quais negócios estão parados há mais de 7 dias na etapa Proposta?» O agente lê, propõe e, nas ações sem volta, pede a sua confirmação antes de executar.

Segurança e controle

• Escopo por chave: a chave do formulário do site só cria lead; a do agente pode ser só de leitura. Escopo não se edita: precisou de outro, crie uma chave nova e revogue a antiga.
• A chave aparece uma vez só, na criação. Revogada, para de funcionar na hora.
• Limite de 120 chamadas por minuto por chave, somando API e MCP.
• Nenhuma ferramenta do MCP manda mensagem ao cliente. As poucas ações que podem disparar uma automação para ele (mover para uma etapa com gatilho, marcar consulta com aviso) vêm marcadas para o agente confirmar com você antes.
• O agente é avisado de que texto vindo do CRM (mensagem de cliente, nome, nota) é dado, não ordem.
• Conta suspensa ou com o teste vencido: a API e o MCP param, e só a entrada de leads continua, para nenhum lead se perder.

Agente externo chamado por @menção

Para quem já tem um agente próprio (Hermes, OpenClaw, n8n): cadastre-o em Configurações › Integrações › Agentes externos e a equipe chama por @nome numa nota interna, como «@Hermes emite a 2ª via do boleto de outubro». O agente recebe o pedido assinado, faz o trabalho no seu sistema e responde ao cliente ou à equipe. O modo padrão é rascunho, para alguém aprovar antes de sair.

Documentação pública

A documentação completa fica em https://crm.salestecnologia.com.br/api/v1/docs, em Markdown e sem chave: dá para mandar ao desenvolvedor ou colar no agente. A mesma existe em JSON (?format=json) e como prompt pronto para agente de IA (?format=prompt). É gerada da mesma fonte da tela do CRM, então as duas nunca ficam diferentes.

Perguntas frequentes

Em quais planos a API e o MCP estão incluídos?

Nos planos Essencial, Pro e Enterprise, sem custo extra. O consumo de IA do seu agente fica com o provedor que você já usa.

Preciso ser programador para usar o MCP?

Para usar, não: depois de ligado, você pede em português ao seu agente. Para ligar, é colar o endereço e a chave na configuração do agente; a tela traz o trecho pronto para Claude Code, Codex, Cursor e Hermes.

Funciona com o ChatGPT ou o Claude no navegador?

Hoje o MCP funciona com agentes que aceitam servidor MCP remoto com a chave no cabeçalho, como Claude Code, Codex, Cursor e Hermes. Os conectores do ChatGPT e do claude.ai no navegador pedem login por OAuth, que ainda não está disponível.

Dá para integrar com n8n, Zapier ou Make?

Sim, por HTTP: chamadas à API com a chave no header Authorization e webhooks para receber os eventos.

A mensagem enviada pela API respeita o horário e o descadastro?

O envio avulso (POST /messages) sai na hora, sem fila e sem checar o «não perturbe». Para o mesmo texto a muitas pessoas, use o disparo (POST /broadcasts/text), que faz o ritmo e respeita quem pediu para sair.

Consigo testar antes de assinar?

Sim. No teste grátis de 7 dias a API e o MCP funcionam: crie uma chave e chame GET /api/v1/me para ver a sua conta respondendo.