Consultar CEP com formulário no n8n (ViaCEP)

Sabe aquele campo de CEP que, em muitos sites, preenche o endereço sozinho? Neste tutorial você vai construir algo parecido no n8n: um formulário onde a pessoa digita um CEP e, logo depois de enviar, vê uma página com a rua, o bairro, a cidade e o estado. O workflow tem só três nós e usa a ViaCEP, uma API brasileira gratuita que não pede cadastro nem chave.

Além de ser útil no dia a dia (para conferir um endereço antes de mandar uma encomenda, por exemplo), este exemplo ensina três ideias que você vai usar em quase todo workflow: receber dados de uma pessoa, usar esses dados dentro de uma URL com uma expressão e devolver uma resposta na tela.

O que você vai construir

Este é o workflow final no editor do n8n, com os três nós ligados em sequência:

Editor do n8n com o workflow Consultar CEP (ViaCEP): nós On form submission, HTTP Request e Form (Form Ending) ligados em sequência — O workflow final “Consultar CEP (ViaCEP)” no editor do n8n (versão 2.40.7).

n8n Form Trigger (no canvas, “On form submission”): cria o formulário com o campo CEP e dispara o workflow quando alguém envia.
HTTP Request: consulta a ViaCEP com o CEP digitado e recebe o endereço.
n8n Form com a página Form Ending: mostra o endereço encontrado na última tela do formulário.

Versão usada: n8n 2.40.7. Os nomes de botões e campos aparecem em inglês, exatamente como na interface. Em todo o tutorial usamos como exemplo o CEP 01001-000, que é público e corresponde à Praça da Sé, no centro de São Paulo.

Pré-requisitos

Um n8n funcionando no seu computador. Se ainda não tem, siga antes o tutorial n8n do zero com Docker: instale e receba a cotação do dólar no e-mail.
Acesso à internet a partir do n8n, para consultar a ViaCEP.
Nenhuma conta, senha ou chave de API.
Se este é o seu primeiro contato com o nó HTTP Request, vale ler também o tutorial sobre as taxas Selic, CDI e IPCA, que explica esse nó com mais calma.

Montando o workflow, nó por nó

Crie um workflow novo e dê a ele o nome Consultar CEP (ViaCEP). Depois, adicione os três nós abaixo, nesta ordem, sempre pelo botão + que aparece à direita do nó anterior.

Nó 1: n8n Form Trigger (o formulário)

O gatilho deste workflow é um formulário. Clique em Add first step, digite “form” na busca, clique em n8n Form e escolha o gatilho On new n8n Form event. O nó entra no canvas com o nome On form submission. Ele cria uma página web com os campos que você definir e, a cada envio, entrega as respostas para o próximo nó.

Tela do nó On form submission com Form Title Consultar CEP, Form Description, um elemento de texto com Label CEP, placeholder ex.: 01001-000 e Required Field ligado; à direita, a saída JSON com CEP, submittedAt e formMode — Configuração do Form Trigger. À direita (OUTPUT), o que chegou depois de um envio de teste.

Campo	Valor	Por que assim
Authentication	None	Qualquer pessoa com o link pode usar o formulário. Para uma consulta pública de CEP, não precisa de senha.
Form Title	Consultar CEP	Título que aparece no topo da página do formulário.
Form Description	Digite um CEP para ver o endereço correspondente.	Uma frase curta que explica o que a pessoa deve fazer.
Form Elements → Label	CEP	Nome do campo na tela. Ele também vira o nome do dado na saída do nó, e é assim que vamos usá-lo no próximo passo.
Form Elements → Element Type	Text Input	Um campo de texto simples. Usamos texto (e não número) porque o CEP pode começar com zero e ter hífen.
Form Elements → Placeholder	ex.: 01001-000	Texto de exemplo, em cinza, que some quando a pessoa começa a digitar.
Form Elements → Required Field	ligado	Impede o envio com o campo vazio.
Options	(nenhuma)	As opções padrão bastam.

No topo do nó ficam os Form URLs, com duas abas. A Test URL serve para testar enquanto você monta o workflow; a Production URL é o link definitivo, que só funciona depois que o workflow é publicado. Logo abaixo dos campos, o próprio n8n avisa: “On submission, the user will be taken to the next form node”, ou seja, depois do envio a pessoa segue para o próximo nó de formulário, que será a nossa página final.

