Como Usar Requisições HTTP na Albato

As requisições HTTP são uma excelente opção para casos em que você precisa enviar ou receber dados de uma aplicação específica e, no momento em que tenta adicionar uma conexão com esse aplicativo ou uma ação desejada dentro da sua automação, percebe que o que você procura não está disponível nativamente na Albato.

Abaixo, explicaremos em detalhes o que são requisições HTTP e como configurar esse importante recurso passo a passo.

Antes de Começar

A Requisição HTTP foi desenvolvida para integrações personalizadas via API. Sua configuração é baseada na documentação da API do serviço de terceiros e requer um conhecimento básico de APIs REST, semelhante à criação de uma requisição no Postman.

Antes de configurar a etapa, encontre as seguintes informações na documentação da API do serviço:

• a URL do endpoint;
• o método da requisição;
• o método de autenticação e os headers obrigatórios;
• o Content-Type necessário, como application/json ou application/x-www-form-urlencoded;
• os nomes exatos dos parâmetros, valores aceitos e formatos dos dados;
• os campos esperados na resposta.

Importante: uma conexão padrão de Requisição HTTP não configura a autenticação automaticamente. Adicione o header de autorização, chave de API, token ou outras credenciais necessárias de acordo com a documentação da API do serviço de terceiros. Usar o Content-Type, nome de parâmetro ou formato de valor incorreto pode fazer com que o serviço rejeite a requisição.

Cada API requer uma configuração individual. O Suporte do Albato pode explicar os campos e opções disponíveis na etapa de Requisição HTTP. Para obter ajuda na escolha de um endpoint, método de autenticação, parâmetros ou estrutura de resposta, entre em contato com o provedor da API ou com um especialista que trabalhe com esse serviço.

O que é uma Requisição HTTP?

De forma simplificada, trata-se basicamente de uma requisição enviada diretamente do Albato para uma aplicação externa, solicitando que uma ação específica seja realizada do outro lado.

Depois que essa ação é executada, recebemos uma resposta, que pode conter uma confirmação de sucesso, uma mensagem de erro ou até mesmo o retorno de dados adicionais solicitados.

Usando exemplos mais práticos, esse recurso pode ser utilizado para solicitar informações específicas, enviar dados, atualizar registros, entre outros casos de uso.

Imagine que você tenha um novo lead que preencheu um formulário em um aplicativo e deseja criar um contato em um CRM que não possui uma integração nativa com o Albato.

Se você tiver acesso à documentação da API do CRM, poderá usar os detalhes técnicos fornecidos nela para configurar uma requisição HTTP no Albato. Isso permite enviar os dados do lead diretamente para o CRM e automatizar o processo de criação do contato.

Esse é apenas um exemplo. As possibilidades são praticamente ilimitadas e dependem do que a API da aplicação externa permite fazer. A seguir, veremos mais detalhadamente os aspectos técnicos da configuração dessas requisições.

Principais Tipos de Requisições HTTP (Métodos)

Cada requisição HTTP utiliza um método que informa à aplicação externa qual ação você deseja realizar. Os métodos mais utilizados são os seguintes.

GET

Utilizado para obter informações.

• Obter dados de usuários de um CRM específico.
• Listar pedidos concluídos ou consultar produtos em seu e-commerce.

POST

Utilizado para criar novos dados diretamente do Albato no aplicativo externo. Exemplo:

• Criar um lead no CRM.
• Enviar um formulário de compra preenchido.
• Registrar uma venda em uma planilha.

Basicamente, ele é utilizado para enviar dados coletados no Albato para o aplicativo externo desejado, acionando uma ação específica nele.

PUT / PATCH

Utilizados para atualizar dados existentes. Exemplo:

• Atualizar o endereço de e-mail de um cliente.
• Alterar o status de um pedido.

DELETE

Utilizado para excluir dados. Exemplo:

• Excluir um registro duplicado.
• Remover um usuário que deixou de pagar pelo plano da sua plataforma.

