API e MCP da Certu

A API da Certu deixa um programa ou um agente de IA operar uma conta da Certu: a IA que atende o WhatsApp do negócio, as conversas, o Cérebro, o CRM, a agenda, o controle do negócio, os anúncios e o perfil do Google. As mesmas ferramentas respondem pelo REST e pelo MCP.

Base do REST

https://certu.com.br/api/v1

MCP

POST https://certu.com.br/api/v1/mcp

OpenAPI 3.1

https://certu.com.br/openapi.json

Autenticação

Authorization: Bearer certu_sk_...

Teste (sandbox)

Chave de teste (certu_sk_test_...) lê os dados reais e simula toda escrita

Limites

60/min por chave · 5 chaves ativas · 2.000 chamadas/dia por conta

Começar

7 dias grátis, sem cartão. Criar conta · Planos

Quando usar a API da Certu

Use quando uma pessoa ou um agente precisa tocar uma pequena ou média empresa que atende clientes pelo WhatsApp:

• Montar a IA que atende o WhatsApp do negócio a partir de uma entrevista com o dono, e testar as respostas dela (agente_criar, agente_testar).
• Ler as conversas recentes do WhatsApp e o histórico inteiro de uma conversa (conversas_listar, conversa_ler).
• Ensinar ou corrigir o que a IA sabe: fichas do Cérebro e produtos (cerebro_*, produto_salvar).
• Cuidar da agenda: listar, marcar, remarcar, confirmar, cancelar e bloquear horário (agenda_*). A API não avisa o cliente.
• Trabalhar o funil, os contatos e as tarefas do CRM (crm_*), e ler as ligações com transcrição (ligacoes_listar, ligacao_ler).
• Controle do negócio: estoque, caixa, resultado do mês, pedidos e cobranças (erp_*, pedido*, cobranca*).
• Preparar anúncios: gerar o kit, publicar pausado, ler o resultado, pausar ou mudar o orçamento (anuncio*).
• Rascunhar e publicar resposta às avaliações do Google (google_*). Parceiro cuida das contas dos clientes dele com conta.

Quando não usar

• Mandar mensagem pra cliente: nenhuma ferramenta manda WhatsApp, e-mail ou SMS pra cliente.
• Ligar gasto de anúncio: campanha nasce sempre pausada e não existe ferramenta que ative.
• Conectar o número do WhatsApp ou pagar: isso é com o dono, no app.
• Disparo em massa ou mensagem fria de qualquer tipo.

Começar em três passos

1. Crie a conta. Começa com 7 dias grátis, sem cartão: https://certu.com.br/criar-meu-agente.
2. Crie a chave no app, em Ajustes, na seção Conectar ao Claude. Ela começa com certu_sk_ e aparece uma vez só. Passo a passo: https://certu.com.br/claude.
3. Chame a API com Authorization: Bearer <chave>. Comece por GET /conta, que diz o que o plano inclui.

Autenticação

Todo pedido leva a chave no cabeçalho Authorization: Bearer. Chave na URL é recusada (chave_na_url).

A chave opera a conta de quem a criou. É autoatendimento: o dono cria e revoga a chave no app, sem pedir aprovação a ninguém.

O conector do claude.ai entra com login OAuth em vez de chave. Descoberta: /.well-known/oauth-protected-resource.

Chave de teste (sandbox) e escopos

A chave de teste (certu_sk_test_...) lê a conta de verdade e simula toda escrita: os parâmetros são validados igual à produção e a resposta é {"sandbox": true, "simulado": true, ...}, sem gravar, sem gastar crédito e sem mandar nada. As respostas levam o cabeçalho Certu-Modo: teste.

Chave de teste e chave com escopo são criadas no POST /api/v1/keys, autenticado pelo login do app (não por outra chave). Escopos: area:ler (leitura) ou area:escrever (escrita, que inclui leitura), além de area:*, *:ler e *. Áreas: conta, conversas, cerebro, agente, anuncios, site, agenda, erp, ligacoes, crm, google, parceiro, webhooks, cobrancas, pets, imoveis, fiscal, clinica.

POST https://certu.com.br/api/v1/keys
{"nome": "Integração de teste", "teste": true, "escopos": ["crm:ler", "agenda:escrever"]}

Limites e erros

