Pular para conteúdo

n8n — instância Bepex

Motor de automação self-hosted. Quase toda a lógica de negócio da Bepex vive aqui. Este doc é o backbone da instância (acesso, auth, quirks, MCP). A arquitetura de cada pipeline específico mora na referencia-tecnica.md do projeto correspondente.

Instância

Parâmetro Valor
URL base https://n8n.bepex.com.br
Webhooks de produção https://n8n-hook.bepex.com.br
Interface https://n8n.bepex.com.br/home/workflows
Login https://n8n.bepex.com.br/signin
Banco SQLite, processo único

Autenticação de sessão (API REST interna)

Sessão baseada em cookie + header customizado. Expira com frequência (minutos).

⚠️ NUNCA usar navigate (page load) para URLs /rest/*. O n8n invalida o cookie quando um endpoint REST é aberto como page load (sem header browser-id). Sempre navegar para uma página da UI primeiro (/workflow/XXX, /home/workflows) e depois usar fetch('/rest/...', { headers: { 'browser-id': bid } }) via javascript_tool.

⚠️ NUNCA bater em endpoints de auth (/rest/login, /rest/me) — invalida a sessão do operador. Se der 401, seguir o fluxo de re-login abaixo.

Header obrigatório: browser-id — lido de localStorage.getItem('n8n-browserId') (valor fixo por browser). O push-ref (sessionStorage.getItem('n8n-client-id')) não é necessário para a REST interna — os cookies são same-origin e vão automaticamente.

Re-login quando a sessão expira (401 ou redirect para /signin)

  1. Navegar para /signin (credenciais já vêm preenchidas por autofill).
  2. Clicar em Sign in.
  3. Se o click falhar porque o Vue não reconhece o autofill (v-model vazio): clicar no campo email → End → digitar espaço → Backspace → clicar no campo password → x → Backspace → Enter. O ato de digitar dispara input/change que o Vue ouve.

Endpoints REST internos úteis

GET   /rest/workflows                          -> listar todos
GET   /rest/workflows/{id}                     -> buscar (nodes, connections, settings)
PATCH /rest/workflows/{id}                     -> atualizar (reseta active=false)
POST  /rest/workflows/{id}/activate            -> ativar (body: { versionId })
GET   /rest/executions?filter={...}            -> listar execuções (filter é JSON URL-encoded)
GET   /rest/executions/{id}?includeData=true   -> detalhes (formato flatted)
POST  /rest/executions/{id}/retry              -> ⚠️ usa SNAPSHOT ANTIGO do workflow
GET   /rest/credentials                        -> listar credenciais

Padrão de PATCH + reativação: GET (pega versionId) → PATCH (nodes) → GET de novo (novo versionId) → POST /activate com o versionId fresh. O versionId muda a cada PATCH — nunca cachear.

Parsing de execuções (formato flatted)

data.data vem como string JSON no formato flatted (array deduplicado; strings numéricas são índices). Precisa de um resolver que segue os índices. O tool MCP get_execution_node_output já decodifica automaticamente — preferir ele quando disponível.

Credenciais na instância

Nome no n8n ID Tipo Uso
Pipedrive account CHj11AO6T3756SqM pipedriveApi Leitura + escrita
Bepex Enrico n5IiwdsiIB3dAUQE pipedriveApi Somente leitura
Postgres n8n v2 7F3gxDoPsQGjAbOW postgres rw — pool_conteudos, representantes, memória de agentes
AWS account kqmbhAWS0tyL5fuI aws Amazon SES (us-east-2)
n8n account (n8nApi) hJX4nrWluQt6BE28 n8nApi Injeta X-N8N-API-KEY no MCP Inspector

Credenciais OpenRouter (uma por sistema) estão em openrouter.md. IDs de credencial são identificadores internos (só válidos dentro da instância) — não são segredos criptográficos, ficam nos docs. Os valores das API keys nunca entram no repo.

MCP Server — n8n Inspector

Workflow interno que expõe a instância como servidor MCP, permitindo inspecionar workflows/execuções sem browser automation. Criado em 2026-05-14.

Parâmetro Valor
Workflow ID 4R4jVyFbohJlER7q
MCP SSE URL https://n8n.bepex.com.br/mcp/${N8N_MCP_SSE_TOKEN}
Credencial n8nApi hJX4nrWluQt6BE28
Helper workflow JaL0rBEjTYd2G4Pu — webhook GET https://n8n-hook.bepex.com.br/webhook/exec-node-out-bepex

Tools disponíveis (10): list_workflows (sempre passar limit — sem filtro devolve 9MB+), get_workflow, list_executions, get_execution, get_execution_node_output, activate_workflow, deactivate_workflow, list_credentials, trigger_webhook (o path DEVE incluir o prefixo webhook/).

⚠️ Bug crítico: nunca chamar operação de patch/execução via MCP apontando para o próprio ID do MCP server (4R4jVyFbohJlER7q) — auto-patch mata a sessão MCP. Os tools patch_workflow e execute_workflow foram removidos em 2026-05-22 (a API pública da versão instalada retorna 405). Para editar workflows, usar o PATCH via browser (fetch('/rest/workflows/{id}', {method:'PATCH'})).

Comportamento do servidor (SQLite, processo único)

  • Uma execução ativa segura o write lock do banco → pode bloquear chamadas REST simultâneas.
  • Nós que chamam APIs externas lentas (OpenRouter, Pipedrive) podem travar o servidor por segundos.
  • Quando parecer travado: F5 primeiro. Quase sempre a execução já terminou e só a UI não atualizou. Ctrl+Shift+R só se o F5 não resolver.
  • Save de execuções: o default do n8n não salva execuções de sucesso. Nunca diagnosticar "cron parado" pela ausência de execuções — checar o Save settings do workflow.

Pegadinhas

  • retry usa o snapshot antigo do workflow — não valida um fix recém-aplicado via PATCH. Para validar fix: disparar o webhook de novo ou rodar manual via Ctrl+Enter no editor.
  • PATCH reseta active: false — sempre reativar com versionId fresh.
  • POST /rest/workflows/{id}/run retorna 500 (payload não mapeado) — usar Ctrl+Enter na UI.
  • DELETE /rest/workflows/{id} retorna 400 — apagar workflow só pela UI.
  • Webhook node ao clonar via REST: NÃO setar httpMethod automaticamente. BPEX manda GET (default); setar POST quebra produção silenciosamente (404 no roteador). Se webhook der 404, não assumir que é o método — verificar via JS qual método o node está configurado.
  • IF isNotEmpty não funciona em nós criados via REST API — usar notEquals "".
  • Schedule Trigger cacheia snapshot após PATCH — deactivate → reactivate para o cron pegar a versão nova.

Índice de workflows (resumo)

O mapa completo de workflows por projeto/disciplina será consolidado em ../indices/automacoes.md pela sessão principal (ver a tabela levantada no log da S9). Workflows de infra/backbone conhecidos:

ID Nome Papel
4R4jVyFbohJlER7q MCP Server — n8n Inspector Backbone MCP (ver acima)
JaL0rBEjTYd2G4Pu Helper exec-node-out Suporte ao MCP Inspector
pflBwIjA8OBpKFHj ERROR TRIGGER Tratamento de erro global
FAsAcSvdYxvURl7z Recebe orçamento feito pelo site Ingestão de orçamento BPEX
QppShVonF0S74T5W TOOL GET FIELDS PIPEDRIVE Utilitário (ver skill n8n-bepex-pipedrive)
toquIjzNhIsNN59O _TEMP_Probe_Pipedrive Diagnóstico/SQL ad-hoc

Workflows de projetos de negócio (Conteúdo Infinito WF0–WF4, Rep, Caramelo, Ofertas, IA Chatwoot, Omie, Betão/Kowalski, etc.) estão listados na referencia-tecnica.md de cada projeto e no índice transversal de automações.