API CRM: seu agente de IA e suas ferramentas fazem follow-up a partir dos mesmos registros de clientes

Uma API CRM é a interface que deixa outro programa, ou um cliente de IA, ler e gravar os registros de um CRM (contatos, empresas, negócios) por requisições HTTP, sem passar pelas telas. Aqui, CRM é o software de gestão de relacionamento com clientes. A API do Customermates é uma API REST aberta em todos os planos, a partir do Starter, a € 12 por usuário ao mês, e na edição gratuita com hospedagem própria. Você se autentica com uma chave de API no cabeçalho x-api-key, o esquema completo é um documento OpenAPI 3.1 em /api/v1/openapi e, nos planos pagos e na hospedagem própria, 16 eventos de webhook avisam os seus sistemas quando algo muda. Não existe um plano separado para desenvolvedores nem um complemento pago de API.

O Customermates é um CRM com API, de código aberto e nativo de IA, feito na Alemanha para pequenas equipes que atendem clientes. A API importa para dois tipos de leitor: o desenvolvedor que quer sincronizar o CRM com outro sistema e a equipe que quer que um cliente de IA, como o Claude ou o ChatGPT, atualize registros. O primeiro usa REST e webhooks. O segundo usa o endpoint MCP, que fica sobre as mesmas permissões.

Por que isso importa para o follow-up. Uma resposta a um cliente escorrega quando os fatos de que ela precisa estão em outro sistema. Por MCP, o seu próprio cliente de IA, como o Claude ou o ChatGPT, lê o registro de um cliente e, no Customermates Cloud a partir do Pro, as conversas com ele, e pode salvar um rascunho de resposta para você revisar e enviar. Por REST e webhooks, as suas outras ferramentas recebem os mesmos registros e são avisadas quando um deles muda.

Para que serve uma API de CRM

Uma API de CRM tira o trabalho de copiar dados de um sistema para outro. Alguns usos comuns:

• Sincronizar clientes com o ERP ou com o sistema de faturamento e de emissão de notas fiscais, para que o cadastro não exista em dois lugares.
• Criar o contato sozinho quando alguém preenche um formulário do seu site, que você mesmo conecta, em vez de digitar o lead à mão.
• Levar os negócios ganhos para uma planilha, um painel de BI ou o sistema de projetos.
• Deixar um agente de IA ler o registro do cliente e atualizar o próximo passo, com as mesmas permissões de uma pessoa.

O que a API REST cobre

A API REST funciona em todas as listas do CRM. Um novo espaço de trabalho começa sem listas: você cria as listas de que precisa (contatos, organizações, negócios ou as suas) em Modelo de dados, pela API ou por MCP, ou deixa a configuração com IA montá-las na nuvem. Toda rota de registros é um POST para uma ação nomeada com um corpo JSON, então o mesmo código funciona para negócios, contatos ou uma lista que você adicionou semana passada.

Um registro é endereçado por uma referência, { "typeId": "...", "recordId": "..." }, e não pela URL. A URL base é o endereço em que você abre o Customermates, na nuvem e no seu próprio servidor. Outras rotas cobrem usuários (/api/v1/users/me, /api/v1/users/search), webhooks e a caixa de entrada: conversas, rascunhos, envio de e-mails e mensagens de chat, atividades e calendários somente leitura.

Alguns detalhes poupam tempo no primeiro dia:

• Os campos têm IDs estáveis. /model/read devolve o fieldId de cada campo, os IDs das opções de um campo de escolha única como a Etapa do negócio e a revision do esquema. Os IDs continuam os mesmos quando alguém renomeia uma lista ou um campo. Os valores são tipados, por exemplo { "kind": "text", "value": "Acme" }.
• As consultas usam um corpo JSON. /records/query aceita typeId, filters, sort, page e pageSize (até 500). Os filtros usam a sintaxe de filtros compartilhada com o aplicativo e o MCP.
• As gravações são protegidas. Uma mutação leva expectedRevision (a revisão do esquema), uma idempotencyKey e a própria mutation; atualizações e exclusões também levam a expectedVersion do registro. Enviar a mesma requisição de novo com a mesma chave não a aplica duas vezes.
• Os vínculos são uma ação própria. link e unlink aceitam um relationId, um source e uma referência de registro target. Uma atualização nunca remove vínculos que você não mencionou.
• Gravações em massa aceitam até 100 registros. updateMany aplica uma alteração a até 100 registros de forma atômica e deleteMany move até 100 para a Lixeira, então você divide uma limpeza de 2.000 contatos em 20 requisições.

