Description
n8n-nodes-starter
This repo contains example nodes to help you get started building your own custom integrations for n8n. It includes the node linter and other dependencies.
To make your custom node available to the community, you must create it as an npm package, and submit it to the npm registry.
If you would like your node to be available on n8n cloud you can also submit your node for verification.
Prerequisites
You need the following installed on your development machine:
- git
- Node.js and npm. Minimum version Node 20. You can find instructions on how to install both using nvm (Node Version Manager) for Linux, Mac, and WSL here. For Windows users, refer to Microsoft’s guide to Install NodeJS on Windows.
- Install n8n with:
npm install n8n -g
Using this starter
These are the basic steps for working with the starter. For detailed guidance on creating and publishing nodes, refer to the documentation.
1. Generate a new repository from this template repository.
2. Clone your new repo:
git clone https://github.com//.git
3. Run npm i to install dependencies.
4. Open the project in your editor.
5. Browse the examples in /nodes and /credentials. Modify the examples, or replace them with your own nodes.
6. Update the package.json to match your details.
7. Run npm run lint to check for errors or npm run lintfix to automatically fix errors when possible.
8. Test your node locally. Refer to Run your node locally for guidance.
9. Replace this README with documentation for your node. Use the Publish your package to npm.
More information
Refer to our documentation on creating nodes for detailed information on building your own nodes.
Resiliência de rede
O servidor do PNCP é frequentemente lento e instável. O node trata falhas
transitórias automaticamente, sem quebrar o workflow.
Configuração (credencial PNCP API)
| Campo | Default | O que faz |
| — | — | — |
| Timeout Por Requisição (Ms) | 60000 | Aborta e retenta requisições mais lentas que isso |
| Máximo De Tentativas | 4 | Total de tentativas, incluindo a primeira |
| Backoff Inicial (Ms) | 1000 | Base da espera exponencial entre tentativas |
| Backoff Máximo (Ms) | 16000 | Teto da espera, inclusive do Retry-After |
| Intervalo Entre Páginas (Ms) | 200 | Pausa entre páginas no modo “Buscar Todas Páginas” |
Credenciais salvas antes desta versão continuam funcionando: os campos ausentes
assumem os defaults acima.
Retentado: status 408, 425, 429 e qualquer 5xx; e as falhas de rede
ECONNRESET, ETIMEDOUT, ESOCKETTIMEDOUT, EAI_AGAIN, EPIPE,
ECONNABORTED (timeout do cliente — a falha mais comum contra o PNCP) e
ECONNREFUSED.
Não retentado: 4xx como 400, 401, 404 e 422 falham de imediato —
retentar um CNPJ inválido não muda o resultado. ENOTFOUND e
CERTHASEXPIRED também são permanentes.
A espera entre tentativas é sorteada entre zero e o teto exponencial. Esse
jitter não é enfeite: sem ele, todos os workflows que falham no mesmo minuto
retentam no mesmo instante e mantêm o servidor derrubado. Quando a resposta traz
o header Retry-After, ele é respeitado.
Resultado parcial na paginação
Com “Buscar Todas Páginas” ligado, a saída ganha dois campos:
{
"data": [],
"totalRegistros": 250,
"totalPaginas": 25,
"paginasBuscadas": 24,
"limitePaginasAtingido": false,
"paginasComErro": [7],
"errosPorPagina": [
{ "pagina": 7, "statusCode": 429, "mensagem": "Limite de requisições", "tentativas": 4 }
],
"completo": false
}
Se uma página falhar em todas as tentativas, o node registra o número em
paginasComErro, o diagnóstico em errosPorPagina, marca completo: false e
continua. errosPorPagina existe porque só o número da página não deixa você
distinguir um 429 (vale tentar mais tarde) de um 404 (não adianta insistir). Você recebe o que deu para
buscar em vez de perder a execução inteira. Use completo em um nó IF para
decidir se reprocessa.
Duas exceções: se a página 1 falhar, o node lança erro — sem ela não há
totalPaginas e não dá para saber o tamanho do que ficou faltando. E se **3
páginas consecutivas* falharem, o node para (circuit break*): o servidor está
fora, insistir só piora.
Limite De Páginas conta páginas tentadas, incluindo as que falharam.
Quanto tempo uma execução pode levar
Os parâmetros se multiplicam: o pior caso de uma execução é
Timeout Por Requisição × Máximo De Tentativas × páginas tentadas. Com os
defaults e Limite De Páginas em 10, isso dá 60s × 4 × 10 = 40 minutos se o
servidor estiver lento a ponto de estourar o timeout em toda tentativa.
Nada limita esse produto — Limite De Páginas limita iterações, não tempo, e
aceita até 1000. Se você aumentar o limite de páginas para buscar mais dados,
aumente na mesma conta o risco de execuções longas. Para workflows com janela de
tempo apertada, baixe Timeout Por Requisição ou Máximo De Tentativas.
O circuit break só ajuda quando as falhas são consecutivas; falhas
intercaladas não o acionam.
Interação com o “Retry On Fail” do n8n
O node já retenta internamente. Se você também ligar o “Retry On Fail” nas
configurações do node, os dois se multiplicam: com maxTries: 3 e
maxTentativas: 4, uma página pode ser pedida até 12 vezes.
Recomendação: deixe o “Retry On Fail” do n8n desligado, ou no máximo em 2.
No modo “Buscar Todas Páginas” ele é especialmente caro, porque reexecuta o node
inteiro e refaz a paginação desde a página 1 — justamente o que a resiliência
interna existe para evitar.
Dropdown de municípios (IBGE)
A lista de municípios usa um perfil próprio, mais curto (3 tentativas, timeout
de 5s), porque é um dropdown do editor com alguém esperando. O n8n não impõe
timeout próprio em loadOptions, então uma espera longa ali chegaria inteira ao
usuário.
O resultado fica em cache por UF enquanto o processo do n8n viver — a lista do
IBGE é estática, e antes disso cada abertura do dropdown refazia a chamada.
Node Dados Abertos
Node declarativo não suporta retry customizado (retryOnFail e maxTries
existem em INode, não em INodeTypeDescription). Ele recebe o que a API
declarativa permite: um timeout explícito e o header Accept.
O timeout é de 120s, mais folgado que os 60s do node PNCP, justamente porque
aqui não há retry para se recuperar dele. Antes desta versão essas chamadas
usavam o default do n8n (300s), então cortar em 60s transformaria uma chamada
lenta que funcionava em falha dura. O objetivo é apenas limitar um travamento.
