API REST

Criando um conector

Para criar um conector de API REST, siga os passos abaixo:

  1. Acesse a tela Connector Manager

  2. Clique em + NEW CONNECTOR

  3. Selecione o cartão do conector REST API

  4. Importe um arquivo com a especificação Open API 3.0.0

    • Na janela modal que se abrirá, clique em SELECT FILE para localizar o arquivo.

    • Após localizar o arquivo, clique em IMPORT.

    • Ao importar o arquivo, o sistema verificará a presença de erros de estrutura e a conformidade com a versão suportada. Após a validação, a tela de configuração do conector será aberta, com todos os campos automaticamente preenchidos com os dados importados.

      Somente é permitido importar arquivos com as extensões .json, .yaml e .yml.

  5. Edite os campos com informações do conector (opcional)

    • Name: nome do conector.

    • Version: versão do conector.

    • Description: descrição do conector.

    • Add icon: adicione um ícone para representar o conector.

  6. Selecione as rotas

    • Se preferir, clique em Select All para selecionar todas as rotas disponíveis.

      Você pode visualizar a requisição (request) e a resposta (response) de cada rota selecionada no lado direita da lista de rotas.

  7. Clique em CREATE

create rest api connector

Não é possível editar um conector de API REST. Se você desejar fazer alterações, como selecionar uma nova rota, será necessário criar um novo conector. Para outras modificações, atualize a especificação no arquivo de importação.

Configurando um conector

Para utilizar o conector que você criou no Connector Manager em uma integração, você deverá configurá-lo na tela Flow. Para isso, siga os passos abaixo:

Adicione o conector ao canvas

  1. Acesse a tela Integration Flows

  2. Selecione o fluxo de integração desejado

    • Se o fluxo de integração que vai utilizar o conector já existe, selecione-o e abra a tela Flow.

    • Se desejar usar o conector em um novo fluxo, clique em + NEW FLOW.

      Consulte nosso tutorial sobre como criar seu primeiro fluxo de integração.

  3. Selecione o conector no menu de edição no canvas

    • Clique no ícone icone hub com sinal de mais, no menu de edição à esquerda.

    • Busque e selecione o conector que você cadastrou. Você pode usar a barra de pesquisa search steps icon para encontrá-lo.

    • Selecione o conector no canvas e clique no ícone de edição icone lapis para abrir o formulário de configuração.

    • Certifique-se de que o conector está conectado ao step anterior e ao step posterior a ele no canvas.

Cada conector permite apenas uma conexão de entrada e uma conexão de saída.

Ao selecionar o conector no canvas, você poderá:

  • Editá-lo icone lapis.

  • Copiá-lo ícone de cópia. Se o formulário do conector já estiver configurado, as configurações serão copiadas também.

  • Excluí-lo ícone da lixeira.

Preencha o formulário de edição

connector form

  • Name: nome do conector. Carrega automaticamente o nome que você usou durante a criação do conector, mas pode ser editado.

  • Connector: campo bloqueado que mostra o nome do conector no momento da criação do mesmo.

  • Route: selecione a rota (exemplo: GET/customer) que o conector utilizará. Se houver muitas, você pode digitar o método HTTP ou o path para filtrar os resultados.

  • URL: insira a URL que fará a requisição. Se houver cadastrado a URL nas variáveis de ambiente, pode clicar no ícone à direita e selecioná-la.

  • Request Timeout: insira o tempo limite da requisição em milissegundos. Por padrão, o valor será de 3000 milissegundos e o valor máximo de 300000 milissegundos.

    Ao clicar no ícone de Properties icone de lista à direita dos campos URL e Request Timeout, você pode:

    • Filtrar e exibir variáveis de ambiente e o payload de steps anteriores (se os steps estiverem conectados) para uso na configuração do formulário.

    • Criar expressões usando o Expression Builder.

  • Security: habilita automaticamente o tipo de segurança já configurado em Authorizations. Se houver mais de um tipo de segurança cadastrado, o campo mostrará uma lista com as opções. Caso o conector não tenha nenhum tipo de segurança habilitado, por padrão o campo exibirá a opção No Auth.

  • Ignore Errors: ignora erros durante a execução do fluxo. Por padrão, este botão é desabilitado e você pode habilitá-lo.
    Confira detalhes sobre o seu funcionamento na tabela abaixo:

    Habilitado switch

    Desabilitado switch off

    A execução do fluxo continua, mesmo que haja erros no processo.

    A execução será interrompida imediatamente.

    Os logs apresentam o step com erro.

    Os logs mostram a execução até o step com erro.

    Steps seguintes serão executados.

    Nenhum step seguinte será executado.

