Sabe aquele número de três dígitos que aparece no comprovante do Pix, da TED, no boleto ou no cadastro de uma conta? É o código do banco (o 341 é o Itaú, o 260 é o Nubank, o 001 é o Banco do Brasil). Neste tutorial você vai montar no n8n um formulário que recebe esse código e mostra de quem é o banco: o nome, o nome completo, o ISPB e a cidade da sede.
Os dados vêm da BrasilAPI, gratuita e sem cadastro, com a lista de bancos do Banco Central. Mas a grande novidade deste tutorial é outra: o tratamento de erro. Se alguém digitar um código que não existe, em vez de o workflow quebrar, a pessoa vê uma mensagem amigável explicando o que fazer.
Para que serve no dia a dia: conferir para qual banco foi um Pix ou uma TED, checar o banco de um boleto antes de pagar, preencher um cadastro que pede o código do banco ou validar a conta de um fornecedor.
O que você vai construir
| Nó | O que faz | Comparando com o dia a dia |
|---|---|---|
| 1. On form submission | Mostra o formulário e recebe o código. | Você lendo o número no comprovante. |
| 2. Buscar banco (HTTP Request) | Pergunta à BrasilAPI de quem é o código. Configurado para continuar pela saída de erro quando falhar. | Ligar para a central e perguntar. |
| 3. Mostrar banco (Form Ending, saída Success) | Mostra os dados do banco. | A atendente lendo a ficha. |
| 4. Banco não encontrado (Form Ending, saída Error) | Mostra uma mensagem amigável. | “Esse número não existe, confira e ligue de novo.” |
Pré-requisitos
- Um n8n funcionando. Se ainda não tem, siga antes o tutorial n8n do zero com Docker.
- Acesso à internet a partir do n8n.
- Nenhuma conta ou chave: a BrasilAPI é aberta.
Versão usada: n8n 2.40. Os nomes de botões e campos aparecem em inglês, como na interface. A BrasilAPI é a mesma do tutorial dos feriados, e o formulário segue a ideia da consulta de CEP e da Tabela FIPE.
A BrasilAPI de bancos em 2 minutos
A BrasilAPI é um projeto aberto que reúne dados públicos brasileiros (CEP, feriados, CNPJ, bancos…) num só lugar, em JSON, sem cadastro. A rota de bancos usa a lista de participantes do sistema de pagamentos publicada pelo Banco Central. No fim do endereço vai o código:
https://brasilapi.com.br/api/banks/v1/341{"ispb":"60701190","name":"ITAÚ UNIBANCO S.A.","code":341,"fullName":"ITAÚ UNIBANCO S.A.","localizacao_sede":"Praça Alfredo Egydio de Souza Aranha, 100, Torre Itaúsa, São Paulo-SP", …}| Campo | Significado |
|---|---|
code | O código do banco (o número do comprovante). Atenção: vem como número, então o 001 chega como 1. |
name | O nome curto, como aparece em extratos. |
fullName | A razão social completa. |
ispb | O ISPB, a “identidade” de oito dígitos do banco no Banco Central (usada no Pix). |
localizacao_sede | O endereço da sede. |
E quando o código não existe? A API responde com status 404 (não encontrado) e esta mensagem:
https://brasilapi.com.br/api/banks/v1/999
{"message":"Código bancário não encontrado","type":"BANK_CODE_NOT_FOUND","name":"NotFoundError"}Para o n8n, um 404 é um erro: por padrão, o nó fica vermelho e o workflow para. É exatamente esse caso que vamos tratar.
Montando o workflow, nó por nó
No n8n, clique em Create workflow e dê o nome Banco pelo código.
Nó 1: o formulário (On form submission)
Clique no + do canvas, procure por Form e escolha o gatilho On form submission. Preencha:
| Campo | Valor |
|---|---|
| Form Title | Banco pelo código |
| Form Description | Digite o código do banco (3 dígitos), como aparece no comprovante. |
| Form Element | Field Name Codigo · Element Type Text · Placeholder 341 · Required Field ligado |
Dois detalhes: o nome Codigo vai sem acento, para a expressão ficar simples; e o tipo é Text, não Number, porque há códigos com zeros à esquerda, como o 001. (A API aceita os dois jeitos, 001 e 1.)
Clique em Execute step, digite 341 e envie: o OUTPUT mostra Codigo: 341.
Nó 2: buscar o banco (HTTP Request)
Adicione um HTTP Request e renomeie para Buscar banco. Method GET. Na URL (Expression), cole o endereço até a última barra e arraste o campo Codigo do INPUT:
https://brasilapi.com.br/api/banks/v1/{{ $json.Codigo }}Clique em Execute step: chegam ispb, name, code, fullName e localizacao_sede.
A novidade: On Error › Continue (using error output)
Ainda no Buscar banco, abra a aba Settings (ao lado de Parameters) e procure On Error, que define o que o nó faz quando dá erro. São três opções:
| Opção | O que acontece no erro |
|---|---|
| Stop Workflow (padrão) | O nó fica vermelho e o workflow para. No formulário, aparece “Problem submitting response”. |
| Continue | O workflow segue pela saída normal, como se tivesse dado certo, levando os dados do erro no lugar da resposta. |
| Continue (using error output) | O nó ganha uma segunda saída, Error. Deu certo, segue pela Success; deu erro, segue pela Error. |
Escolha Continue (using error output). Repare que o painel de saída passa a ter duas abas, Success Branch e Error Branch, e que, no canvas, o nó ganha duas bolinhas de saída.
É como ter um plano B na vida real: se o primeiro caminho estiver fechado, você já sabe para onde ir. Na prática, isso é o que separa uma automação de teste de uma automação que outras pessoas podem usar.
Nó 3: banco encontrado (Form Ending na saída Success)
Puxe a saída Success, adicione o nó Form com a operação Form Ending e renomeie para Mostrar banco. Em Completion Title, Banco encontrado; em Completion Message (Expression):
{{ String($json.code).padStart(3, '0') }} · {{ $json.name }}
Nome completo: {{ $json.fullName }}
ISPB: {{ $json.ispb }}
Sede: {{ $json.localizacao_sede }}O String($json.code).padStart(3, '0') resolve o detalhe do código numérico: String(…) transforma o número em texto, e padStart(3, '0') completa com zeros à esquerda até ter três dígitos. Assim, o 1 volta a ser 001, como no comprovante.
Nó 4: a mensagem amigável (Form Ending na saída Error)
Agora puxe a saída Error e adicione outro Form Ending, chamado Banco não encontrado. Título Banco não encontrado e, em Expression:
Não achamos nenhum banco com o código {{ $('On form submission').item.json.Codigo }}.
Confira os números no comprovante (ex.: 001 Banco do Brasil, 341 Itaú, 260 Nubank) e tente de novo.Uma boa mensagem de erro diz o que aconteceu e o que fazer. Para repetir o código digitado, arraste o Codigo do bloco do formulário. Curiosidade: na saída Error, o item mantém os campos que entraram no nó (inclusive o Codigo) e ganha um campo error com a mensagem da API; se quiser, dá para mostrá-la com {{ $json.error.message }}.
Testando os dois caminhos
Feche o nó e clique em Execute workflow. Teste os dois lados:
| Código digitado | Caminho | Resultado no teste (07/10/2026) |
|---|---|---|
| 341 | Success | 341 · ITAÚ UNIBANCO S.A. |
| 260 | Success | 260 · NU PAGAMENTOS – IP |
| 001 | Success | 001 · BCO DO BRASIL S.A. (com os zeros, graças ao padStart) |
| 999 | Error | Banco não encontrado (mensagem amigável) |
| abc | Error | Banco não encontrado (letras também caem no caminho de erro) |
No canvas, a seta verde mostra por onde cada execução passou: pela saída Success ou pela Error. O Buscar banco continua verde mesmo quando a API responde 404, porque o erro foi tratado.
Erros comuns (testados)
Todos foram reproduzidos no n8n de teste, com o código 999.
| O que aparece | Causa | Como resolver |
|---|---|---|
| Formulário: “Problem submitting response”. Buscar banco vermelho: “The resource you are requesting could not be found” / “Código bancário não encontrado” | O On Error ficou no padrão, Stop Workflow. | Settings › On Error › Continue (using error output), e ligue um Form Ending na saída Error. |
| Página “Banco encontrado” vazia, com “undefined ·” e campos em branco | Foi escolhido só Continue. O erro segue pela saída normal, e o Mostrar banco tenta ler name e fullName que não existem. | Troque por Continue (using error output). |
| Qualquer código mostra sempre “001 · BCO DO BRASIL S.A.” | O campo do formulário foi renomeado (no teste, para “Código do banco”) e a URL continuou com $json.Codigo, que ficou vazio. O endereço termina em /v1/, a API devolve a lista de todos os bancos, e o formulário mostra o primeiro. | Depois de renomear um campo, arraste-o de novo para a URL (ou corrija o nome na expressão). |
Publicando: o endereço definitivo do formulário
Durante os testes, o formulário usa a Test URL, que só funciona com o editor aberto e depois de clicar em Execute workflow. Para deixar a consulta sempre disponível, clique em Publish e confirme.
Depois, abra o nó do formulário e clique na aba Production URL: esse é o endereço definitivo.
No computador ou num servidor?
| No seu computador (Docker) | Num servidor | |
|---|---|---|
| Para que serve | Teste e aprendizado | Produção |
| Quando funciona | Só com o computador e o Docker ligados | Sempre: é uma máquina na internet ligada 24 horas |
| Quem abre o formulário | Só você, no próprio computador (endereço com localhost) | Qualquer pessoa com o link, até pelo celular |
Atenção: publicar no n8n do seu computador não é o mesmo que colocar em produção. O endereço com localhost não abre no celular nem em outro computador. Levar o n8n para um servidor é um passo que a série vai dar mais adiante, com calma.
JSON do workflow para importar
Se preferir, importe o workflow pronto. Baixe o arquivo abaixo ou copie o JSON. No n8n, crie um workflow novo e abra o menu … (três pontinhos) › Import › From file, ou cole o JSON no canvas com Ctrl+V. O workflow não usa credenciais, e o On Error já vem configurado.
O download é um .zip com o banco-pelo-codigo-n8n.json dentro. Depois de importar, clique em Publish para ganhar a sua Production URL.
{
"name": "Banco pelo código",
"nodes": [
{
"parameters": {
"formTitle": "Banco pelo código",
"formDescription": "Digite o código do banco (3 dígitos), como aparece no comprovante.",
"formFields": {
"values": [
{
"fieldLabel": "Codigo",
"placeholder": "341",
"requiredField": true
}
]
},
"options": {}
},
"id": "8b4c0000-1111-4d08-9b08-000000000001",
"name": "On form submission",
"type": "n8n-nodes-base.formTrigger",
"typeVersion": 2.6,
"position": [
0,
0
],
"webhookId": "8b4c0000-aaaa-4d08-9b08-0000000000f1"
},
{
"parameters": {
"url": "=https://brasilapi.com.br/api/banks/v1/{{ $json.Codigo }}",
"options": {}
},
"id": "8b4c0000-2222-4d08-9b08-000000000002",
"name": "Buscar banco",
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.5,
"position": [
260,
0
],
"onError": "continueErrorOutput"
},
{
"parameters": {
"operation": "completion",
"completionTitle": "Banco encontrado",
"completionMessage": "={{ String($json.code).padStart(3, '0') }} · {{ $json.name }}\nNome completo: {{ $json.fullName }}\nISPB: {{ $json.ispb }}\nSede: {{ $json.localizacao_sede }}",
"options": {}
},
"id": "8b4c0000-3333-4d08-9b08-000000000003",
"name": "Mostrar banco",
"type": "n8n-nodes-base.form",
"typeVersion": 2.5,
"position": [
540,
-100
],
"webhookId": "8b4c0000-bbbb-4d08-9b08-0000000000f2"
},
{
"parameters": {
"operation": "completion",
"completionTitle": "Banco não encontrado",
"completionMessage": "=Não achamos nenhum banco com o código {{ $('On form submission').item.json.Codigo }}.\nConfira os números no comprovante (ex.: 001 Banco do Brasil, 341 Itaú, 260 Nubank) e tente de novo.",
"options": {}
},
"id": "8b4c0000-4444-4d08-9b08-000000000004",
"name": "Banco não encontrado",
"type": "n8n-nodes-base.form",
"typeVersion": 2.5,
"position": [
540,
120
],
"webhookId": "8b4c0000-cccc-4d08-9b08-0000000000f3"
}
],
"connections": {
"On form submission": {
"main": [
[
{
"node": "Buscar banco",
"type": "main",
"index": 0
}
]
]
},
"Buscar banco": {
"main": [
[
{
"node": "Mostrar banco",
"type": "main",
"index": 0
}
],
[
{
"node": "Banco não encontrado",
"type": "main",
"index": 0
}
]
]
}
},
"pinData": {},
"settings": {
"executionOrder": "v1",
"timezone": "America/Sao_Paulo"
},
"meta": {
"templateCredsSetupCompleted": false
}
}Para ir além
- Tratar erro nos outros tutoriais: no workflow da Tabela FIPE, ligue o On Error no Buscar anos e mostre “código FIPE não encontrado”. No CEP, faça o mesmo para CEP inexistente.
- Tentar de novo antes de desistir: nas mesmas Settings, Retry On Fail repete a chamada algumas vezes. Bom para APIs instáveis (não adianta para código inexistente).
- Avisar você quando der erro: em vez de (ou além de) mostrar a mensagem, ligue a saída Error num nó de notificação, como o ntfy do tutorial do lembrete.
- Error Workflow: o n8n também permite um workflow inteiro só para erros de outros workflows, assunto para a trilha de Monitoramento.
Recapitulando
- Para o n8n, uma resposta 404 da API é um erro, e o padrão é parar o workflow.
- Em Settings › On Error, Continue (using error output) cria a saída Error; o nó passa a ter dois caminhos, Success e Error.
- Continue (sem error output) segue pela saída normal com dados vazios: evite.
- Cada saída leva ao seu Form Ending: uma página para o sucesso e uma mensagem amigável para o erro.
String($json.code).padStart(3, '0')mantém os zeros à esquerda do código.- Depois do Publish, a Production URL é o endereço definitivo do formulário.
Começamos pelo mais simples e estamos evoluindo juntos, um passo de cada vez. Tratar erros é o que separa uma automação de teste de uma automação de verdade, e vai aparecer em tudo daqui para a frente. E vêm aí as novas trilhas do site: Projetos reais, montados a partir de vagas de emprego, e Monitoramento, para deixar automações no ar 24 horas.
Fontes
- BrasilAPI, documentação (rota Banks: /api/banks/v1 e /api/banks/v1/{code}): https://brasilapi.com.br/docs
- BrasilAPI, código-fonte do projeto: https://github.com/BrasilAPI/BrasilAPI
- Banco Central do Brasil, participantes do STR (códigos e ISPB): https://www.bcb.gov.br/estabilidadefinanceira/participantesstr
- n8n Docs: configurações do nó (Settings, On Error, Retry On Fail): https://docs.n8n.io/build/understand-workflows/workflow-components/work-with-nodes
- n8n Docs: tratamento de erros: https://docs.n8n.io/build/flow-logic/handle-errors-gracefully
- n8n Docs: HTTP Request node: https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/
- n8n Docs: n8n Form node (Form Ending): https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.form/
- MDN: String.prototype.padStart(): https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/String/padStart
- Testes próprios no n8n 2.40 local, em 07/10/2026.
Próximo degrau: Projetos reais
Partimos da descrição de vagas reais que pedem n8n e transformamos cada requisito num workflow pronto, explicado nó a nó e campo a campo, no mesmo estilo dos tutoriais.
