Documentação para desenvolvedores do Mentrun

Visão geral

Cada empresa tem os próprios dados, chaves e endereços: uma chave de uma empresa nunca enxerga outra. O MCP respeita o cargo de quem criou a chave: se a pessoa não vê um registro no Mentrun, a integração também não vê. O webhook do CRM age em nome da pessoa que conectou o CRM, e as automações em nome do responsável da automação.

• Não há API REST de leitura e escrita geral: ler e alterar dados da empresa é pelo MCP. Os outros endereços desta página são só de entrada (automações e CRM) e de saída (webhooks).
• Fora do MCP, por segurança: membros, convites, cargos e permissões, assinatura e cobrança, chaves de acesso, chave da IA, configurações de integração e SQL.
• Lançamentos do Financeiro e Comissões não se alteram pelo MCP (as categorias do Financeiro, sim, pelo acesso Configurar a empresa). Funil, etapas e modelos de projeto só pelo acesso Configurar a empresa, sempre com prévia; o Processo comercial só pelo acesso Configurar o comercial (as colunas do quadro de tarefas dá para criar, renomear e ordenar com Tarefas).

Credenciais

• Toda chave e todo segredo aparecem uma vez só, na hora em que são criados. Guarde num cofre de senhas. As chaves do MCP e da automação ficam guardadas só como impressão (hash); os segredos do CRM e as credenciais do passo Chamar outro app ficam cifrados, porque o sistema precisa deles para assinar e conferir.
• Quem pode criar: quem tem a permissão Conectar ferramentas no cargo (por padrão, Dono e Gestor; o Dono libera para outros cargos). Cargo só de leitura cria só chave de leitura.
• Validade padrão de 30 dias. Máximo: 365 dias só para chave de leitura no cabeçalho (cxm_); 180 dias para endereço único (cxu_) ou chave que altera ou exclui; 90 dias para a chave administrativa. Girar a chave cria outra igual e a antiga para na hora, em 1 hora ou em 24 horas, à sua escolha.
• A chave para de funcionar sozinha se expirar, for revogada, ou se a pessoa dona dela sair da empresa, mudar de cargo ou perder a permissão.
• Não achou Conectar outros apps no menu Empresa? Procure na busca do sistema ou abra direto /app/configuracoes/api.

Onde achar cada id

• ID_DA_AUTOMACAO: no editor da automação, clique no gatilho Ao receber de outro app; o campo Endereço para o outro app já traz o endereço completo (o id também aparece no endereço do navegador, /app/automacoes/<id>).
• ID_DA_CONEXAO: em Empresa › Conectar outros apps › CRM, o campo do endereço de entrada já traz o endereço completo.
• Ids de pessoa, projeto, funil e etapa para as ferramentas do MCP: listar_pessoas, listar_projetos e listar_funis devolvem o id de cada um.

Girar, revogar e trocar

MCP do Mentrun

O MCP (Model Context Protocol) é o jeito de ler e alterar os dados da empresa por programa. Funciona com Claude, ChatGPT, Claude Code, n8n, Make ou qualquer script que fale HTTP.

• Protocolo MCP sobre HTTP (streamable HTTP), sem estado, JSON-RPC 2.0. Resposta em application/json (notificações, como notifications/initialized, voltam 202 sem corpo); não há fluxo SSE nem sessão (Mcp-Session-Id não é usado). GET devolve 405.
• Versões do protocolo aceitas: 2025-06-18 (padrão), 2025-03-26 e 2024-11-05.
• Métodos: initialize, ping, tools/list e tools/call. Não há resources nem prompts. Lote (array JSON-RPC) não é aceito.
• Chamar initialize antes é opcional: dá para chamar tools/call direto.
• tools/list já vem filtrado para a sua chave: aparece só o que o escopo da chave, o cargo da pessoa e a assinatura permitem.
• Cada ferramenta tem esquema estrito: argumento desconhecido é recusado com a lista do que está errado.
• Resposta grande é cortada em 60 mil caracteres e volta com aviso de parcial. Textos longos (transcrição, documento) têm paginação por inicio e max_caracteres.
• Toda alteração fica no histórico da empresa, no nome da pessoa dona da chave. A aba Uso e auditoria mostra as chamadas de cada chave.

Conectar no Claude

Configurações › Conectores › Adicionar conector personalizado
URL: https://mentrun.com.br/api/mcp
Clique em Conectar, entre no Mentrun, escolha a empresa e o nível (Só consultar ou Consultar e alterar).

claude mcp add --transport http mentrun https://mentrun.com.br/api/mcp \
  --header "Authorization: Bearer $MENTRUN_MCP_TOKEN"

claude mcp add --transport http mentrun "https://mentrun.com.br/api/mcp/k/cxu_SUA_CHAVE"

Conectar no ChatGPT e outros

• ChatGPT (com conectores personalizados liberados no plano ou no modo desenvolvedor): nas configurações de conectores do ChatGPT, crie um conector personalizado com a URL https://mentrun.com.br/api/mcp e autenticação OAuth. Clique em Conectar, entre na sua conta, escolha a empresa e o nível.
• Sem OAuth: use o endereço único https://mentrun.com.br/api/mcp/k/cxu_… sem autenticação.
• Claude Code com OAuth: claude mcp add --transport http mentrun https://mentrun.com.br/api/mcp e depois autentique pelo comando /mcp.
• Os menus do Claude e do ChatGPT mudam com frequência; o que vale é o endereço e o tipo de autenticação.

Chamar com curl

Guarde a chave numa variável de ambiente (export MENTRUN_MCP_TOKEN=cxm_…) e rode na ordem:

