Dados e conexõesGuia

Conexões de API (HTTP)

Uma conexão API (HTTP) guarda as duas coisas que toda chamada a uma API repete: onde ela fica e como fazer login. O passo Requisição HTTP de um flow aponta para a conexão, escreve só o caminho, e a plataforma acrescenta o endereço e a credencial — que fica guardada como variável secreta, nunca dentro do flow.

8 min de leituraAntes: Integrações, O que é um flowAbrir no Waiso

O que você vai aprender

Criar uma conexão API (HTTP) com o login certo
Saber quais variáveis secretas cada login cria
Conectar uma API OAuth2 na própria página de login dela
Chamar a conexão pelo passo Requisição HTTP, ou importar um comando cURL

O que a conexão faz

Sem conexão, um passo Requisição HTTP precisa do endereço completo e de todos os headers em cada passo — e um token digitado num header ficaria salvo no flow em texto aberto. Com uma conexão, o endereço do passo pode ser relativo (/orders/42), o painel lateral mostra Relativo a https://api.example.com, e o worker acrescenta o header (ou o parâmetro de query) de login no momento em que envia a requisição. Os registros da execução nunca contêm a credencial.

O passo Requisição HTTP no topo do flow usa uma conexão salva; os passos abaixo leem a resposta dele.

A conexão fica na página Integrações do projeto, no grupo Serviços, ao lado de bancos, armazenamento e provedores de IA. Uma conexão pode servir quantos passos e flows você quiser; trocar a chave é uma edição só, e cada passo usa o valor novo na próxima execução.

Crie a conexão

Abra o diálogo
Em Integrações, clique em Adicionar integração e escolha API (HTTP) — “Qualquer API REST, com o login dela”.
Dê um nome e defina o endereço base
O Nome (por exemplo api-da-loja) também dá nome às variáveis. O Endereço base precisa começar com http:// ou https://; os passos escrevem caminhos relativos a ele.
Escolha o login
Em Login escolha Nenhum, API key, Bearer token, Basic ou OAuth2, e preencha os campos que aparecem (tabela abaixo).
Confirme as variáveis
Salvar mostra antes Variáveis que essa conexão cria com os nomes exatos. Clique em Confirmar e salvar. Se um nome já existe, o salvamento espera até você renomear a conexão.

Login	O que você preenche	O que cada requisição recebe	Variável secreta
Nenhum	Nada	Nada acrescentado	—
API key	Enviar em Header ou Query, o nome do header ou do parâmetro, a chave	`X-Api-Key: …` por padrão, ou `?api_key=…`	`HTTP_SHOP_API_API_KEY`
Bearer token	Token	`Authorization: Bearer …`	`HTTP_SHOP_API_TOKEN`
Basic	Usuário, Senha	`Authorization: Basic …`	`HTTP_SHOP_API_PASSWORD`
OAuth2	Endereço de autorização, Endereço do token, Client ID, Client secret, Escopos	`Authorization: Bearer …` com um access token renovado	`…_CLIENT_SECRET` + `…_REFRESH_TOKEN`

Os nomes seguem a regra de toda conexão: HTTP_ mais o nome da conexão em maiúsculas, com cada sequência de outros caracteres virando um _, e depois o campo. O usuário do Basic e o client ID do OAuth2 não são segredos, então ficam na própria conexão.

Conecte uma API OAuth2

APIs OAuth2 nunca entregam um token fixo: uma pessoa faz login na própria página da API e permite o acesso. O Waiso guarda o refresh token de longa duração que volta e o transforma em access tokens curtos conforme os passos precisam.

Cadastre o endereço de retorno
Com OAuth2 escolhido, o diálogo mostra um Endereço de retorno com Copiar. Cadastre esse endereço nas configurações do app da API, onde você também obtém o client ID e o secret.
Salve e depois conecte
Preencha os endereços, o client ID, o client secret e os escopos (separados por espaço) e salve. Abra a conexão de novo e clique em Conectar: você faz login na página da API e volta com Conectado.
Conecte de novo quando pedido
Se a API revogar o acesso, os passos falham com oauth_reconnect_required até alguém clicar em Conectar de novo.

Chame pelo flow

No painel lateral do passo Requisição HTTP, escolha a conexão em Conexão (ou Sem conexão para um endereço completo). Depois defina o método e o caminho, adicione linhas de Query e Headers, um Body (Nenhum, JSON, Formulário, Texto ou Arquivo) e como ler a resposta. A saída do passo é { status, headers, body }; os passos seguintes se vinculam aos campos de body. O tópico passos prontos cobre todas as opções, incluindo paginação.

Importe um comando cURL

Importar cURL abre Importar um comando cURL: cole o comando que a documentação da API mostra e o passo recebe o método, o endereço, a query, os headers e o body. Tudo que parece credencial — um header Authorization, um -u usuario:senha — aparece em Segredos encontrados com Guardar como e um nome de variável, para virar uma variável secreta do projeto em vez de texto no flow.

Limites e regras

As requisições saem do processo do worker, nunca do sandbox do seu script. Todo endereço — e cada salto de redirecionamento, até 5 — é conferido: endereços privados, de loopback e link-local são recusados com host_not_allowed, a menos que um administrador tenha liberado esse host.
Uma requisição tem 60 segundos por padrão; uma resposta acima de 50 MB falha com http_response_too_large; uma falha de rede é http_request_failed.
Com Falhar o passo quando a resposta for um erro (4xx/5xx) ligado (o padrão), uma resposta de erro faz o passo falhar com http_status_error.
O header Authorization é descartado quando um redirecionamento sai da origem da API, então uma credencial nunca segue a requisição para outro site.

ExercícioChame uma API pública por uma conexãoAbrir no Waiso

Salvar um endereço base uma vez e chamar um caminho relativo por um passo Requisição HTTP.

Antes de começar

Um projeto onde você possa adicionar integrações e flows

Passos

1Em Integrações, clique em Adicionar integração → API (HTTP).
2Dê o nome placeholder, defina o Endereço base como https://jsonplaceholder.typicode.com, mantenha Login em Nenhum e salve.
3Crie um flow e adicione um passo Requisição HTTP abaixo do Início.
4Escolha placeholder em Conexão, mantenha GET e digite /todos/1 como endereço.
5Clique em Rodar teste e leia a Resposta.

Resultado esperado

Saída esperadaSucessoO status e o body da resposta (headers omitidos aqui)

{
  "status": 200,
  "body": {
    "userId": 1,
    "id": 1,
    "title": "delectus aut autem",
    "completed": false
  }
}

Dica

A linha Relativo a https://jsonplaceholder.typicode.com no painel lateral confirma que o passo está usando a conexão.

Ver solução

O passo junta o endereço base e /todos/1. Um GET só lê, então Rodar teste envia na hora; um POST, PUT, PATCH ou DELETE perguntaria “Isso vai gravar de verdade” antes.

Confira · 2 perguntas

Uma conexão chamada billing usa Bearer token. Como se chama a variável dela?

HTTP_BILLING_TOKEN, uma variável secreta.

Por que um passo apontado para http://10.0.0.5/ falha?

É um endereço privado: a requisição é recusada com host_not_allowed, a menos que um administrador tenha liberado esse host.