Webhooks: deixe o CRM chamar você

Um webhook envia um POST JSON para a sua URL quando um evento assinado acontece. Administradores, e membros cuja função tem Acesso de leitura Todos e Criar em API e webhooks, adicionam um em Configurações → Webhooks: URL, eventos, a lista em Registros de com filtros opcionais, um segredo opcional, cabeçalhos personalizados opcionais e um modelo de corpo opcional. A referência de webhooks lista todos os eventos e payloads.

• Eventos: 5 eventos de registro (record.created, record.updated, record.deleted quando um registro vai para a Lixeira, record.restored e record.deletedPermanently) para qualquer lista que você escolher, inclusive as suas, mais 11 eventos de caixa de entrada e calendário.
• Alterações incluídas: um payload record.updated traz a referência do registro e lista cada campo que mudou com o valor before e o valor after. Uma gravação que não altera nada não envia evento.
• Assinaturas: com um segredo definido, cada entrega é assinada com HMAC-SHA256 sobre o corpo bruto.
• Novas tentativas: um timeout, erro de rede, 5xx, 408, 425 ou 429 é repetido automaticamente, até 10 tentativas no total. Outras respostas 4xx não são repetidas, porque uma repetição falharia do mesmo jeito. Cada entrega tem um timeout de 5 segundos.
• Registro de entregas: Configurações → Registro de webhooks mostra o código de status e a mensagem de resposta de cada entrega, com um botão de reenvio.
• Modelos de corpo: um modelo substitui o envelope padrão, então uma ferramenta de chat ou um endpoint de automação que espera o próprio formato JSON pode receber as entregas sem middleware.

As entregas não têm ordem estrita. Duas atualizações no mesmo contato com poucos milissegundos de diferença podem chegar invertidas, então desduplique pelo id do evento, indexe o seu handler por typeId e recordId e use o timestamp do payload e a versão do registro.

Como fazer a sua primeira chamada de API

1. Crie uma chave

   Abra Configurações → Chaves de API e conectores, clique em Adicionar, escolha Chave de API padrão, dê um nome como ERP sync, produção e copie a chave. Ela é exibida uma única vez. O guia de chaves de API cobre expiração e rotação.

2. Leia o esquema

   Busque /api/v1/openapi no endereço do seu espaço de trabalho e importe no Postman, no Insomnia ou em um gerador de clientes. Depois envie POST /api/v1/model/discover com {"search":"deal"} para obter o typeId dos seus negócios, e POST /api/v1/model/read com {"typeIds":["<deal-type-id>"]} para ver os campos, as opções de etapa e a revision do esquema.

3. Consulte

   Envie POST /api/v1/records/query com o cabeçalho x-api-key e um corpo como {"typeId":"<deal-type-id>","filters":[{"fieldId":"system:updatedAt","operator":"inLastDays","value":{"kind":"decimal","value":"7","currency":null}}],"page":1,"pageSize":25} para listar os negócios alterados na última semana.

4. Escreva

   Mova um negócio para outra etapa com POST /api/v1/records/mutate e {"expectedRevision":<revision>,"idempotencyKey":"move-acme-to-demo","mutation":{"action":"update","ref":{"typeId":"<deal-type-id>","recordId":"<deal-id>"},"expectedVersion":<version>,"fields":[{"fieldId":"<stage-field-id>","value":{"kind":"select","value":"<option-id>"}}]}}. Se o seu usuário consegue fazer isso no aplicativo, a chave consegue pela API.

5. Assine

   Adicione um webhook para Registro atualizado na lista Negócios com um segredo, aponte para o seu endpoint e confira a primeira entrega em Registro de webhooks.

Uma chave errada, expirada ou excluída recebe HTTP 401. Uma chave cujo proprietário foi definido como Inativo recebe 403.

Erros e códigos de status

Toda rota REST responde a uma chamada recusada com o mesmo corpo JSON: um objeto error com o kind e a lista issues. O status HTTP segue o kind:

Um erro inesperado do servidor responde 500 sem esse corpo. Decida pelo kind e pelo customCode, que é estável, e não pela message, que é texto para pessoas. Em um 429, respeite o cabeçalho Retry-After; sem ele, espere um intervalo crescente (1, 2, 4 e 8 segundos, mais um pouco de aleatoriedade) e desista depois de algumas tentativas. Reenvie uma gravação com a mesma idempotencyKey, para que uma alteração que já passou não seja aplicada duas vezes. O guia de chaves de API detalha cada caso.

