REST V2

Aprenda a chamar endpoints HTTP externos e a configurar o conector REST V2 na Digibee Integration Platform.

Visão geral

O REST V2 realiza chamadas a endpoints HTTP, suportando ações como GET, POST, PUT e DELETE. Em comparação com a V1 (descontinuada), ele utiliza expressões em Double Braces para compor a URL, headers, query parameters e o corpo da mensagem, permitindo acesso direto aos dados do pipeline.

Você pode configurar o conector manualmente ou importar suas configurações diretamente a partir de um comando cURL ou de uma especificação OpenAPI, reduzindo o tempo de configuração e evitando erros.

Importando a partir de cURL ou OpenAPI

Quando você precisa integrar uma API externa, é possível importar seu contrato diretamente no conector REST V2 em vez de configurar cada campo manualmente. O conector suporta dois formatos de importação:

• cURL: Uma ferramenta de linha de comando usada para fazer requisições HTTP. Se você já tiver um comando cURL para a API que deseja chamar, pode colá-lo diretamente no conector.

• OpenAPI: Um formato de especificação padrão (JSON ou YAML) que descreve os endpoints, métodos, parâmetros e a estrutura de requisição de uma API. A maioria das APIs publica uma especificação OpenAPI em sua documentação para desenvolvedores.

Para importar uma configuração:

1. Na página de configuração do conector REST V2, clique em Importar no canto superior direito e selecione cURL ou OpenAPI.

2. Forneça o input:

   • Para cURL: Cole seu comando cURL. O conector suporta as flags -X, -H, -d, -u e -b.

   • Para OpenAPI: Insira seu contrato OpenAPI no formato JSON ou YAML.

3. Clique em Aplicar.

A Digibee faz o parse do input e preenche automaticamente os seguintes campos:

• URL: A URL base e o path.

• Verb: O método HTTP (GET, POST, PUT, DELETE, PATCH e HEAD).

• Headers: Todos os headers definidos no contrato.

• Query Params: Os query parameters definidos na especificação.

• Body: A estrutura do corpo da requisição.

A importação irá sobrescrever todos os campos atuais do conector.

Após importar, revise os campos preenchidos e configure os valores dinâmicos que o pipeline precisar usando expressões Double Braces.

Parâmetros

A tabela abaixo lista todos os parâmetros de configuração do conector. Parâmetros que suportam expressões Double Braces estão marcados com ✅ na coluna Suporta DB.

A coluna Visível quando indica os parâmetros que só aparecem na interface após uma condição ser atendida; parâmetros sempre visíveis são indicados com —.

Este conector suporta Alias, um parâmetro que salva a saída do conector para que ela possa ser referenciada posteriormente no pipeline por meio de expressões Double Braces.

Conexão

Parâmetro	Descrição	Tipo de dado	Suporta DB	Valor padrão	Visível quando
URL	Endereço que receberá a chamada HTTP. Suporta Double Braces, mas a referência a informações de conta não é permitida.	String	✅	https://viacep.com.br/ws/{{ DEFAULT(message.$.cep, "04547-130") }}/json/	—
Headers	Todos os headers necessários para a chamada (por exemplo, Content-Type: application/json). Suporta Double Braces para os campos key e value. A referência a informações de conta é permitida apenas para os campos de value.	Pares de chave-valor	✅	Content-Type: application/json	—
Query Params	Query parameters necessários para a chamada. Suporta Double Braces apenas para campos de value.	Pares de chave-valor	✅ (apenas values)	N/A	—
Verb	O método HTTP (GET, POST, PUT, DELETE, PATCH e HEAD).	String	❌	GET	—
Send A File	Quando ativado, envia um arquivo no lugar do body.	Booleano	❌	false	Verb é POST, PUT, DELETE ou PATCH
File Name	Nome do arquivo ou caminho completo do arquivo (por exemplo, tmp/processed/file.txt).	String	✅	N/A	Send A File está ativado
Body	O corpo da requisição. Clique em Escreva com IA para obter suporte de IA.	JSON	✅	N/A	Verb é POST, PUT, DELETE ou PATCH

Autenticação

