Ferramentas do Darwin: Requisições HTTP

A ferramenta de Requisição HTTP (HTTP Request) foi projetada para realizar integrações de API personalizadas. Sua configuração baseia-se na documentação da API do serviço de terceiros e requer conhecimentos básicos sobre APIs REST, semelhante à criação de uma requisição em ferramentas como o Postman.

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

Importante: Uma conexão de Requisição HTTP padrão não configura a autenticação automaticamente. Você deve adicionar o cabeçalho de autorização, a chave de API (API key), o token ou outras credenciais necessárias de acordo com a documentação do serviço de terceiros. Usar um Content-Type, um nome de parâmetro ou um formato de valor incorreto pode fazer com que o serviço rejeite a requisição.

Cada API requer uma configuração individual.

Em termos simples, é um pedido enviado diretamente do Darwin para uma aplicação externa, solicitando que uma ação específica seja executada nesse sistema.

Uma vez 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 que tenham sido solicitados.

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

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

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

Esse roteamento é feito através da URL (endpoint), que forneceremos ao configurar a etapa no Darwin.

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

Ao configurar esta etapa no Darwin, você verá três seções principais onde é possível enviar ou receber dados:

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

Na configuração da requisição HTTP, preste atenção ao campo Formato de maiúsculas e minúsculas do cabeçalho (Header case format). Algumas APIs diferenciam maiúsculas de minúsculas nos nomes dos cabeçalhos. Essa configuração permite definir como as chaves serão enviadas na requisição.

As opções disponíveis incluem:

Você deve escolher o formato que corresponda aos requisitos especificados na documentação da API da aplicação externa. Se o formato não corresponder, a requisição poderá falhar devido a erros de validação ou autorização.

Esta seção geralmente é usada 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, este é o local onde você inclui campos como nome, e-mail ou número de telefone.

Aqui você configura quais informações devem ser retornadas como resposta à sua requisição.

Por exemplo, você pode configurar para que retorne o status da requisição (se foi bem-sucedida ou se ocorreu um erro), ou qualquer dado adicional fornecido pela aplicação externa. No caso de uma requisição GET, você pode enviar o ID de um usuário do CRM e configurar a resposta para que retorne detalhes adicionais sobre esse usuário, como seu nome ou endereço.

Para configurar uma requisição HTTP corretamente, você precisa de detalhes técnicos específicos, como a URL do endpoint, os cabeçalhos necessários, os parâmetros e o método adequado. 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 a 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. Essa documentação geralmente é organizada por tipo de ação (criar, atualizar, recuperar), mostrando os endpoints disponíveis, os parâmetros obrigatórios e os métodos de autenticação.

Vamos usar como exemplo a API de um CRM chamado Perfex, supondo que o objetivo seja criar um novo registro (assinatura):

Ao localizar esta ação na documentação, você verá o método que deve usar.

Em seguida, você verá a URL.

Por fim, os campos (parâmetros) que devem ser enviados.

Por exemplo, a documentação pode indicar que o campo authtoken (do tipo texto ou String) é o único que deve ser enviado na seção de Cabeçalhos (Headers). Além disso, ela detalhará quais parâmetros você deve preencher na seção do Corpo (Body) para que o registro seja criado corretamente no CRM.

Atenção: Cada aplicação externa tem sua própria documentação. A maioria pode ser encontrada publicamente na internet; outras exigem contato direto com a equipe de suporte da aplicação. Dúvidas específicas sobre as ações disponíveis ou parâmetros devem ser verificadas diretamente com o suporte técnico da referida plataforma.

A seguir, explicamos como configurar essa requisição na plataforma.

O processo de configuração é semelhante ao de criar uma nova conexão.

Vá até a aba de Aplicativos (Apps) e clique em Adicionar uma conexão (Add a connection).

Para começar, você só precisa preencher a URL e o formato (Content-type), conforme indicado na documentação.

Os campos restantes serão preenchidos dentro da automação.

Você pode adicionar várias requisições HTTP para diferentes aplicativos ou ações. Por isso, é importante configurar um nome interno que facilite sua identificação no futuro.

Após configurar esta etapa, vá para a aba de Automações e abra o fluxo onde você irá inserir sua Requisição HTTP.

No local onde você normalmente adicionaria uma ação, clique para adicionar uma nova etapa e selecione a conexão de Requisição HTTP que você acabou de criar.

Você verá a opção de Enviar Requisição (Send API Request) ou Obter arquivo por URL (Get a File by URL). Selecione Enviar Requisição.

Insira novamente a sua URL no campo correspondente.

Se for uma URL dinâmica, você pode inserir uma parte como valor fixo e preencher o restante com variáveis dinâmicas das etapas anteriores.

Preencha o campo do método. (O campo de protocolo não precisa ser preenchido a menos que a documentação exija explicitamente).

Configure os Cabeçalhos (Headers). Defina o nome exato do campo e seu tipo de dado (por exemplo, String).

Configure os Parâmetros (Body). Selecione os campos que você vai enviar. Se um campo não estiver marcado como obrigatório na documentação, ele é opcional. Atribua os valores correspondentes a cada parâmetro.

Configure a Resposta (Response) para receber a mensagem de sucesso ou o aviso de erro.

Pronto! Basta ativar a automação e você poderá verificar o resultado dessa etapa na aba de histórico da plataforma.

Você também pode usar uma requisição de API para baixar um arquivo. Por exemplo, se em uma etapa da sua automação você receber apenas a URL de um arquivo (mas não o arquivo em si), você pode usar esse método.

O Darwin enviará uma requisição para essa URL e recuperará o arquivo, deixando-o disponível para uso em etapas posteriores (por exemplo, para fazer o upload no Google Drive).

Como configurar:

Identifique a URL correta (endpoint) onde o arquivo está hospedado.

Crie uma nova conexão especificando a URL e o formato.

Na automação, selecione a opção Obter arquivo por URL (Get a File by URL).

Use o método GET e mapeie a URL dinâmica obtida na etapa anterior.

A resposta dessa requisição será o arquivo físico.

Ao procurar por uma ação específica de um aplicativo dentro da sua automação, é possível que você encontre uma opção chamada Requisição de API Personalizada (Custom API Request).

Em resumo, esta ação é uma versão simplificada da Requisição HTTP. Ela acelera o processo de configuração porque não é necessário incluir manualmente os dados obrigatórios do cabeçalho, como chaves de API ou tokens. Como a conexão com o aplicativo já está criada nativamente na plataforma, a autenticação é tratada automaticamente.

Para utilizá-la, o aplicativo deve ter uma conexão configurada previamente na sua conta e a ação de Custom API Request deve estar disponível na sua lista de ações. Você só precisa consultar a documentação da API, encontrar o endpoint desejado e preencher os parâmetros da requisição ou da resposta.