O método escolhido depende da ação que você deseja realizar. Ao consultar a documentação da API da aplicação externa, você poderá determinar qual método deve ser utilizado em cada caso específico.

O que é uma URL (Endpoint) Dentro de uma Requisição HTTP?

Toda requisição HTTP será enviada para uma aplicação externa. Dependendo da ação, essa requisição precisará ser direcionada para uma área específica dessa aplicação ou deverá conter dados predefinidos para garantir seu sucesso.

Esse direcionamento é feito por meio da URL (Endpoint), que forneceremos ao configurar a etapa no Albato.

Qual é a Estrutura de uma Requisição HTTP?

Como mencionado anteriormente, toda requisição HTTP deve incluir um Método e uma URL.

Agora vamos analisar os elementos adicionais que podem ser incluídos em uma requisição. Ao configurar essa etapa no Albato, você verá três seções principais nas quais os dados podem ser enviados ou recebidos.

A primeira seção é Headers (Headers da requisição).

Essa parte da requisição é processada primeiro pela aplicação externa. Na maioria dos casos, os headers contêm informações essenciais, como tokens, chaves de API e outros dados de autorização necessários para autenticar a requisição.

Nas configurações da requisição HTTP, preste atenção ao campo de formato Header case. Algumas APIs são sensíveis à diferença entre letras maiúsculas e minúsculas utilizadas nos nomes dos headers. Essa configuração permite definir como as chaves dos headers serão enviadas na requisição.

As opções disponíveis incluem:

• Title Case (por exemplo, X-Api-Key);
• lowercase (por exemplo, x-api-key);
• UPPERCASE (por exemplo, X-API-KEY).

Preserve original (envia os headers exatamente como você os inseriu). Você deve escolher o formato que corresponde aos requisitos especificados na documentação da API da aplicação externa. Se a API esperar um formato específico de header e o uso de maiúsculas e minúsculas não corresponder, a requisição poderá falhar devido a erros de autorização ou validação.

A segunda seção é Request Parameters, também conhecida como Body (corpo da requisição). Essa seção é normalmente utilizada com os métodos POST, PUT ou PATCH.

Aqui você define os parâmetros que serão enviados para a aplicação externa. Por exemplo, ao criar um novo contato, é aqui que você inclui campos como nome, e-mail ou número de telefone.

Por fim, temos a seção Response Parameters. É aqui que você configura quais informações devem ser retornadas como resposta à sua requisição.

Por exemplo, você pode configurar a resposta para retornar o status da requisição, informar se ela foi bem-sucedida, se ocorreu um erro ou quaisquer dados adicionais fornecidos pela aplicação externa.

No caso de uma requisição GET, você pode enviar o ID de um usuário do CRM nos parâmetros da requisição e configurar a resposta para retornar detalhes adicionais sobre esse usuário, como nome, e-mail ou endereço.

Onde Posso Encontrar as Informações Necessárias para Criar uma Requisição HTTP?

Para configurar corretamente uma requisição HTTP, você precisa de detalhes técnicos específicos, como a URL do endpoint, os headers obrigatórios, os parâmetros da requisição e o método apropriado. Todas essas informações são fornecidas na documentação da API da aplicação externa.

Qualquer aplicação que ofereça uma API (ou seja, que permita interação remota com outros sistemas) fornece uma documentação que explica quais ações estão disponíveis, quais dados podem ser enviados ou recuperados e como as requisições devem ser estruturadas.

A documentação da API varia de uma aplicação para outra. No entanto, normalmente ela é organizada em seções de acordo com o tipo de ação (por exemplo, criação, atualização ou recuperação de dados), os endpoints disponíveis, os parâmetros obrigatórios, os métodos de autenticação e outros detalhes de configuração.

Para ilustrar isso, usaremos a documentação da API de um CRM chamado Perfex como exemplo. Vamos supor que o objetivo seja criar um novo registro (assinatura) nesse CRM.

Na documentação da API, ao localizar essa ação, você verá o método que deve ser utilizado.

Em seguida, você verá a URL.

