Conversor de moedas no n8n com formulário (API Frankfurter) | Trilha Iniciante, Etapa 6

Construção de um conversor de moedas completo

O vídeo apresenta a sexta etapa da trilha iniciante de n8n do canal Orbitacode, focada na construção de um conversor de moedas funcional. A proposta é prática: o usuário digita um valor, seleciona a moeda de origem e a moeda de destino em um formulário web, e o n8n retorna imediatamente o resultado convertido, com a cotação atualizada e formatada no padrão brasileiro. Para obter as taxas de câmbio, o workflow utiliza a API Frankfurter, um serviço gratuito que não éxige cadastro nem chave de acesso, agregando dados de bancos centrais de diversos países, incluindo o Banco Central do Brasil.

O conversor atende a cenários cotidianos reais, como planejar uma viagem internacional, verificar o custo de uma compra no exterior ou calcular o valor a receber de um cliente estrangeiro. A simplicidade da solução não ésconde sua utilidade: em poucos minutos, qualquer pessoa com noções básicas de n8n consegue montar uma ferramenta que antes demandaria consulta manual a sites de câmbio ou planilhas complexas.

Arquitetura do workflow em quatro nós

O fluxo é composto por quatro nós principais, cada um com função claramente definida. O primeiro nó, On form submission, cria o formulário web com os campos necessários: um campo numérico para o valor a ser convertido e dois menus suspensos para selecionar as moedas de origem e destino. As opções incluem USD, EUR, BRL, GBP, ARS e JPY, cobrindo as moedas mais comuns para o público brasileiro. O campo numérico possui validação que éxige preenchimento, evitando erros de execução.

O segundo nó, HTTP Request, consome a API Frankfurter enviando os parâmetros dinamicamente. Em vez de uma URL fixa, o workflow utiliza Send Query Parameters para montar a requisição com base nas escolhas do usuário, passando as variáveis base e quotes extraídas do primeiro nó. Essa abordagem torna o workflow reutilizável para qualquer combinação de moedas, sem necessidade de editar configurações a cada consulta.

O nó Edit Fields e o cálculo da conversão

O terceiro nó introduz uma peça nova para quem acompanha a trilha: o Edit Fields com mapeamento manual. É neste ponto que o cálculo acontece. O nó recebe o valor digitado no formulário e a taxa de câmbio retornada pela API, multiplicando um pelo outro para gerar o total convertido. O uso do Edit Fields com Include Other Input Fields ligado garante que os dados anteriores permaneçam disponíveis para o nó final, evitando o erro comum de perda de informações no fluxo.

O quarto nó, Form Ending, apresenta o resultado ao usuário com uma mensagem personalizada. A expressão monta uma frase clara que inclui o valor original, a cotação aplicada e o valor final convertido, formatado com duas casas decimais e vírgula, como manda o padrão brasileiro. A experiência do usuário final é fluida: preenche o formulário, submete e vê o resultado na mesma página, sem redirecionamentos.

API Frankfurter e fontes de dados confiáveis

A Frankfurter se destaca como escolha didática e funcional para este projeto. Por ser gratuita e dispensar cadastro, elimina fricções iniciais para quem está aprendendo. A API é mantida com dados de bancos centrais, o que confere credibilidade às cotações, ainda que o próprio vídeo faça questão de esclarecer que se trata de uma taxa de referência. Cartões de crédito, casas de câmbio e plataformas de pagamento aplicam tarifas, spread e impostos que alteram o valor final.

O formato da API é simples: a URL base aceita parâmetros como base e quotes, retornando um JSON com as taxas solicitadas. No exemplo do vídeo, a URL https://api.frankfurter.dev/v2/rates?base=USD&quotes=BRL busca a cotação do dólar americano em relação ao real brasileiro. A flexibilidade permite consultar múltiplas moedas de uma só vez, embora o workflow do tutorial utilize uma conversão por requisição, mantendo a lógica enxuta.

Publicação e diferença entre teste e produção

O vídeo dedica atenção especial à diferença entre ambiente de teste e produção. Ao executar o workflow com o editor aberto, o formulário funciona temporariamente, mas a URL de teste só é acessível na máquina local. Para disponibilizar o formulário de forma permanente, é necessário clicar em Publish, o que gera a Production URL, um endereço definitivo que pode ser aberto em qualquer dispositivo, desde que o n8n esteja rodando em um servidor acessível.

A distinção entre rodar o n8n no Docker local e em um servidor remoto é crucial. No computador pessoal, o workflow só funciona enquanto o Docker e o PC estiverem ligados, e o endereço com localhost só abre naquela máquina. Em um servidor, o n8n permanece ativo 24 horas por dia, com endereço público acessível de qualquer lugar. A série promete evoluir para esse cenário em etapas futuras.

Erros comuns e boas práticas de configuração

O tutorial antecipa os erros mais frequentes que iniciantes encontram. O primeiro é o parâmetro quotes escrito sem o s final, que gera a mensagem unknown parameter: quote. O segundo é o uso de nomes de moedas por extenso, como dolar, em vez do código de três letras, resultando em invalid currency. O terceiro é o erro toDateTime can't be used on undefined value, causado pela ausência da opção Include Other Input Fields no nó Edit Fields.

Outra observação importante: quando o usuário seleciona a mesma moeda nos dois campos, a taxa retornada é 1, o que não configura erro. O triângulo amarelo em um nó apenas indica que ele foi alterado e precisa ser reexecutado, não sendo um sinal de problema. Essas orientações evitam frustrações comuns e aceleram a curva de aprendizado.

Aplicações práticas e integração com a trilha

O conversor de moedas representa um marco na trilha iniciante. Após etapas anteriores que abordaram HTTP Request básico, formulário para consulta de CEP, agendamento com Schedule Trigger e uso de Filter, este projeto consolida habilidades essenciais: manipulação de formulários, consumo de APIs com parâmetros dinâmicos e processamento de dados com expressões.

Os próximos passos da trilha apontam para APIs mais sofisticadas e novas trilhas de projetos reais, incluindo vagas e monitoramento. O artigo complementar no site oferece o passo a passo completo e o JSON do workflow pronto para importar, permitindo que o espectador reproduza o projeto sem digitar cada configuração manualmente. O canal mantém o compromisso de ensinar n8n em português, um nó de cada vez.