curl -sS -X POST "https://mentrun.com.br/api/mcp" \
  -H "Authorization: Bearer $MENTRUN_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"meu-script","version":"1.0"}}}'

curl -sS -X POST "https://mentrun.com.br/api/mcp" \
  -H "Authorization: Bearer $MENTRUN_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

curl -sS -X POST "https://mentrun.com.br/api/mcp" \
  -H "Authorization: Bearer $MENTRUN_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"listar_negocios","arguments":{"status":"open","limite":5}}}'

curl -sS -X POST "https://mentrun.com.br/api/mcp/k/cxu_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"quem_sou_eu","arguments":{}}}'

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{\"negocios\": [ ... ]}" }],
    "isError": false
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{\n  \"erro\": \"Este token não tem permissão de escrita ou a assinatura está só leitura.\"\n}" }],
    "isError": true
  }
}

Outros motivos comuns no campo erro: falta de acesso ao módulo (Esta chave não permite "criar_tarefa": falta o acesso "tarefas:write".), argumento inválido (Argumentos inválidos — prazo: use AAAA-MM-DD), registro que o cargo não vê (… não encontrado) e muitas alterações seguidas (Muitas alterações seguidas. Espere um minuto e continue.).

Esquema das ferramentas e uma escrita

{"jsonrpc":"2.0","id":2,"result":{"tools":[{
  "name": "criar_tarefa",
  "description": "Cria uma tarefa, opcionalmente ligada a projeto (e etapa), negócio ou reunião, com responsável, prazo, prioridade, estimativa e etiquetas.",
  "inputSchema": {"type":"object","additionalProperties":false,"required":["titulo"],"properties":{
    "titulo": {"type":"string","minLength":1,"maxLength":200},
    "descricao": {"type":"string","maxLength":8000},
    "prazo": {"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},
    "prioridade": {"type":"string","enum":["low","normal","high","urgent"]},
    "responsavel_id": {"type":"string","format":"uuid"},
    "projeto_id": {"type":"string","format":"uuid"},
    "etapa_id": {"type":"string","format":"uuid"},
    "negocio_id": {"type":"string","format":"uuid"},
    "reuniao_id": {"type":"string","format":"uuid"},
    "estimativa_min": {"type":"integer","minimum":0,"maximum":100000},
    "etiquetas": {"type":"array","maxItems":5,"items":{"type":"string","minLength":1,"maxLength":30}}}},
  "annotations": {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}
}]}}

curl -sS -X POST "https://mentrun.com.br/api/mcp" \
  -H "Authorization: Bearer $MENTRUN_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"criar_tarefa","arguments":{"titulo":"Enviar proposta para a Loja Aurora","prazo":"2026-10-30","prioridade":"high","responsavel_id":"UUID_DA_PESSOA","etiquetas":["proposta"]}}}'
# result.content[0].text: {"ok": true, "id": "<uuid>", "alvo": {"tipo": "task", "id": "<uuid>"}}

• annotations diz se a ferramenta só lê (readOnlyHint) ou exclui (destructiveHint): o Claude e o ChatGPT usam isso para pedir confirmação.
• Transcrição em partes: ler_transcricao com {"id":"UUID","inicio":0,"max_caracteres":12000} (500 a 20.000) devolve total_caracteres, inicio, fim, continua e texto. Chame de novo com inicio = fim enquanto continua for true.
• Documento em partes: ler_documento aceita os mesmos inicio e max_caracteres (padrão 20.000) e devolve total_caracteres, inicio, continua e conteudo; o próximo inicio é inicio + max_caracteres.
• Campos personalizados: listar_campos_personalizados devolve o código, o tipo, as opções e o formato de cada campo de cliente, de projeto e de tarefa. Mande os valores em campos ({"codigo": valor}, até 40 por vez; várias opções como lista; sim ou não como true/false; null apaga) em criar_cliente, atualizar_cliente, atualizar_projeto, criar_tarefa e atualizar_tarefa.
• Tarefas (0.84): criar_tarefa e atualizar_tarefa aceitam inicio (AAAA-MM-DD) e tarefa_mae_id (vira subtarefa; um nível só, herda projeto e etapa da mãe; null em atualizar_tarefa volta a ser tarefa normal). ler_tarefa traz inicio, campos, tarefa_mae e subtarefas.
• Cronograma (0.91): ler_cronograma com {"projeto_id":"UUID"} devolve as tarefas com início, prazo, atraso, tarefa-mãe e depende_de, o período, quantas estão sem datas e fora_de_ordem (começa antes do prazo da anterior). reagendar_tarefas muda datas como arrastar na tela: {"tarefas":[{"id":"UUID","inicio":"2026-11-03","prazo":"2026-11-07"}]} (até 50; null tira a data) ou {"projeto_id":"UUID","deslocar_dias":7} (todas as abertas com data). Tudo ou nada: início depois do prazo recusa a chamada inteira.
• Formulários de entrada: criar_formulario com {"nome":"Briefing de campanha","campos":[{"tipo":"short_text","titulo":"Nome da empresa","obrigatorio":true},{"tipo":"select","titulo":"Objetivo","opcoes":["Vendas","Marca"]}]} cria o formulário PAUSADO (destino e publicação ficam na tela). listar_respostas_formulario devolve pergunta e resposta de cada campo e o link; marcar_resposta_formulario muda a situação (nova, em_andamento, concluida, arquivada).
• Projeto a partir de modelo: listar_modelos_projeto devolve o id e as etapas de cada modelo; passe o id em criar_projeto (modelo_id).
• Relatórios agendados: criar_relatorio_agendado com {"nome":"Reuniões da semana","tipo":"reunioes","periodo":"semana_passada","frequencia":"semanal","dias_semana":["seg"],"horario":"08:00","aviso_no_mentrun":true}. Tipos: reunioes, comercial, projetos, tarefas, horas, metas e pergunta_ia (com pergunta). Frequência: diaria, dias_semana, semanal ou mensal (dia_mes 1 a 31; 31 = último dia). Horário de Brasília, de 15 em 15 minutos. E-mail de fora, WhatsApp e relatório em nome de outra pessoa (dona_id) só Dono ou Gestor. pausar_relatorio_agendado com retomar: true retoma. Excluir e "Enviar agora" ficam na tela.
• Exportar (Excel, PDF com a marca do Mentrun ou CSV): exportar_relatorio com {"modulo":"financeiro","formato":"pdf","periodo":"last_month"} ou com datas {"modulo":"projetos","formato":"xlsx","de":"2026-10-01","ate":"2026-10-06"}. Módulos: projetos, tarefas, reunioes, financeiro, trafego, clientes, chamados e horas. Período: 7d, 30d, this_month, last_month, 90d, this_year, all ou de/ate (dias no fuso da empresa, fim incluído). Filtros simples do módulo (ex.: status, texto, tipo e situacao no financeiro, visao nos chamados, quebra no tráfego). Devolve url (GET, vale 1 hora), arquivo, periodo, linhas e resumo; o arquivo é apagado em até 2 dias. Os dados vêm das mesmas leituras que a chave já pode fazer: sem financeiro:read, exportar o financeiro é recusado. Até 10 exportações por minuto por chave.
• Exportar (Excel, PDF com a marca do Mentrun ou CSV): exportar_relatorio com {"modulo":"financeiro","formato":"pdf","periodo":"last_month"} ou com datas {"modulo":"projetos","formato":"xlsx","de":"2026-10-01","ate":"2026-10-06"}. Módulos: projetos, tarefas, reunioes, financeiro, trafego, clientes, chamados, horas e recrutamento (vagas e candidaturas, sem contato; pede recrutamento:read). Período: 7d, 30d, this_month, last_month, 90d, this_year, all ou de/ate (dias no fuso da empresa, fim incluído). Filtros simples do módulo (ex.: status, texto, tipo e situacao no financeiro, visao nos chamados, quebra no tráfego). Devolve url (GET, vale 1 hora), arquivo, periodo, linhas e resumo; o arquivo é apagado em até 2 dias. Os dados vêm das mesmas leituras que a chave já pode fazer: sem financeiro:read, exportar o financeiro é recusado. Até 10 exportações por minuto por chave.
• Armazenamento: armazenamento (sem argumentos, chave de Dono ou Gestor) devolve usedBytes, quotaBytes, pct, status (ok, warn = quase cheio, full = cheio), pacotes de +50 GB, uso por categoria, lixeira e o prazo da mídia do WhatsApp. Só lê: limpar arquivos antigos e contratar mais espaço são na tela Empresa › Armazenamento, com prévia e confirmação.

OAuth 2.1 (Claude e ChatGPT sem copiar chave)

• Fluxo authorization_code com PKCE S256 obrigatório; cliente público (sem client_secret).
• Escopos: read (só consultar) e write (consultar e alterar). OAuth nunca dá permissão de excluir.
• Endereços de retorno aceitos: https://claude.ai/api/mcp/auth_callback, https://claude.com/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect, https://chatgpt.com/connector/oauth/<id> e http://localhost ou http://127.0.0.1 (com porta) para desenvolvimento.
• O parâmetro resource é opcional; se vier, tem de ser o endereço do MCP (senão volta 400 invalid_target). Cliente registrado e nunca usado é apagado em 30 dias.
• Acesso (cxa_) vale 1 hora; renovação (cxr_) vale 90 dias e muda a cada uso. Reusar um código ou uma renovação já usada derruba a conexão.

# 1. Registrar o cliente (público, sem segredo)
curl -sS -X POST "https://mentrun.com.br/oauth/register" -H "Content-Type: application/json" \
  -d '{"client_name":"Integração Loja Aurora","redirect_uris":["http://localhost:8765/callback"]}'
# 201 {"client_id":"<uuid>", "grant_types":["authorization_code","refresh_token"], "token_endpoint_auth_method":"none", ...}

# 2. PKCE
VERIFIER=$(openssl rand -base64 48 | tr -d '=+/\n' | cut -c1-64)
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')

# 3. Abrir no navegador (a pessoa entra, escolhe a empresa e o nível)
# https://mentrun.com.br/oauth/authorize?response_type=code&client_id=<uuid>&redirect_uri=http%3A%2F%2Flocalhost%3A8765%2Fcallback&code_challenge=$CHALLENGE&code_challenge_method=S256&scope=read%20write&state=abc123
# Volta para http://localhost:8765/callback?code=cxc_…&state=abc123 (código vale 10 minutos, uso único)

# 4. Trocar o código
curl -sS -X POST "https://mentrun.com.br/oauth/token" -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode grant_type=authorization_code --data-urlencode code=cxc_SEU_CODIGO \
  --data-urlencode client_id=<uuid> --data-urlencode redirect_uri=http://localhost:8765/callback \
  --data-urlencode code_verifier="$VERIFIER"
# 200 {"access_token":"cxa_…","token_type":"Bearer","expires_in":3600,"refresh_token":"cxr_…","scope":"read write"}

# 5. Renovar (a renovação muda a cada uso: guarde a nova)
curl -sS -X POST "https://mentrun.com.br/oauth/token" -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode grant_type=refresh_token --data-urlencode refresh_token=cxr_SUA_RENOVACAO \
  --data-urlencode client_id=<uuid>
# Erro: 400 {"error":"invalid_grant","error_description":"Código ou renovação inválido, vencido ou já usado."}

Escopos e modelos de chave

• O que a chave pode fazer = escopo da chave × permissões do cargo da pessoa dona × assinatura ativa. Um registro que a pessoa não vê volta como não encontrado.
• Escopo é módulo:nível (por exemplo pipeline:write). Alterar inclui ler; excluir nunca vem junto, precisa ser marcado.
• Acessos sensíveis só valem com o escopo próprio ou a chave de administrador (o curinga *, a chave antiga write e o OAuth não chegam): Financeiro e Comissões (só leitura), Publicar automações, Configurar o comercial, Configurar a empresa e Contratação.
• Gestão de campanhas (Meta Ads), módulo trafego_gestao, também é acesso sensível: curinga (*:write), a chave antiga "write" e o OAuth padrão não chegam, e criar a chave com alterar pede a verificação em duas etapas. A empresa precisa da Gestão de campanhas liberada; mudar pede Dono, Gestor ou o cargo com Criar e editar campanhas. trafego_preparar_mudanca confere no Meta sem mudar nada e devolve lote_id; trafego_aplicar_mudanca com dinheiro ou exclusão exige confirmar: true; com o modo ensaio ligado, o Meta só confere.
• Excluir negócio, projeto, tarefa, documento ou pasta manda para a lixeira por 30 dias (restaurar_item traz de volta). Apontamento de horas excluído não volta pelo MCP. A única exclusão definitiva é excluir_reuniao, só com chave administrativa e informando o título exato em confirmar_titulo. Chave que exclui ou administra exige a verificação em duas etapas para criar e para girar.
• Notificações e lembretes são sempre da pessoa dona da chave: a chave lê e marca só os avisos dela e edita só os lembretes dela.

Módulos e níveis (chave Personalizada)

Ferramentas do MCP

Lista completa por área: 220 ferramentas. O tools/list devolve o esquema de argumentos de cada uma, já filtrado para a sua chave. Legenda: ler, alterar e excluir.

Configurar o comercial pelo Claude

• Chave: em Configurações › Conectar outros apps, o Dono ou o Gestor cria uma chave Personalizada com "Configurar o comercial" (alterar). Para materiais, marque também Documentos e pastas e Arquivos; para testar numa reunião real, Reuniões e análise (alterar).
• Leia antes: ler_processo e ler_configuracao_analise mostram oferta, cliente ideal, caminho da call, critérios, objeções, glossário, perfil da análise e o que ainda falta preencher.
• Mande o material (playbook, apresentação, script) no chat ou guarde no Mentrun (criar_documento ou preparar_upload_arquivo). Documento não entra direto na análise de reunião: o essencial vai para o Processo com atualizar_processo (oferta, cliente ideal, diferenciais, contexto_extra até 4.000 caracteres, nunca prometer, etapas da call, próximo passo, regras e glossário).
• Critérios com peso (0,5 a 3, até 20) com salvar_criterio; objeções com a resposta combinada e as frases do cliente (até 40) com salvar_objecao. Sem id cria; com id ajusta ou desliga.
• Como a IA analisa: configurar_analise muda o perfil, se reunião só do time é analisada e se a análise sugere negócio e desfecho.
• Toda escrita é prévia por padrão (simular: true): o banco aplica, mede o antes → depois e desfaz. Mostre a prévia à pessoa e grave com simular: false só depois do ok. A gravação fica na auditoria como mcp.write.
• As próximas reuniões já são analisadas com a régua nova. Para conferir agora, reanalisar_reuniao numa reunião recente (usa uma análise da cota).
• "Configurar o comercial" é um acesso sensível: curinga (*:write), a chave antiga "write" e o OAuth padrão não chegam. Só Dono ou Gestor com Processo › Editar.

Configurar o resto da empresa pelo Claude

• Chave Personalizada com "Configurar a empresa" (alterar). A empresa precisa do Assistente no plano e a pessoa da permissão de usá-lo.
• ver_tipos_configuracao lista o que dá para montar: nomes e menu (estrutura_empresa), configuracao, funil, campos, modelo_projeto, modelo_empresa (só prévia e link; aplica na tela), categorias_aviso, whatsapp_padrao, organizacao_conhecimento, financeiro (só categorias), trilha, atribuir_trilha e teste_treino.
• preparar_configuracao_empresa(tipo, dados) monta a prévia e devolve previa_id com o de → para. Nada muda ainda. A prévia aparece também no Assistente, na conversa "Pelo Claude (MCP)".
• Pastas com documentos dentro (0.99): organizacao_conhecimento aceita criar_pastas e criar_documentos na mesma prévia, ligados pelo apelido: {"criar_pastas":[{"ref":"p1","nome":"Rotina mensal"}],"criar_documentos":[{"titulo":"Checklist do fechamento","tipo":"sop","conteudo":"## Passos…","pasta_ref":"p1"}]} (até 20 pastas e 10 documentos).
• aplicar_previa(previa_id, confirmar: true) grava tudo ou nada; desfazer_alteracao(previa_id) volta; descartar_previa cancela; listar_previas mostra o que já foi feito.
• Fica fora deste módulo: Processo e análise (use processo_editar), automações, cadastros, lançamentos do Financeiro, lixeira, cargos, integrações, pessoas e cobrança.
• Acesso sensível: curinga (*:write), a chave antiga "write" e o OAuth padrão não chegam. Leituras e gravações respeitam o cargo da pessoa dona da chave, como na tela.

Automações pelo MCP

• Módulo automacoes (ler e alterar): listar_automacoes, ler_automacao, catalogo_automacoes (gatilhos e passos aceitos), historico_automacao e rodadas; criar_automacao e editar_automacao mexem só no rascunho; testar_automacao simula sem mandar nada para fora.
• Módulo automacoes_publicar (sensível, só alterar): publicar, pausar, ativar, arquivar, rodar_automacao_agora (só gatilho manual), repetir e cancelar rodada e voltar_versao. Publicar, rodar e voltar versão pedem confirmar_nome com o nome exato.
• Passo que manda algo para fora da empresa (chamar outro app, e-mail, WhatsApp, resposta ao cliente) novo ou alterado em relação à versão publicada só se publica pela tela. Chave com automacoes_publicar pede 2FA ao criar e ao trocar.
• Segredos do desenho voltam como ••••; ao editar, mande •••• para manter o valor guardado.
• 0.77: publicar confere o desenho como a tela; com passo incompleto, a recusa lista até 6 pontos (Falta completar N pontos antes de publicar: …). No catalogo_automacoes, as variáveis comuns a todo acontecimento (event.*) vêm uma vez só, em variaveis_de_todo_acontecimento. Gatilhos novos: finance.entry_paid, finance.entry_overdue, whatsapp.message_received (com filter: group, phone, contains), project.hours_warning e project.hours_exceeded. Ações: ticket.find; cargo em task.create, notify e reminder.create; e-mail em client.lookup; template_name em project.create.
• 0.77 (bateria de fluxos): gatilhos novos task.commented (Comentaram na tarefa; dados task e comment {id, body até 1.000, author_user_id}) e project.hours_milestone (Horas do projeto: 80% ou estouro; sai uma vez por marco e por projeto, hours.milestone 80 ou 100). hours ganha extra e extra_minutes nos três gatilhos de horas. filter de whatsapp.message_received aceita client: true (só conversas ligadas a um cliente), e a mensagem traz client_name e project_name. client.created traz origin (cadastro, importacao ou automatico); finance.entry_paid e finance.entry_overdue trazem fin_entry.first_payment; ticket.sla_breached traz client_breaches_7d. Ação nova finance.lookup (Ver a conta do Financeiro, só lê; entry_id → entry.paid, status, days_late, amount_text, due_date, paid_at, client_name, project_id, link). Campos novos: allow_back em project.set_stage (volta para a etapa), if_none: main em training.assign, people e people_count em meeting.list, client.email, client.phone e project.id/name em client.lookup. Definir valores ganha a operação calc (+ − × ÷ e parênteses). Em qualquer passo depois de um erro: {{run.error}} e {{run.error_step}}. whatsapp.send com um cliente em to vai para o grupo ligado ao cliente.
• 0.86: gatilho novo task.column_changed (tarefa mudou de coluna no quadro). O filter do gatilho também vale para project.stage_changed (stage = nome da etapa, template = nome do modelo) e task.column_changed (stage = nome da coluna), sem diferença de acento ou maiúscula: é o que o raio da coluna do quadro cria.

Receber em automações

Na automação, escolha o gatilho Ao receber de outro app, clique nele e use Gerar chave. O painel mostra o endereço (com o id da automação) e a chave, uma vez só. Publique a automação para ela começar a receber.

curl -sS -X POST "https://mentrun.com.br/api/automacoes/ID_DA_AUTOMACAO" \
  -H "Content-Type: application/json" \
  -H "x-cortex-key: cxh_SUA_CHAVE" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{"id":"pedido-1234","cliente":{"nome":"Loja Aurora"},"valor":350}'

curl -sS -X POST "https://mentrun.com.br/api/automacoes/ID_DA_AUTOMACAO/cxh_SUA_CHAVE" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "id=pedido-1234" \
  --data-urlencode "nome=Loja Aurora"

{ "ok": true, "status": "queued", "run_id": "3f6c1d2e-..." }
{ "ok": true, "status": "duplicate", "run_id": "3f6c1d2e-..." }
{ "ok": true, "status": "sample" }
{ "ok": true, "status": "held" }

• Só POST. A chave vai em x-cortex-key, em Authorization: Bearer ou no fim do endereço. Se vier cabeçalho, ele vale (o caminho não salva um cabeçalho errado).
• Corpo: qualquer objeto JSON, ou formulário (application/x-www-form-urlencoded, até 200 campos). Até 256 KB.
• Automação publicada e ativa: o aviso roda a automação (queued). Ainda em rascunho ou sem versão publicada: volta 202 com status sample, o aviso fica guardado como exemplo para montar os passos e nada roda. Publicada e pausada (à mão, depois de 5 falhas seguidas ou pela trava contra laço): volta 202 com status held, o aviso fica guardado por até 7 dias (até 500 por automação e 64 KB cada) e roda quando a empresa reativar a automação e escolher rodar os guardados; não precisa mandar de novo. Se não der para guardar (500 já guardados, aviso maior que 64 KB), volta 503 paused com Retry-After: 300 e o aviso precisa ser mandado de novo depois de reativar. Arquivada ou módulo desligado: 409.
• O 202 volta na hora e a execução começa em até cerca de um minuto. Veja o resultado em Automações › Execuções.
• Repetição: mande Idempotency-Key (até 150 caracteres visíveis, sem espaço) ou indique no gatilho o campo do corpo que identifica o aviso (ex.: id ou pedido.id). Com uma dessas chaves, a repetição é ignorada enquanto a execução existir (30 dias de histórico). Sem nenhuma, o mesmo conteúdo repetido em 24 horas é ignorado (os mesmos campos e valores, mesmo em outra ordem, com outra formatação ou como formulário).
• Gerar nova chave derruba a anterior na hora.
• Por empresa: até 5 execuções ao mesmo tempo e 300 execuções novas por hora (o excedente espera na fila). Por automação: até 500 na fila (acima disso, 429 busy). Uma execução roda até 50 passos (ou 300 passos quando tem Para cada item) e 2 minutos de tempo ativo. Depois de 5 falhas seguidas, a automação pausa sozinha.
• Chamada é de servidor para servidor (sem CORS para navegador).

Usar os dados recebidos nos passos

Use nomes de campo com letras sem acento, números e _ (até 64 caracteres por nível, até 12 níveis). Campo com hífen, espaço, acento ou ponto no nome não pode ser lido por variável.

CRM: enviar ao Mentrun

Para qualquer CRM ou plataforma de automação (Make, n8n, Zapier). Em Empresa › Conectar outros apps › CRM, informe o nome do CRM e clique em Conectar CRM: o Mentrun mostra o endereço de entrada (com o id da conexão), o segredo de entrada e o segredo de saída, uma vez só. Ali também ficam o Mapa de etapas, o Funil de destino e o Mapa de pessoas.

SECRET='whsec_SEU_SEGREDO_DE_ENTRADA'
URL='https://mentrun.com.br/api/crm/ID_DA_CONEXAO'
BODY='{"event_id":"evt-0001","type":"deal.upsert","data":{"external_id":"D-100","title":"Contrato anual","client_name":"Cliente Exemplo","value":12000,"stage":"proposta","owner_email":"vendedor@suaempresa.com.br"}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -sS -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "x-cortex-signature: t=$TS,v1=$SIG" \
  --data-raw "$BODY"

{ "ok": true, "event_id": "evt-0001", "status": "done", "deal_id": "9b1e...", "created": true, "warning": null }
{ "ok": true, "event_id": "evt-0002", "status": "ignored", "detail": "Sem mudanças desde o último evento.", "deal_id": "9b1e..." }
{ "ok": true, "event_id": "evt-0001", "duplicate": true, "status": "done" }

* obrigatório

• Envelope: {"event_id", "type", "data"}. event_id (até 200 caracteres) é único por conexão: repetir devolve 200 com duplicate: true, sem aplicar de novo.
• Assinatura obrigatória em x-cortex-signature: t=<segundos unix>,v1=<HMAC-SHA256 em hex de "t.corpo">, com o segredo de entrada inteiro (incluindo whsec_) como chave. Tolerância de 5 minutos.
• stage é procurado no Mapa de etapas pelo texto exato (diferencia maiúsculas, até 60 etapas). Etapa mapeada para ganho ou perda ganha ou perde o negócio. Sem correspondência, o negócio vai para a primeira etapa aberta do funil, inclusive um negócio que já existia, com aviso em warning. Sem stage, a etapa não muda.
• owner_email procura o Mapa de pessoas, depois um Dono, Gestor ou Vendedor ativo com o mesmo e-mail, depois o responsável padrão e, por fim, a pessoa que conectou o CRM.
• occurred_at mais antigo que o último evento aplicado é ignorado (evita sobrescrever com dado velho).
• Processa na hora, numa transação só. Dado inválido volta 422 (error: rejected, com message): corrija e mande com um event_id novo. Reenviar o event_id recusado volta 200 com duplicate: true e status: rejected, sem aplicar. O event_id é lembrado por 90 dias.
• Girar o segredo de entrada troca na hora: o que vier assinado com o antigo volta 401. Conectar o CRM de novo gera os dois segredos; desconectar faz o endereço responder 404.
• Mudança que entrou pelo CRM não volta para ele pelo webhook de saída (sem eco).

BODY='{"event_id":"evt-0002","type":"meeting.create","data":{"external_id":"M-200","title":"Diagnóstico Loja Aurora","started_at":"2026-10-21T14:00:00-03:00","duration_min":45,"participants":[{"name":"Ana Souza","email":"ana@lojaaurora.com.br"}],"owner_email":"vendedor@suaempresa.com.br","deal_external_id":"D-100","transcript":"Vendedor: Bom dia, Ana.\nAna: Bom dia, vamos falar do plano anual."}}'
# 200 {"ok":true,"event_id":"evt-0002","status":"done","meeting_id":"…","created":true}
# A análise roda depois; quando terminar, sai meeting.analyzed se esse evento estiver marcado.

Webhooks de saída

Na mesma aba CRM, ligue Enviar eventos para o CRM, cole a URL do seu sistema e marque os eventos. A tela mostra os últimos envios com situação, tentativas e último erro, e tem o botão Enviar evento de teste.

Requisição

{
  "id": "6f1c2b9e-4a7d-4e2b-9c1a-2d3e4f5a6b7c",
  "type": "deal.stage_changed",
  "created_at": "2026-10-22T14:03:11.482913+00:00",
  "data": {
    "deal": {
      "id": "0b8e5c1a-...",
      "title": "Plano anual",
      "client_name": "Padaria Exemplo Ltda",
      "value": 12000.00,
      "status": "open",
      "lost_reason": null,
      "owner_user_id": "a1b2c3d4-...",
      "next_step": "Enviar proposta revisada",
      "stage": { "id": "9c0d...", "name": "Proposta", "kind": "open", "key": "proposta" }
    },
    "previous_stage": { "id": "7e1f...", "name": "Diagnóstico", "kind": "open", "key": "diagnostico" },
    "external_ids": { "pipedrive": "D-100" }
  }
}

Entrega e novas tentativas

• Uma URL de destino por empresa, só HTTPS na porta 443. Endereço interno, IP direto ou localhost é recusado ao salvar e de novo a cada envio.
• POST com prazo de 10 segundos. Só resposta 2xx conta como entregue; redirecionamento não é seguido e conta como falha.
• Falhou (inclusive 4xx)? Nova tentativa depois de 1 min, 5 min, 30 min, 2 h e 12 h: 6 tentativas em cerca de 14 horas e meia. Depois disso o evento fica como falha na tela, com botão Reenviar.
• Entrega pelo menos uma vez e sem ordem garantida. Descarte repetidos pelo id (ou x-cortex-event-id). O botão Reenviar manda o mesmo id.
• A assinatura é refeita a cada tentativa (t muda). Responda 2xx rápido e processe depois.
• Só entra na fila o evento que acontece com o envio ligado e o tipo marcado: não há envio retroativo. O evento de teste também exige o envio ligado.
• Girar o segredo de saída troca na hora, inclusive nas novas tentativas: aceite os dois segredos no seu lado por alguns minutos.
• Envios entregues ou em falha ficam 30 dias na tela, com o botão Reenviar.

Conferir a assinatura

O cabeçalho x-cortex-signature traz t=<segundos unix>,v1=<hex>. O v1 é o HMAC-SHA256, em hexadecimal minúsculo, de t + "." + corpo cru, usando o segredo inteiro como chave: no webhook de saída, o segredo de saída do CRM (com o whsec_); no passo de automação, o segredo cadastrado na credencial de assinatura (em GET e DELETE o corpo assinado é vazio). Recuse se o horário estiver a mais de 5 minutos do seu relógio. Confira sobre o corpo cru, em UTF-8, sem reformatar o JSON.

import crypto from "node:crypto";

// Use o corpo CRU (ex.: express.raw({ type: "application/json" })): não reserialize o JSON.
export function verificarCortex(rawBody, header, secret, toleranciaSeg = 300) {
  if (!header) return false;
  const partes = header.split(",").map((p) => p.trim());
  const t = partes.find((p) => p.startsWith("t="))?.slice(2);
  const assinaturas = partes.filter((p) => p.startsWith("v1=")).map((p) => p.slice(3));
  if (!t || !/^\d+$/.test(t) || assinaturas.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranciaSeg) return false;
  const esperado = Buffer.from(
    crypto.createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest("hex"),
    "hex",
  );
  return assinaturas.some((s) => {
    const b = Buffer.from(s, "hex");
    return b.length === esperado.length && crypto.timingSafeEqual(b, esperado);
  });
}

import hashlib, hmac, re, time

def verificar_cortex(raw_body: bytes, header: str, secret: str, tolerancia: int = 300) -> bool:
    if not header:
        return False
    partes = [p.strip() for p in header.split(",")]
    t = next((p[2:] for p in partes if p.startswith("t=")), "")
    assinaturas = [p[3:].strip().lower() for p in partes if p.startswith("v1=")]
    if not re.fullmatch(r"[0-9]{1,12}", t) or not assinaturas or abs(int(time.time()) - int(t)) > tolerancia:
        return False
    esperado = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest().encode()
    return any(hmac.compare_digest(s.encode(), esperado) for s in assinaturas)

Automação chama seu app

No editor de automações, o passo Chamar outro app faz a requisição para o seu sistema.

• Métodos GET, POST, PUT, PATCH e DELETE; endereço, cabeçalhos e corpo JSON aceitam variáveis ({{trigger.body.x}}, {{steps.<id>.response.body.x}}).
• Acesso guardado em Automações › Configurações › Chaves de outros apps: Bearer, usuário e senha, chave em cabeçalho próprio, chave num parâmetro do endereço (por exemplo ?api_key=, nome do parâmetro configurável) ou segredo de assinatura (o mesmo x-cortex-signature descrito acima). A chave nunca aparece no histórico.
• Atalho Enviar aviso para outro app: um POST com os dados do gatilho já no corpo (até 20 campos, um por linha, que você edita ou apaga: evento, quando e os campos do registro) e 3 novas tentativas por padrão; cole o endereço do seu sistema. Links do Mentrun vão completos ({{app.url}} + caminho).
• Gatilho de reunião (Reunião chegou, Reunião analisada) traz participant_names, participant_emails, external_emails (e-mails de fora), host_email, is_external, duration_min, call_type, source e link; a analisada traz também summary e next_steps_text. A transcrição nunca vai.
• Cabeçalhos que sempre vão: user-agent Mentrun-Automacoes/1, accept e idempotency-key <execução>:<passo> (com :<visita> quando o passo roda de novo na mesma execução), para você descartar repetição.
• Prazo de 1 a 10 segundos (padrão 8). Corpo só em POST, PUT e PATCH, até 64 KB; resposta lida até 256 KB. Até 3 redirecionamentos: 301, 302 e 303 viram GET sem corpo, e credencial e assinatura não seguem para outro domínio. Novas tentativas configuráveis (0 a 5) para erro de rede ou DNS, 408, 425, 429 e 5xx, com espera crescente a partir de 30 s (até 1 h) e respeitando Retry-After.
• A resposta fica disponível para os próximos passos em {{steps.<id>.response.status}}, {{steps.<id>.response.ok}}, {{steps.<id>.response.body.<campo>}} e os campos mapeados no passo em {{steps.<id>.mapped.<nome>}}. Resposta em texto com mais de 2.000 caracteres chega cortada.
• Mesmas travas de endereço do webhook de saída (só https público, porta 443). O passo não pode chamar nenhum endereço do próprio Mentrun (nem a entrada de automações, nem o MCP, nem a integração de CRM), também depois de redirecionamento: use um passo de ação. No Testar agora a chamada é simulada e nada sai; o botão Testar a chamada do passo manda de verdade e mostra a resposta.

Erros e limites

Todas as respostas de erro vêm em JSON. No MCP, erro de protocolo segue o JSON-RPC ({"error":{"code":-32001,"message":"..."}}); nos webhooks, {"ok":false,"error":"..."}.

MCP 401 (cabeçalho www-authenticate: Bearer resource_metadata="https://mentrun.com.br/.well-known/oauth-protected-resource/api/mcp", error="invalid_token")
{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"Acesso ao MCP ausente, inválido, expirado ou revogado."}}

