Principal Construindo Fluxos Como criar um fluxo no Fluxo Controlado com API externa

Como criar um fluxo no Fluxo Controlado com API externa

Última atualização em Jun 24, 2026

Quando usar

  • Você precisa conectar o Fluxo Controlado a uma API externa (status de pedido, consulta de CEP, validação de CPF etc.)
  • Você quer aprender o fluxo completo — input do cliente → request HTTP → mapeamento da resposta → resposta formatada
  • Você precisa lidar com entradas inválidas ou retornos vazios da API

Pré-requisitos

  • Workspace do Fluxo Controlado criado
  • URL e método (GET/POST) da API externa que será consultada
  • (Se aplicável) Headers de autenticação prontos (token, API key)

Sobre este artigo

Este guia ensina, passo a passo, como construir um Fluxo Controlado que recebe uma entrada do usuário, faz uma requisição HTTP, extrai os dados retornados, retorna uma resposta formatada para a ClaudIA — ou direciona para N2 quando algo não dá certo.

Passo a passo

Etapa 1 — Criar um novo fluxo no Fluxo Controlado

  1. Acesse o Fluxo Controlado e clique em Criar um Typebot

  2. Comece do zero (Blank bot)

Etapa 2 — Definir o ponto de partida (input do usuário)

  1. Crie um bloco de input de texto

  2. Salve a entrada do usuário (ex: CEP) numa variável (ex: cep)

Etapa 3 — Configurar a chamada de API

  1. Adicione um bloco do tipo HTTP Request

  2. No campo URL, cole o endpoint da API (ex: https://viacep.com.br/ws/{{cep}}/json)

  3. Certifique-se de que a variável esteja entre chaves duplas: {{cep}}

  4. Método: GET (ou POST conforme a API)

Etapa 4 — Testar o request

  1. Clique em Test Request

  2. Adicione um valor real de teste (ex: 01025-020)

  3. Se o teste falhar, verifique se o link começa com https://

Etapa 5 — Mapear os campos de resposta

Depois que o request funcionar, extraia os dados relevantes do JSON retornado em variáveis individuais (ex: endereco, bairro, cidade, uf, ddd).

Etapa 6 — Montar a resposta formatada

Crie um bloco de texto com a resposta para o cliente, usando as variáveis extraídas:

"O CEP {{cep}} corresponde à rua {{endereco}}, no bairro {{bairro}}, cidade de {{cidade}}/{{uf}}, DDD {{ddd}}."

Etapa 7 — Lidar com entradas inválidas (CEP que não existe)

  1. Use um bloco Condition

  2. Verifique se a variável endereco existe:

    • Se sim, siga com a resposta

    • Se não, envie "Não encontramos esse CEP" e retorne à ClaudIA ou redirecione para N2

Etapa 8 — Devolver para a ClaudIA

  • No final do fluxo, use o bloco Retornar para a Cloud

  • Se o dado foi encontrado: retorne uma resposta amigável

  • Se não: envie texto sinalizando que a ClaudIA deve escalar para N2

    "Não encontrei o status. Por favor, transfira."

Etapa 9 — Publicar e testar com tickets reais

  1. Clique em Publicar no topo da tela

  2. O fluxo estará disponível para testes reais com tickets na IDS

Etapa 10 — Tratar entradas com formatação incorreta

Se o usuário digitar o CEP com traços, espaços ou pontos (ex: 01.025-020), use blocos intermediários para sanitizar a entrada (remover caracteres especiais).

Dica: use blocos de transformação de texto ou scripts JavaScript no Fluxo Controlado para sanitização customizada.

Conclusão

Com esse fluxo, você:

  • Automatiza buscas externas via API

  • Personaliza a resposta para o cliente

  • Escala para humano apenas quando necessário

  • Replica o modelo para consultas de status de pedido, rastreio, CPF etc.

Observações