Parâmetro	Descrição	Tipo de dado	Suporta DB	Valor padrão	Visível quando
Use Dynamic Account	Quando ativado, usa a conta dinamicamente; caso contrário, usa estaticamente.	Booleano	❌	false	—
Scoped	Quando ativado, isola a conta armazenada de outros sub-processos. Não suportado para contas usadas em headers ou body. Para saber mais, leia a documentação de Credenciais Dinâmicas.	Booleano	❌	false	Use Dynamic Account está ativado
Account Name	Nome da conta gerado dinamicamente pelo conector Store Account.	String	❌	N/A	Use Dynamic Account está ativado
Account	Conta utilizada pelo conector. Saiba mais na seção Usando contas.	String	❌	N/A	Use Dynamic Account está desativado
Custom Account #1	Conta cujas credenciais podem ser referenciadas em qualquer campo que suporte Double Braces por meio de {{ account.custom-1.<field> }}. Saiba mais na seção Usando custom accounts.	String	❌	N/A	—
Custom Account #2	Conta cujas credenciais podem ser referenciadas em qualquer campo que suporte Double Braces por meio de {{ account.custom-1.<field> }}. Saiba mais na seção Usando custom accounts.	String	❌	N/A	—

Timeouts

Saiba mais na seção Configurando os timeouts.

Parâmetro	Descrição	Tipo de dado	Suporta DB	Valor padrão
Connect Timeout	Tempo máximo para estabelecer uma conexão com o servidor, em milissegundos (inclui DNS, handshake TCP e TLS quando aplicável).	Inteiro	❌	30000
Read Timeout	Tempo máximo de espera para receber uma resposta após a conexão ser estabelecida, em milissegundos.	Inteiro	❌	30000
Write Timeout	Tempo máximo para enviar o corpo da requisição ao servidor, em milissegundos.	Inteiro	❌	30000
Call Timeout	Tempo total permitido para a requisição inteira (conexão, escrita, leitura), em milissegundos.	Inteiro	❌	30000

Tratamento de erros

Parâmetro	Descrição	Tipo de dado	Suporta DB	Valor padrão
Stop On Client Error	Quando ativado, interrompe a execução do pipeline ao ocorrer um erro HTTP da família 4xx.	Booleano	❌	false
Stop On Server Error	Quando ativado, interrompe a execução do pipeline ao ocorrer um erro HTTP da família 5xx.	Booleano	❌	false

Resposta

Parâmetro	Descrição	Tipo de dado	Suporta DB	Valor padrão	Visível quando
Override Response Charset	Quando ativado, substitui o charset retornado pelo endpoint pelo valor especificado em Response Charset.	Booleano	❌	false	—
Response Charset	Charset a ser aplicado.	String	❌	UTF-8	Override Response Charset está ativado

Avançado

Estes parâmetros estão disponíveis apenas quando Advanced Settings estiver ativado.

Parâmetro	Descrição	Tipo de dado	Suporta DB	Valor padrão	Visível quando
Raw Mode	Quando ativado, recebe ou envia um payload que não é JSON.	Booleano	❌	false	—
Raw Mode As Base64	Quando ativado, retorna o conteúdo da resposta em Base64.	Booleano	❌	false	Raw Mode está ativado
Save As Local File	Quando ativado, salva o retorno como um arquivo no diretório local do pipeline.	Booleano	❌	false	—
Response File Name	Nome do arquivo ou caminho completo do arquivo (por exemplo, tmp/processed/file.txt). Suporta Double Braces, mas a referência a informações de conta não é permitida.	String	✅	N/A	Save As Local File está ativado
Allow Insecure Endpoints	Quando ativado, permite chamadas a endpoints HTTPS com certificados inválidos.	Booleano	❌	false	—
Enable Retries	Quando ativado, realiza novas tentativas em caso de erros de servidor.	Booleano	❌	false	—
Number Of Retries	Número máximo de tentativas antes de desistir da chamada.	Inteiro	❌	0	Enable Retries está ativado
Time To Wait Between Retries	Tempo de espera entre as tentativas, em milissegundos.	Inteiro	❌	0	Enable Retries está ativado
Compress Body With GZIP	Quando ativado, comprime o corpo da requisição usando GZIP.	Booleano	❌	false	—
Force HTTP 1.1	Quando ativado, força a requisição a usar HTTP 1.1.	Booleano	❌	false	—
Disable Connection Pooling	Quando ativado, não reutiliza conexões. Recomendado para endpoints com problemas de reutilização de conexão.	Booleano	❌	false	—
Invalidate SSL Sessions On Every Call	Quando ativado, invalida sessões SSL em todas as chamadas. Recomendado para endpoints com problemas de reutilização de sessão SSL. Ativar essa opção torna o conector single-threaded.	Booleano	❌	false	—
Enable Follow Redirect	Quando ativado, segue automaticamente os redirecionamentos para respostas 302. Quando desativado, retorna a resposta original 302 para inspeção antes do redirecionamento.	Booleano	❌	true	—