E, por fim, os campos que devem ser enviados.

Observe que, neste caso, apenas o campo chamado authtoken, do tipo String, deve ser enviado na seção Header.

Além disso, você verá quais campos podem ser configurados para que esse novo registro seja criado no CRM, ou seja, os parâmetros que você preencherá na seção Request Parameters (Body) da sua etapa no Albato.

Por fim, você também pode configurar as respostas de acordo com o status da sua requisição.

Aqui, você terá acesso a todas as informações importantes que mencionamos e que precisa ter em mãos antes de criar sua requisição HTTP.

Atenção: cada aplicativo externo possui sua própria documentação. A maioria delas pode ser encontrada publicamente por meio de pesquisas na internet; outras exigem que você entre em contato diretamente com a equipe de suporte do aplicativo externo.

Observe que o Albato não controla quais tipos de ações estão disponíveis em cada aplicativo. Essa é uma configuração externa e depende totalmente da aplicação para a qual a requisição está sendo enviada.

Quaisquer dúvidas específicas sobre a documentação ou sobre as ações disponíveis também devem ser direcionadas diretamente à equipe da aplicação externa.

Configurando a Requisição HTTP no Albato

Agora vamos ver como configurar essa requisição diretamente no Albato.

Criando uma Requisição HTTP

1. O processo de configuração é semelhante ao de criação de uma nova conexão. Primeiro, acesse a aba Apps e clique em Add a connection.

Aqui, você já precisará indicar algumas das informações mencionadas anteriormente.

2. Para começar, preencheremos apenas a URL e o formato (Content-type), conforme mencionado na documentação de exemplo.

Os campos restantes (parâmetros) serão preenchidos dentro da automação.

3. Você pode adicionar várias requisições HTTP, cada uma para uma aplicação específica ou ação desejada. Por isso, é importante configurar um nome interno no Albato que facilite a identificação posteriormente.

4. Depois que essa etapa estiver configurada, acesse a aba Automations e abra a automação na qual você inserirá sua Requisição HTTP.

No local onde normalmente você adicionaria uma etapa de ação que não está disponível no Albato, clique para adicionar uma nova etapa e selecione a conexão de Requisição HTTP que você criou.

Você verá que terá a opção de Send Request ou Get a File by URL.

5. Abordaremos a segunda opção com mais detalhes no final deste artigo. Por enquanto, selecione Send API Request. Você verá os campos e seções que precisam ser preenchidos.

Preencha-os de acordo com as especificações fornecidas na documentação da API.

Neste exemplo, estamos usando a documentação da API do Perfex como referência. No entanto, a mesma lógica se aplica a qualquer aplicação que forneça documentação de API.

6. Insira novamente sua URL no campo correspondente.

Se for uma URL dinâmica, você poderá adicionar parte dela como um valor fixo e preencher os valores dinâmicos provenientes das etapas anteriores, por exemplo.

7. Preencha também o campo do método.

O campo de protocolo não precisa ser preenchido, a menos que a documentação da API mencione explicitamente esse requisito.

8. Em seguida, vamos preencher os campos de Header.

De acordo com a documentação da API, este é o único campo obrigatório.

Então, ficará assim.

Observe que, além de especificarmos o nome exato do campo, também definimos seu tipo (neste caso, String).

9. Agora vamos configurar os campos que serão enviados para essa aplicação. Selecionaremos alguns deles.

Se um campo não estiver marcado como obrigatório na documentação da API, você poderá escolher se deseja ou não enviá-lo. Isso depende das informações que você coletou anteriormente na sua automação e deseja enviar para a aplicação externa.

Como exemplo, preencheremos estes campos.

10. Em seguida, no campo à direita, coloque os valores que deseja enviar para esses parâmetros.

11. Por fim, vamos preencher o campo Response.

Aqui, vamos configurá-lo para receber uma mensagem de sucesso ou um aviso de erro.

Dessa forma, sua requisição de API estará criada corretamente, de maneira simples, tornando-se uma ferramenta útil para inúmeras situações.