Para testar só este nó, clique em Execute step. O n8n abre o formulário de teste numa nova aba do navegador. Digite o CEP e clique em Submit:

Formulário de teste Consultar CEP com o aviso This is a test version of your form, o campo CEP preenchido com 01001-000 e o botão Submit — O formulário de teste aberto pelo n8n, com o CEP de exemplo digitado.

Volte ao n8n e veja a saída do nó (o painel OUTPUT do print anterior). Ela traz três campos: CEP, com o valor digitado (01001-000); submittedAt, com a data e a hora do envio; e formMode, que mostra test porque usamos o link de teste. O que interessa para nós é o campo CEP.

Nó 2: HTTP Request (consultar a ViaCEP)

Agora vamos perguntar à ViaCEP qual é o endereço daquele CEP. Clique no + à direita do Form Trigger, adicione um nó HTTP Request e preencha como abaixo. O detalhe novo em relação a uma URL fixa é que o CEP muda a cada envio, então ele entra na URL por meio de uma expressão. Esta é a URL completa:

https://viacep.com.br/ws/{{ $json.CEP }}/json/

Tela do nó HTTP Request com Method GET e a URL com a expressão $json.CEP, cujo resultado é https://viacep.com.br/ws/01001-000/json/; à esquerda, o INPUT com o CEP; à direita, a resposta JSON da ViaCEP com logradouro Praça da Sé — HTTP Request com a URL montada por expressão. À esquerda (INPUT), o CEP vindo do formulário; à direita (OUTPUT), o endereço devolvido pela ViaCEP.

Campo	Valor	Por que assim
Method	GET	Vamos apenas consultar um endereço, sem enviar nem alterar nada.
URL	a URL do bloco acima	É o formato de consulta da ViaCEP: `/ws/`, o CEP e `/json/` para receber a resposta em JSON. A parte entre chaves duplas é trocada pelo CEP digitado.
Authentication	None	A ViaCEP é pública e não pede chave.
Send Query Parameters	desligado	O CEP já vai dentro da própria URL.
Send Headers	desligado	Não são necessários cabeçalhos especiais.
Send Body	desligado	Uma consulta GET não envia corpo.
Options	(nenhuma)	As opções padrão bastam.

Para criar a expressão, clique no campo URL, digite https://viacep.com.br/ws/ e então arraste o campo CEP do painel INPUT, à esquerda, para dentro da URL. O n8n escreve {{ $json.CEP }} sozinho e transforma o campo em modo expressão (repare no ícone fx). Termine digitando /json/. Logo abaixo do campo, o n8n mostra a URL já resolvida: https://viacep.com.br/ws/01001-000/json/. Essa prévia é ótima para conferir se a expressão está certa antes de executar.

A expressão {{ $json.CEP }} quer dizer: “pegue, nos dados que chegaram do nó anterior ($json), o campo chamado CEP”. O nome precisa ser escrito exatamente como aparece no INPUT, com as mesmas letras maiúsculas.

Clique em Execute step e veja a resposta no OUTPUT. Para o CEP de exemplo, a ViaCEP devolveu, entre outros campos, logradouro igual a “Praça da Sé”, complemento igual a “lado ímpar”, bairro igual a “Sé”, localidade igual a “São Paulo” e uf igual a “SP”. A resposta também traz o código ibge do município e o ddd da região. Diferente da BrasilAPI de taxas, aqui a resposta é um único objeto, por isso o n8n mostra 1 item.

Nó 3: n8n Form com Form Ending (a página final)

Falta mostrar o resultado para quem preencheu o formulário. Clique no + à direita do HTTP Request, procure por n8n Form e adicione o nó. No campo Page Type, escolha Form Ending: é a página que encerra o formulário. O nó aparece no canvas com o nome Form e a legenda “Form Ending”. A mensagem final, com as expressões, é esta:

{{ $json.logradouro }}, {{ $json.bairro }}, {{ $json.localidade }}/{{ $json.uf }} (CEP {{ $json.cep }})

Tela do nó Form com Page Type Form Ending, On n8n Form Submission Show Completion Screen, Completion Title Endereço encontrado e Completion Message com expressões; a prévia mostra Praça da Sé, Sé, São Paulo/SP (CEP 01001-000) — O nó Form configurado como Form Ending. Abaixo da mensagem, a prévia já mostra o endereço montado.