Configure as abas: Body, Header, Query e Path

Body

Para configurar o corpo da requisição, clique em + CREATE DATA MAPPING.

Há duas formas de configuração:

body connector
Data Mapping

O mapeamento de dados é fundamental para a integração de diferentes sistemas e aplicações, permitindo a troca fluida de informações entre eles. Ele transforma dados de um formato para outro, ajustando campos e tipos conforme necessário.

Utilizando as colunas "FROM" e "TO", você pode mapear seus dados manualmente:

  • FROM (DE): indica a origem dos dados, que inclui os steps anteriores e as variáveis de ambiente registradas.

  • TO (PARA): representa o destino dos dados, que corresponde ao corpo da requisição do conector.

data mapping empty

Mapeamento de dados de 1 para 1

  1. Selecione um atributo na coluna "FROM", à esquerda.

  2. Selecione um atributo da coluna "TO", à direita.

  3. Clique em ADD MAPPING.

  4. Clique em CONFIRM.

  5. Você pode repetir os passos acima quantas vezes for necessário.

Uma vez salvo, será possível visualizar o mapeamento de dados na aba Body e a opção de edição estará habilitada.

Veja uma demonstração no GIF abaixo:

data mapping 1 to 1

Mapeamento de dados de 2 para 1 ou mais

Para um mapeamento de dados de 2 para 1 ou mais, você deverá usar uma expressão.

Para isso, antes de selecionar os atributos na coluna "FROM", clique na função concat (única função disponível) na seção EXPRESSION. Se preferir, você pode escrever a expressão manualmente.

É possível selecionar apenas um atributo da coluna "TO", e esse atributo não pode ser escolhido mais de uma vez.

Veja um GIF demonstrativo abaixo:

data mapping 2 to 1

Agora, veja mais um exemplo de mapeamento de dados:

  • Uso da função concat para mapear três atributos da coluna "FROM" (logradouro, município e UF) para o atributo logradouro da coluna "TO".

  • Mapeamento do atributo nome_social da coluna "FROM" para o atributo nome da coluna "TO". O For Each aparece na frente da expressão, pois é a origem do payload.

  • Mapeamento manual da cidade "São Paulo" para o atributo cidade da coluna "TO".

Veja os exemplos no GIF abaixo:

data mapping examples

Campos de mapeamento de dados

Você pode visualizar o mapeamento de dados em DATA MAPPING FIELDS.
Cada linha apresenta o atributo de entrada (ou a expressão) e o atributo de saída nas respectivas colunas.

Se a seta entre as colunas "FROM" e "TO" estiver cinza, isso indica que não há uma expressão associada. Por outro lado, se a seta estiver laranja, significa que uma expressão foi utilizada.

Para excluir uma linha do mapeamento de dados:

  1. Clique na seta entre as colunas "FROM" e "TO" para selecionar a linha.

  2. Depois clique na icone de lixeira ao lado do título da seção "DATA MAPPING FIELDS".

Estrutura dos atributos

Considere o exemplo de mapeamento de dados com a função concat:

concat($.API_Brasil.Response.Payload.logradouro$.API_Brasil.Response.Payload.municipio$.API_Brasil.Response.Payload.uf) ->  $.Request.Payload.endereço.logradouro

Atributos de entrada

Observe como as diferentes partes da estrutura de dados da API aparecem no mapeamento de dados:

  • Response

    • Payload

      • Logradouro

      • Município

      • UF

        concat($.API_Brasil.Response.Payload.logradouro$.API_Brasil.Response.Payload.municipio$.API_Brasil.Response.Payload.uf)

        1. concat: a função concat junta os três elementos em uma única string.

        2. $.: convenção comum em linguagens e estruturas de dados que utilizam notação de caminho (path notation) para acessar elementos dentro de objetos ou JSON.

        3. API_Brasil.Response.Payload.logradouro: esse caminho aponta para o campo "logradouro" dentro do payload da resposta da API Brasil.

        4. API_Brasil.Response.Payload.município: esse caminho aponta para o campo "município" dentro do payload da resposta da API Brasil.

        5. API_Brasil.Response.Payload.uf: esse caminho aponta para o campo "uf" dentro do payload da resposta da API Brasil.

Atributos de saída

  • Request

    • Payload

      • Endereço

        • Logradouro

          $.Request.Payload.endereço.logradouro