Chaves de API e permissões

As chaves pertencem ao usuário que as criou e agem com a função atual desse usuário. Não há usuários de API separados nem escopos por chave, então uma chave não pode ser limitada a somente leitura. Se uma integração deve apenas ler negócios, crie a chave dela sob um membro cuja função permita só isso. No Customermates Cloud, esse membro é um assento pago como qualquer outro.

Criar chaves exige Acesso de leitura Todos e Criar na linha API e webhooks de uma função. Uma nova função personalizada começa sem isso, então, de fábrica, só administradores criam chaves. A mesma permissão também abre todos os webhooks do espaço de trabalho, o que vale saber antes de concedê-la. Para parar todas as chaves de alguém que sai, defina o membro como Inativo. Remover Acesso de leitura Todos em API e webhooks da função dele também faz as chaves pararem.

MCP: a API para clientes de IA

O endpoint MCP em /api/v1/mcp dá a um cliente de IA externo 59 ferramentas sobre os mesmos registros, a caixa de entrada e os webhooks. O Claude e o ChatGPT se conectam por OAuth como um conector personalizado; o Claude Code, o Codex, o Cursor e o Gemini usam uma chave de API. O cliente, o modelo e a assinatura dele continuam sendo seus. A busca semântica ainda pode contar para o uso do Mate no Customermates Cloud. O guia de MCP lista todas as ferramentas.

O Mate, o assistente dentro do Customermates Cloud, é um recurso separado. Ele roda com créditos de IA hospedados e não precisa de chave de API. Instalações com hospedagem própria têm MCP, mas não têm o Mate.

O que a API não faz

• Sem PUT nem PATCH em registros. Toda alteração de registro é um POST para /api/v1/records/mutate.
• Sem OR entre regras de filtro. As regras de filtro se combinam com AND. Para OR, faça duas consultas ou use o operador in em um campo.
• Sem cota de requisições publicada. Um espaço de trabalho muito movimentado responde 429 com um cabeçalho Retry-After. Divida os trabalhos em massa em lotes de 100.
• Sem endpoint de exportação CSV e sem exportação da conta inteira. O aplicativo importa arquivos Excel, CSV e JSON e exporta XLSX e JSON, uma lista por vez. Qualquer coisa maior passa pelo seu próprio script de API.
• Sem caixa de entrada e sem Mate na hospedagem própria. As rotas de registros REST, os webhooks e o MCP funcionam lá; as rotas de mensagens exigem o Customermates Cloud no Pro ou superior.

Nenhum período de compatibilidade retroativa é prometido além do caminho /api/v1, então trate o documento OpenAPI atual como o contrato e teste com base nele.

Como outros CRMs medem o acesso à API

O Customermates publica esta página. Os números abaixo vêm da documentação de cada fornecedor, verificada em 8 de outubro de 2026; eles mudam, então siga os links antes de planejar em cima deles.

Escolha o HubSpot ou o Zoho CRM se você quer um plano gratuito hospedado com acesso à API e a sua integração cabe nos limites de chamadas que eles publicam. Escolha o Pipedrive se um orçamento diário que cresce com o plano e os assentos combina com o seu volume. Escolha o EspoCRM se você quer um CRM de código aberto com hospedagem própria, com usuários de API separados e funções próprias. O Customermates serve a uma equipe pequena que quer a API de registros, os webhooks e um endpoint MCP para clientes de IA pelo preço do próprio CRM, com um núcleo AGPL que ela pode hospedar por conta própria. Não serve se você precisa de escopos por chave ou, no Customermates Cloud, de um usuário de API que não ocupe um assento pago.

Quanto custa

O acesso à API não tem sobretaxa. Uma equipe de três pessoas no Starter paga € 36 por mês e recebe REST, webhooks e MCP. A mesma equipe no Pro paga € 87 e adiciona a caixa de entrada unificada e as rotas de mensagens dela. Hospedar a edição de código aberto por conta própria não custa nada em taxas de licença; você roda o servidor. A cobrança é mensal, veja os preços. Se você monta fluxos no n8n, o n8n é um produto separado com planos próprios; o guia do n8n mostra a configuração do HTTP Request.