12. Basta ativar a automação e você poderá verificar o resultado dessa etapa, assim como qualquer outra ação da sua automação, diretamente na aba de histórico da plataforma.

Requisições de API para Acessar Arquivos (Get file by URL)

Como mencionado anteriormente, você também pode utilizar uma requisição de API para recuperar um arquivo. Por exemplo, em uma das etapas ou gatilhos da sua automação, você pode receber apenas a URL de um arquivo, e não o arquivo em si.

Nesse caso, você pode utilizar essa etapa para enviar uma requisição para essa URL. O Albato recuperará o arquivo, disponibilizando-o para uso nas etapas seguintes que suportam entradas de arquivos.

1. Para configurar esse tipo de automação, primeiro identifique a URL correta da requisição (Endpoint) na qual o arquivo pode ser acessado.

2. O processo de configuração é o mesmo descrito anteriormente: crie uma nova conexão, especifique a URL e o formato necessário e, em seguida, selecione essa conexão dentro da sua automação.

3. Em seguida, utilize no campo de URL o valor coletado anteriormente que contém a URL do arquivo, bem como o método definido como GET.

A resposta dessa requisição HTTP será o próprio arquivo, que poderá ser utilizado em diversas ações que esperam esse formato, como a ação Adicionar arquivo no Google Drive.

Custom API Request x HTTP Request

Em algum momento, ao adicionar uma ação de uma aplicação desejada à sua automação, você pode não encontrar a ação exata que deseja.

No entanto, pode encontrar uma ação chamada Custom API Request.

Em resumo, essa ação é uma versão simplificada de uma Requisição HTTP. Ela acelera o processo de configuração porque você não precisa incluir manualmente dados obrigatórios de header, como chaves de API ou tokens. Como a conexão da aplicação já foi criada nativamente no Albato, a autenticação é tratada automaticamente.

Se esse recurso estiver disponível para a aplicação que você deseja utilizar, abra a documentação da API do aplicativo, encontre o endpoint desejado e preencha os parâmetros de requisição ou resposta necessários conforme descrito anteriormente.

Para utilizar o Custom API Request, a aplicação já deve ter uma conexão configurada no Albato. Essa conexão deve estar configurada corretamente e a ação Custom API Request deve estar disponível na lista de ações da aplicação. Se o aplicativo não estiver listado no Albato ou a opção Custom API Request não estiver disponível, será necessário utilizar a Requisição HTTP padrão.

Como Trabalhar com Campos de Array

Em algumas aplicações externas, a requisição HTTP esperada pode exigir o envio de campos do tipo Array. Esses arrays podem ter diferentes formatos, como:

• Boolean Array
• Date and Time Array
• Decimal Array
• Phone Array
• Int Array
• String Array
• Object Array

Como vimos anteriormente, o formato exato do campo será descrito na documentação da API.

Vamos imaginar que você precise enviar um Object Array.

1. Ao adicionar o campo à sua requisição, selecione este formato:

2. Em seguida, você precisará fornecer o nome do array, conforme descrito na documentação da API.

Vamos supor que temos um array de objetos contendo informações de contato, estruturado da seguinte forma:

{
  "contacts": [
    {
      "id":
      "name":
      "age":
    }
  ]
}

Nesse caso, o nome do array é contacts, então vamos inseri-lo aqui:

3. Em seguida, crie um campo dentro do array para cada valor contido no objeto.

Quando terminar, a configuração ficará assim:

Como você pode ver, agora configuramos corretamente a requisição para enviar esse tipo de dado.

Você pode aplicar a mesma lógica a todos os outros formatos de array.

O comportamento geral e o processo de configuração são os mesmos dos demais tipos de campos.

Conclusão

Este artigo explicou em detalhes como criar e configurar ações de Requisição HTTP no Albato.

Se o seu objetivo é receber dados de uma aplicação externa diretamente em uma etapa de gatilho, você pode considerar o uso do recurso Incoming Webhook.

Você pode encontrar um guia completo sobre esse recurso aqui.