Este trecho indica que o resultado da concatenação (o endereço completo) será armazenado no campo "logradouro" do payload de requisição.

Data Mapping com Full Body

No canto superior direito de Data Mapping, você pode habilitar ou desabilitar o botão FULL BODY.

Assim, a requisição do conector é enviada com as propriedades, estruturas e valores na requisição da chamada e você não precisa mapeá-los um a um. Ao habilitar o botão, você automatiza todo o processo de mapeamento de dados.

full body

Para automatizar seu processo, siga as etapas abaixo:

  1. Habilite o FULL BODY.

  2. No campo Input Data, selecione o step que contém os dados a serem mapeados. Você poderá selecionar o payload de requisição/resposta dos conectores, o payload de requisição do gatilho ou o For Each.

  3. Em Full Data Mapping, visualize o mapeamento feito automaticamente transformando os campos de "FROM" para os campos de "TO".

  4. Clique em CONFIRM para salvar o mapeamento de dados.

Uma vez salvo, será possível visualizá-lo abaixo da aba Body e a opção de edição estará habilitada.

Ao clicar na aba Header, você visualiza os cabeçalhos associados à rota escolhida na configuração do formulário do conector de API REST.

Configure os seguintes campos:

  • Name: por padrão, o formulário carrega o nome automaticamente. Se não houver nenhum, você poderá inseri-lo manualmente.

  • Value: informe o valor do cabeçalho. Você pode fazer isso manualmente ou utilizando o botão icone de expressao para acessar o Expression Builder. Neste caso, você pode criar expressões ou apenas utilizar a coluna Properties para selecionar os atributos e clicar em CONFIRM.

header connector

Query

Ao clicar na aba Query, você visualiza os parâmetros de consulta associados à rota escolhida na configuração do formulário do conector de API REST.

Configure os seguintes campos:

  • Name: por padrão, o formulário carrega o nome automaticamente. Se não houver nenhum, você poderá inseri-lo manualmente.

  • Value: informe o valor do parâmetro de consulta. Você pode fazer isso manualmente ou utilizando o botão icone de expressao para acessar o Expression Builder. Neste caso, você pode criar expressões ou apenas utilizar a coluna Properties para selecionar os atributos e clicar em CONFIRM.

query connector

Path

Ao clicar na aba Path, você visualiza os parâmetros de caminho associados à rota escolhida na configuração do formulário do conector de API REST.

Configure os seguintes campos:

  • Name: por padrão, o formulário carrega o nome automaticamente. Se não houver nenhum, o campo é bloqueado.

  • Value: informe o valor do parâmetro de caminho. Você pode fazer isso manualmente ou utilizando o botão icone de expressao para acessar o Expression Builder. Neste caso, você pode criar expressões ou apenas utilizar a coluna Properties para selecionar os atributos e clicar em CONFIRM.

path connector

Após finalizar a configuração do conector, clique em SAVE.

Expression Builder

O componente Expression Builder permite que você crie expressões com parâmetros e variáveis através de funções e condições disponíveis dentro do componente. Assim, você pode ajustar a expressão conforme suas necessidades.

Você pode criar expressões para os seguintes campos:

  • URL;

  • Request Timeout.

Siga os passos abaixo para acessar a tela do Expression Builder:

  1. Clique no ícone de Properties icone de lista, à direita dos campos URL ou Request Timeout.

  2. Em seguida, clique no ícone icone de expressão no canto superior direito.

expression builder connector

A tela de Expression Builder contém as seguintes seções:

  • Properties: mostra os dados dos steps anteriores e as variáveis de ambiente. Você pode filtrar os atributos usando o campo de busca no topo da seção e clicando em icone lupa. Você pode selecionar mais de um atributo. Ao selecioná-lo, o atributo aparece no campo Expression.

  • Expression: campo para inserir os atributos de entrada ou criar uma expressão clicando no botão botao fx à direita. Apenas a função Concat está disponível para criar a expressão.

Ao selecionar dois ou mais atributos no campo Properties, será obrigatória a criação de uma expressão.

Para salvar as informações, clique em CONFIRM.

Alerta alertIcon

Um ícone de alerta aparecerá no conector se:

  • Os campos abaixo não estiverem configurados:

    • Route

    • URL

    • Request Timeout

    • Security

  • As variáveis de ambiente registradas forem alteradas ou excluídas.

  • Os atributos definidos em steps anteriores forem modificados ou removidos enquanto ainda estão sendo utilizados no step configurado.

Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]