MCP 429 (cabeçalho retry-after: 60; com teto liberado, o número na mensagem é o da empresa)
{"jsonrpc":"2.0","id":null,"error":{"code":-32000,"message":"Limite de chamadas atingido. Tente em um minuto. Limite de 60 requisições por minuto. Precisa de mais? Fale com o suporte e conte o motivo, que avaliamos liberar."}}

MCP 503
{"jsonrpc":"2.0","id":null,"error":{"code":-32000,"message":"Serviço indisponível. Tente de novo em instantes."}}

MCP 200 (ferramenta com nome errado)
{"jsonrpc":"2.0","id":7,"error":{"code":-32602,"message":"Ferramenta desconhecida: criar_tarefas"}}

Automação 401  {"ok":false,"error":"unauthorized"}
Automação 202  {"ok":true,"status":"held","detail":"A automação está pausada no Mentrun: o aviso ficou guardado (por até 7 dias) e roda quando alguém da empresa reativar a automação e escolher rodar os guardados. Não precisa mandar de novo."}
Automação 503  {"ok":false,"error":"paused","detail":"A automação está pausada no Mentrun e este aviso não foi processado. Mande de novo depois que ela for reativada."}
Automação 409  {"ok":false,"error":"inactive","detail":"A automação não está publicada e ativa para receber (publique ou ative no Mentrun)."}
Automação 413  {"ok":false,"error":"payload_too_large","max_bytes":262144}
Automação 429  {"ok":false,"error":"rate_limited","detail":"Limite de 60 requisições por minuto. Precisa de mais? Fale com o suporte e conte o motivo, que avaliamos liberar."}