• 60 pedidos por minuto por chave. Toda resposta do /api/v1, inclusive 401, 404, 405 e OPTIONS, leva o cabeçalho IETF RateLimit-Policy: "minuto";q=60;w=60 (com o limite da própria chave quando ela é conhecida). A chamada feita com chave leva também RateLimit: "minuto";r=<restante>;t=<segundos>, além de X-RateLimit-Limit e X-RateLimit-Remaining; o 429 traz Retry-After.
• 5 chaves ativas e 2.000 chamadas de ferramenta por dia por conta, somando todas as chaves. Corpo até 1 MB.
• Cada ação continua seguindo o plano e os créditos da conta. Leia GET /conta antes, pra não prometer o que o plano não inclui.
• Erro vem em JSON com o status HTTP. Use o código em error; o message explica.

Versionamento e descontinuação

• A v1 só ganha acréscimos: endereços novos, parâmetros opcionais novos e campos novos na resposta. O que quebrar sai em /api/v2.
• Antes de remover ou mudar qualquer coisa na v1, a Certu avisa por e-mail quem tem chave afetada e manda os cabeçalhos Deprecation (RFC 9745) e Sunset (RFC 8594), com a data, nos endereços afetados.
• Operação descontinuada aparece com deprecated: true no /openapi.json.

Servidor MCP

Endereço: POST https://certu.com.br/api/v1/mcp. Streamable HTTP, sem estado, só respostas JSON (sem SSE); GET responde 405. Versões do protocolo: 2025-11-25, 2025-06-18, 2025-03-26.

Métodos: initialize, ping, tools/list, tools/call. As 65 ferramentas são as mesmas operações do REST.

No claude.ai ou no app do Claude, adicione um conector personalizado com o endereço https://certu.com.br/api/v1/mcp e entre na conta; não precisa de chave. Guia completo: https://certu.com.br/claude.

Descoberta sem chave: manifesto em https://certu.com.br/.well-known/mcp.json e cartão do servidor em https://certu.com.br/.well-known/mcp/server-card.json.

Claude Code

claude mcp add --transport http certu https://certu.com.br/api/v1/mcp --header "Authorization: Bearer SUA_CHAVE"

Cursor e outros clientes MCP

{
  "mcpServers": {
    "certu": {
      "url": "https://certu.com.br/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer SUA_CHAVE"
      }
    }
  }
}

Exemplos

Resumo da conta: plano, créditos e o que o plano inclui

curl https://certu.com.br/api/v1/conta \
  -H "Authorization: Bearer $CERTU_KEY"

Agendamentos confirmados de uma semana

curl "https://certu.com.br/api/v1/agenda?de=2026-10-12&ate=2026-10-18&status=confirmado" \
  -H "Authorization: Bearer $CERTU_KEY"

Ensinar um fato à IA (com chave de teste, é simulado e nada é gravado)

curl -X POST https://certu.com.br/api/v1/cerebro \
  -H "Authorization: Bearer $CERTU_KEY" \
  -H "Content-Type: application/json" \
  -d '{"titulo": "Horário de atendimento", "conteudo": "Segunda a sexta, das 9h às 18h."}'

Listar as ferramentas do MCP

curl -X POST https://certu.com.br/api/v1/mcp \
  -H "Authorization: Bearer $CERTU_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Agir em outra conta

Parceiro, dono de mais de um negócio ou admin de outra conta passa conta (na query, ou no corpo de um POST) pra agir naquela conta. GET /parceiro/clientes lista as contas que a chave alcança. Sem conta, a chamada age na conta de quem criou a chave.

Webhooks

Os webhooks de saída ficam em /api/v1/webhooks (escopo webhooks:ler / webhooks:escrever) e fazem parte da API empresarial, ligada por conta. Eventos: mensagem.recebida, conversa.transferida_humano, contato.criado, negocio.criado, ligacao.concluida.

Endereços do REST

Todo caminho é relativo a https://certu.com.br/api/v1. Parâmetros, corpos e esquemas estão na especificação OpenAPI.

Mais para agentes e desenvolvedores

• Especificação OpenAPI 3.1
• Manifesto do servidor MCP
• Cartão do servidor MCP
• llms.txt
• AGENTS.md
• Conectar o Claude à Certu
• Planos e preços