Documentação

Parâmetro	Descrição	Tipo de dado	Suporta DB	Valor padrão
Documentation	Espaço para documentar informações sobre a configuração do conector e regras de negócio.	String	❌	N/A

Fluxo de mensagens

Entrada

O corpo da mensagem suporta valores estáticos e expressões Double Braces. Não se aplica ao verbo GET.

{
    "id": {{ DEFAULT(message.customer.id, UUID()) }},
    "name": {{ message.customer.name }},
    "type": "1"
}

Saída

Sucesso

Resposta padrão quando a chamada é bem-sucedida.

{
    status: 2xx,
    statusMessage: "STATUS_MESSAGE",
    body: {},
    headers: {}
}

Sucesso — Raw Mode as Base64

Retornado quando Raw Mode As Base64 está ativo. O corpo da resposta é codificado em Base64.

{
    status: 2xx,
    statusMessage: "STATUS_MESSAGE",
    body: "content in base64 format",
    headers: {}
}

Sucesso — Save As Local File

Retornado quando Save As Local File está ativado. O corpo da resposta contém o nome do arquivo salvo.

{
    status: 2xx,
    statusMessage: "STATUS_MESSAGE",
    body: {
        file: "name of the file defined in the Response File Name property"
    },
    headers: {}
}

Erro

Retornado quando a chamada HTTP falha.

{
    error: "error message",
    code: XXX,
    body: {},
    headers: {}
}

REST V2 em ação

Configurando os timeouts

Connect Timeout

Define o tempo máximo permitido para estabelecer uma conexão com o servidor. Se o servidor estiver lento para aceitar a conexão ou indisponível, a requisição falha após esse tempo.

Exemplo: O servidor demora mais de 10 segundos para completar o handshake. A conexão falha por timeout.

Read Timeout

Especifica o tempo máximo para aguardar uma resposta após o envio da requisição. Evita que o cliente fique esperando indefinidamente por dados.

Exemplo: O servidor aceitou a conexão, mas demora mais de 15 segundos para começar a responder. Um erro de timeout é retornado.

Write Timeout

Define o tempo máximo permitido para enviar o corpo da requisição ao servidor. Especialmente relevante para requisições com payloads grandes, como uploads de arquivos.

Exemplo: O upload de um arquivo leva mais de 30 segundos. A requisição falha por timeout na escrita.

Call Timeout

Define o timeout total para toda a chamada HTTP, incluindo conexão, envio e recebimento. Se a soma dos tempos ultrapassar esse valor, a requisição é abortada.

Exemplo: Você configura um timeout de 60 segundos para toda a operação. Se conectar, enviar e receber juntos ultrapassarem esse limite, a requisição é cancelada.

Enviando um arquivo binário

Para enviar um arquivo binário pelo REST V2, informe:

• O endpoint de destino na URL

• O content type (MIME type do arquivo) no header, por exemplo, application/pdf

• O caminho onde o arquivo se encontra no campo File Name

Como fazer requisições usando content-type: multipart/form-data

Especifique o header Content-Type: multipart/form-data no conector. Ao selecionar qualquer verbo HTTP, com exceção do GET, um campo será aberto para você especificar o corpo do payload a ser enviado.

Para especificar campos:

{
  "fields": {
    "nome_do_campo1": "valor_do_campo_1",
    "nome_do_campo2": "valor_do_campo_2"
  }
}

Para especificar arquivos:

{
  "files": {
    "nome_do_campo_do_arquivo1": "caminho_do_arquivo_1",
    "nome_do_campo_do_arquivo2": "caminho_do_arquivo_2"
  }
}

Você pode combinar ambas as estruturas e utilizar expressões Double Braces para valores dinâmicos.

Como fazer requisições usando content-type: application/x-www-form-urlencoded

Especifique o header Content-Type: application/x-www-form-urlencoded no conector. Ao selecionar qualquer verbo HTTP, com exceção do GET, um campo será aberto para você especificar o corpo do payload a ser enviado.

Exemplo:

{
  "nome_do_campo1": "valor_do_campo_1",
  "nome_do_campo2": "valor_do_campo_2"
}

Usando contas

O REST V2 suporta três parâmetros de conta, cada um com um comportamento diferente:

• Account: O conector prepara automaticamente a requisição com as credenciais da conta de acordo com a tecnologia de autenticação.

• Custom Account #1 e Custom Account #2: Podem ser usadas apenas para referenciar os valores das credenciais em outros campos por meio de Double Braces, por exemplo {{ account.custom-1.value }}.

O parâmetro Account sempre tem precedência sobre as custom accounts.

A tabela abaixo descreve como o conector prepara a autorização para cada tipo de conta suportado.

Tipo de conta	Como o conector lida com a autorização
API Key	Adiciona URL-PARAM-NAME e API-KEY como query parameters: https://www.address.com?<URL-PARAM-NAME>=<API-KEY>
AWS V4	Gera os headers de autenticação da AWS e assina a mensagem usando o algoritmo AWS Signature Version 4. Verifique a documentação do serviço AWS para identificar headers ou parâmetros adicionais necessários.
Basic	Codifica USERNAME e PASSWORD em Base64 e adiciona um header de autorização: Authorization: Basic <ENCODED-INFORMATION>
Certificate Chain	Usa a cadeia fornecida para validar e estabelecer uma conexão segura com o servidor da API.
Custom Auth Header	Cria um header personalizado usando HEADER-NAME e HEADER-VALUE: <HEADER-NAME>: <HEADER-VALUE>
Google Key	Gera um token de autenticação do Google e adiciona um header de autorização: Authorization: Bearer <GOOGLE-JWT-TOKEN>. Verifique a documentação do serviço do Google para identificar headers ou parâmetros adicionais necessários.
OAuth 2	O comportamento varia por provedor. Para Microsoft e Google: Authorization: Bearer <PROVIDER_ACCESS_TOKEN>. Para Mercado Livre: https://www.address.com?access_token=<API-KEY>
OAuth Bearer Token	Usa um token OAuth existente e adiciona um header de autorização: Authorization: Bearer <TOKEN>
NTLM	Lida automaticamente com a autenticação NTLM usando as credenciais definidas na conta.

Para saber mais sobre tipos de conta e configuração, leia a documentação de Contas.

Usando custom accounts

Custom Account #1 e Custom Account #2 permitem referenciar credenciais de contas diretamente em qualquer campo que suporte Double Braces, exceto o campo URL. Isso é útil quando você precisa usar os valores de uma conta de forma flexível, sem depender da autenticação automática gerenciada pelo parâmetro Account.

As credenciais referenciadas por custom accounts não são expostas no output do conector. O comportamento é o mesmo das demais contas: os valores são utilizados internamente para realizar a chamada e não aparecem na resposta do pipeline.

Para usar uma custom account:

1. Selecione a conta desejada em Custom Account #1 ou Custom Account #2.

2. Em qualquer campo que suporte Double Braces, referencie os valores da conta usando as expressões abaixo.

A conta OAuth 2 não tem suporte para ser referenciada por custom accounts.

Os campos disponíveis dependem do tipo de conta selecionado:

Tipo de conta	Campos disponíveis
API Key	{{ account.custom-1.url-param-name }} {{ account.custom-1.api-key }}
Basic	{{ account.custom-1.username }} {{ account.custom-1.password }}
Custom Auth Header	{{ account.custom-1.header-name }} {{ account.custom-1.header-value }}
OAuth Bearer Token	{{ account.custom-1.token }}
Certificate Chain	{{ account.custom-1.chain }} {{ account.custom-1.password }}
Google Key	{{ account.custom-1.key }} {{ account.custom-1.scopes }}
AWS V4	{{ account.custom-1.service-name }} {{ account.custom-1.access-key }} {{ account.custom-1.secret-key }} {{ account.custom-1.session-token }} {{ account.custom-1.region }}
NTLM	{{ account.custom-1.username }} {{ account.custom-1.password }} {{ account.custom-1.domain }} {{ account.custom-1.hostname }}

Substitua custom-1 por custom-2 ao referenciar a Custom Account #2.

Exemplo: Usando uma conta do tipo Basic para passar credenciais no corpo da requisição:

{
    "username": "{{ account.custom-1.username }}",
    "password": "{{ account.custom-1.password }}"
}