CRM 401  {"ok":false,"error":"invalid_signature","reason":"stale"}
CRM 422  {"ok":false,"error":"invalid_event","errors":["type: ..."]}
CRM 422  {"ok":false,"error":"rejected","event_id":"evt-0001","message":"O negócio novo precisa de \"title\"."}
CRM 403  {"ok":false,"error":"read_only","message":"A assinatura está só leitura."}
CRM 429  {"ok":false,"error":"rate_limited","message":"Limite de 60 requisições por minuto. Precisa de mais? Fale com o suporte e conte o motivo, que avaliamos liberar."}

No MCP, outros erros JSON-RPC voltam com HTTP 200: -32600 (lote ou requisição inválida), -32601 (método não suportado) e -32602 (ferramenta desconhecida). É diferente do isError, que é a ferramenta recusando o pedido.

Proteções de uso

Tudo que chega de fora (MCP, avisos para automações e webhook do CRM) tem teto de 60 requisições por minuto, ou o teto que a nossa equipe liberou para a sua empresa. Passou do limite: a resposta é 429 com Retry-After: 60 e a mensagem diz o limite que vale e o que fazer. O limite de alterações do MCP não dá 429: a ferramenta volta isError com a mensagem de muitas alterações seguidas.

Precisa de mais de 60 por minuto? O Dono ou o Gestor toca em Pedir mais limite em Empresa › Conectar outros apps › Nova chave (no campo Limite de chamadas por minuto) e conta o motivo, o app e quantas chamadas por minuto espera, até 600. O pedido vira um chamado no Suporte; a nossa equipe avalia e libera para a sua empresa. Liberado, o novo teto vale para a empresa toda (chaves do MCP, avisos para automações e webhook do CRM, cada um no seu contador) e aparece no mesmo campo como Teto da empresa. O uso normal pelas telas do sistema não entra nesse limite.

Por quanto tempo fica guardado

Segurança

As chaves dão acesso real aos dados da empresa. Siga estas regras antes de entregar uma chave a uma pessoa, a uma IA ou a outro sistema.

• Chave que altera ou exclui é uma senha de máquina: quem tiver o endereço único ou a chave age em nome da pessoa dona, dentro do cargo dela, e tudo fica no histórico com o nome dessa pessoa.
• Comece em Só leitura, com validade curta (30 dias), uma chave por pessoa e por uso. Dê Alterar só nos módulos necessários e Excluir só quando precisar.
• Nunca cole a chave em repositório, planilha, chat, e-mail ou print, nem em código que roda no navegador. O endereço único (cxu_) é tão sensível quanto a chave.
• Uma IA com permissão de alterar pode mudar muitos itens em segundos se entender errado um pedido. Peça para ela listar o que vai mudar antes de confirmar.
• Transcrições, documentos e chamados podem trazer instruções escritas por terceiros: o assistente deve tratá-las como dados. Confirme cada alteração que ele propuser.
• Vazou? Revogue ou gire na hora em Empresa › Conectar outros apps e confira a aba Uso e auditoria.