Habilidade de Workflow n8n

O que Habilidade de Workflow n8n faz?

Construa, implante e gerencie workflows n8n inteiramente através da API usando snippets de nós pré-construídos e padrões testados em batalha.

Configuração

Antes do primeiro uso, preencha os detalhes da sua instância abaixo. Obtenha sua chave de API em n8n Configurações > API.

• URL: https://YOUR_INSTANCE.app.n8n.cloud
• Chave de API: YOUR_API_KEY
• ID do Projeto: YOUR_PROJECT_ID (opcional, para instâncias com vários projetos)

Credenciais

Mapeie seus aliases de credenciais aqui. Obtenha os IDs de GET /api/v1/credentials.

Alias	Tipo de Credencial	ID	Nome
gmail	gmailOAuth2
sheets	googleSheetsOAuth2Api
slack	slackOAuth2Api
openai	openAiApi
anthropic	anthropicApi
telegram	telegramApi
notion	notionApi

Adicione linhas conforme necessário. O campo name deve corresponder exatamente ao nome que você deu à credencial em sua instância n8n (Configurações > Credenciais). Os snippets de nós em ./references/nodes/ usam credenciais placeholder — o Claude substitui seus IDs desta tabela ao construir workflows.

---

Início Rápido: Novo Workflow

1. Verifique ./references/nodes/ para snippets de nós pré-construídos. Copie, renomeie e defina as posições.
2. Construa o JSON (array de nós + objeto de conexões).
3. Escreva em /tmp/<name>.json.
4. Execute: bash ./references/deploy.sh /tmp/<name>.json
5. Pronto. O script lida com POST, transferência de projeto, verificação e atualização de índice.

---

Formato de Conexão

"Nome da Fonte": { "main": [[{"node": "Alvo", "type": "main", "index": 0}]] }

• Fan-out (uma fonte, vários alvos): "main": [[{"node": "A", ...}, {"node": "B", ...}]]
• Mesclar entradas: a fonte A conecta com "index": 0, a fonte B com "index": 1
• Ramificação IF: "main": [ [alvos verdadeiros], [alvos falsos] ]
• Sub-nó de IA: "ai_languageModel": [[{"node": "Nome do Modelo", "type": "ai_languageModel", "index": 0}]]
• Sub-nó de ferramenta de IA: "ai_tool": [[{"node": "Nome da Ferramenta", "type": "ai_tool", "index": 0}]]

---

Estrutura JSON do Workflow

{
  "name": "Nome do Workflow",
  "nodes": [...],
  "connections": {...},
  "settings": { "executionOrder": "v1", "callerPolicy": "any" }
}

• O corpo do POST NÃO deve incluir o campo active (somente leitura, use PATCH para ativar)
• Remova todas as chaves de configuração exceto: executionOrder, callerPolicy, saveDataSuccessExecution, errorWorkflow (se existir)
• Chaves que devem ser removidas antes do PUT: binaryMode, availableInMCP, timeSavedMode

---

Endpoints da API

POST   /api/v1/workflows              — criar
GET    /api/v1/workflows/{id}         — buscar (SEMPRE antes do PUT)
PUT    /api/v1/workflows/{id}         — atualizar
PATCH  /api/v1/workflows/{id}         — ativar/desativar: { "active": true }
PUT    /api/v1/workflows/{id}/transfer — mover para projeto
GET    /api/v1/executions/{id}?includeData=true — buscar dados de execução
GET    /api/v1/credentials            — listar todas as credenciais

---

Regras

• GET antes do PUT — nunca modifique a partir do cache, sempre busque a versão atual primeiro
• Verificar após PUT — busque novamente e confirme que as alterações foram aplicadas
• Conexões usam nomes de NÓS, nunca UUIDs
• Prefira nós nativos da plataforma em vez de HTTP Request (mostra logotipos da plataforma na interface)
• Nós de código com caracteres !: escreva JS em /tmp/*.js primeiro, depois leia de volta (escapamento de string Python transforma ! em \!)
• includeData=true em buscas de execução (sem isso, data.resultData.runData é nulo)
• Valores permitidos para callerPolicy: any, none, workflowsFromAList, workflowsFromSameOwner

---

Sintaxe de Expressão (corpo HTTP Request)

• FUNCIONA: ={{ ({ key: value }) }} — objeto entre parênteses, sem JSON.stringify
• QUEBRADO: ={{ JSON.stringify({...}) }} — causa "sintaxe inválida"
• QUEBRADO: ={{ }} incorporado dentro de corpo JSON estático — não é avaliado
• Referência entre nós: $item(0).$node["NomeDoNó"].json.field

---

Biblioteca de Nós

Snippets de nós pré-construídos estão em ./references/nodes/. Cada arquivo é um objeto JSON de nó pronto para uso.

Fluxo de trabalho obrigatório:

1. Antes de construir qualquer nó, faça glob em ./references/nodes/*.json para ver o que está disponível.
2. Se o tipo de nó existir na biblioteca, copie seu JSON e personalize (nome, posição, parâmetros). NÃO escreva do zero.
3. Se o tipo de nó NÃO existir na biblioteca, construa-o do zero.
4. Após implantar o workflow, salve quaisquer novos tipos de nó que você construiu na biblioteca como ./references/nodes/<nome-do-nó>.json.

---

Referências Profundas (carregue apenas quando necessário)

• ./references/patterns.md — padrões de repetição, estado persistente, pegadinhas de expressão
• ./references/rules.md — regras de PUT/POST, lista de permissões de configurações, convenções de nomenclatura
• ./references/node-types.md — referência de parâmetros para tipos de nós comuns