Campo	Valor	Por que assim
Page Type	Form Ending	Indica que esta é a última tela do formulário (a outra opção, Next Form Page, criaria mais uma página de perguntas).
On n8n Form Submission	Show Completion Screen	Mostra uma tela de conclusão com título e mensagem. As outras opções redirecionam para um site, mostram um texto ou HTML livre, ou devolvem um arquivo.
Completion Title	Endereço encontrado	Título grande da página final.
Completion Message	o texto do bloco acima	Monta uma frase com os campos da ViaCEP. Cada trecho entre chaves duplas é trocado pelo valor correspondente.
Limit Wait Time	desligado	Não precisamos limitar o tempo de espera entre as páginas do formulário.
Options	(nenhuma)	As opções padrão bastam.

Assim como na URL do Nó 2, você não precisa digitar as expressões: arraste cada campo (logradouro, bairro, localidade, uf e cep) do painel INPUT para dentro da Completion Message e escreva as vírgulas, a barra e o texto “(CEP ” entre eles. Repare na prévia abaixo do campo, no print: “Praça da Sé, Sé, São Paulo/SP (CEP 01001-000)”. É exatamente o que a pessoa vai ver.

Um cuidado: aqui usamos cep em minúsculas, porque é assim que o campo vem da ViaCEP. Já no Nó 2 usamos CEP em maiúsculas, porque é assim que ele vem do formulário. Cada expressão lê os dados do nó imediatamente anterior.

O workflow completo e o teste

Com os três nós prontos, feche o nó e clique em Execute workflow, na parte de baixo do canvas. O n8n abre o formulário de teste numa nova aba e fica esperando. Digite 01001-000 e clique em Submit. Em poucos segundos, a página muda para a tela final:

Página final do formulário com o título Endereço encontrado e a mensagem Praça da Sé, Sé, São Paulo/SP (CEP 01001-000) — Resultado do teste: a página Form Ending mostrando o endereço do CEP 01001-000.

De volta ao editor, os três nós estão com contorno verde e a indicação 1 item em cada ligação:

Workflow executado com os três nós em verde: On form submission, HTTP Request e Form (Form Ending), com 1 item em cada ligação — O workflow completo depois do teste, com os três nós em verde.

Para conferir os dados sem abrir cada nó, clique em Logs, na barra inferior. Selecionando o nó Form, a tabela mostra os campos que passaram por ele, com os valores do CEP de exemplo. O campo unidade aparece como empty porque a ViaCEP o devolveu vazio para esse CEP.

Painel Logs com os três nós executados e a saída do nó Form em tabela: cep 01001-000, logradouro Praça da Sé, complemento lado ímpar, bairro Sé, localidade São Paulo, uf SP — O painel Logs depois do teste: a saída do nó Form em forma de tabela.

Usar o formulário de verdade (Production URL)

O link de teste só funciona enquanto o editor está esperando um envio, logo depois de você clicar em Execute workflow ou Execute step. Para ter um link fixo, que funcione a qualquer hora, clique em Publish, no canto superior direito do editor, e confirme. Depois, abra o Form Trigger, clique na aba Production URL e copie o endereço. As consultas feitas por esse link não aparecem no canvas, e sim na aba Executions, no topo do editor. Lembre que, com o n8n rodando só no seu computador, esse link também só abre no seu computador.

Erros comuns

A página final mostra “, , / (CEP )” sem endereço. Isso acontece quando o CEP tem o formato certo (8 dígitos) mas não existe. Nesse caso, a ViaCEP não dá erro: ela responde normalmente, mas com um único campo, erro, igual a true. Como não há logradouro, bairro nem cidade, as expressões ficam vazias. No teste abaixo, usamos o CEP inexistente 99999-999:

Página final do formulário com o título Endereço encontrado e a mensagem vazia , , / (CEP ), resultado de um CEP inexistente — Erro real com um CEP que não existe: a página final aparece, mas sem endereço.

Para um primeiro workflow, basta saber o motivo. Quando quiser tratar esse caso, adicione um nó If entre o HTTP Request e o Form para verificar se o campo erro existe e mostrar uma mensagem como “CEP não encontrado”.

“Problem submitting response” no formulário e “Bad request – please check your parameters” no HTTP Request. A ViaCEP respondeu com o código 400, que ela usa para CEPs em formato inválido: com menos de 8 dígitos (como 0100100), com espaço no meio ou com letras. Também acontece se a expressão da URL estiver errada, por exemplo {{ $json.cep }} em minúsculas no Nó 2: como o formulário envia CEP, a expressão fica vazia e a URL vira https://viacep.com.br/ws//json/. Confira a prévia abaixo do campo URL.
“Form Trigger isn’t listening yet”. Você abriu a Test URL sem que o editor estivesse esperando um envio. Clique em Execute workflow (ou em Execute step no Form Trigger) e use o formulário que o n8n abre.
“Problem loading form” ao abrir a Production URL. A mensagem completa explica: “This usually occurs if the n8n workflow serving this form is deactivated or no longer exist”. O link de produção só funciona com o workflow publicado. Clique em Publish e tente de novo.
O endereço aparece incompleto. Alguns CEPs, como os de cidades pequenas que têm um CEP único, vêm da ViaCEP sem logradouro ou sem bairro. Não é defeito do workflow: a API simplesmente não tem esse dado para aquele CEP.

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 escolha uma das opções: abra o menu … (três pontinhos) no topo do editor, vá em Import e depois em From file; ou cole o JSON direto no canvas com Ctrl+V.

consultar-cep-viacep.zip Baixar

O download é um arquivo .zip com o consultar-cep-viacep.json dentro. Descompacte antes de importar (ou copie o JSON do bloco abaixo).

{
  "name": "Consultar CEP (ViaCEP)",
  "nodes": [
    {
      "parameters": {
        "formTitle": "Consultar CEP",
        "formDescription": "Digite um CEP para ver o endereço correspondente.",
        "formFields": {
          "values": [
            {
              "fieldLabel": "CEP",
              "placeholder": "ex.: 01001-000",
              "requiredField": true
            }
          ]
        },
        "options": {}
      },
      "id": "8c3f2e51-1111-4d2b-9f02-0c0000000001",
      "name": "On form submission",
      "type": "n8n-nodes-base.formTrigger",
      "typeVersion": 2.6,
      "position": [
        0,
        0
      ],
      "webhookId": "8c3f2e51-aaaa-4d2b-9f02-0c00000000f1"
    },
    {
      "parameters": {
        "url": "=https://viacep.com.br/ws/{{ $json.CEP }}/json/",
        "options": {}
      },
      "id": "8c3f2e51-2222-4d2b-9f02-0c0000000002",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.5,
      "position": [
        260,
        0
      ]
    },
    {
      "parameters": {
        "operation": "completion",
        "completionTitle": "Endereço encontrado",
        "completionMessage": "={{ $json.logradouro }}, {{ $json.bairro }}, {{ $json.localidade }}/{{ $json.uf }} (CEP {{ $json.cep }})",
        "options": {}
      },
      "id": "8c3f2e51-3333-4d2b-9f02-0c0000000003",
      "name": "Form",
      "type": "n8n-nodes-base.form",
      "typeVersion": 2.5,
      "position": [
        520,
        0
      ],
      "webhookId": "8c3f2e51-bbbb-4d2b-9f02-0c00000000f2"
    }
  ],
  "connections": {
    "On form submission": {
      "main": [
        [
          {
            "node": "HTTP Request",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "HTTP Request": {
      "main": [
        [
          {
            "node": "Form",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "pinData": {},
  "settings": {
    "executionOrder": "v1"
  },
  "meta": {
    "templateCredsSetupCompleted": false
  }
}

O workflow não usa credenciais, então funciona logo depois de importado. Os campos webhookId identificam os endereços do formulário dentro do seu n8n; você não precisa mexer neles.

Recapitulando

O n8n Form Trigger cria um formulário e entrega as respostas ao workflow, com um link de teste e outro de produção.
Uma expressão como {{ $json.CEP }} coloca um dado do nó anterior dentro de qualquer campo, inclusive de uma URL.
O HTTP Request consulta a ViaCEP e devolve o endereço em campos separados.
O n8n Form com Form Ending mostra o resultado na tela final para quem preencheu.

Com esse mesmo modelo de três nós (formulário, consulta e resposta), você consegue montar várias outras ferramentas simples, como uma consulta de feriados por ano ou de dados de um banco pelo código. No próximo tutorial, vamos continuar explorando APIs públicas brasileiras com o n8n.