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:

Na página de configuração do conector REST V2, clique em Importar no canto superior direito e selecione cURL ou OpenAPI.
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.
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

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

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

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: {}
}

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: {}
}

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:

Selecione a conta desejada em Custom Account #1 ou Custom Account #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 }}"
}

AnteriorEmail V1: Exemplos de uso (Descontinuado)PróximoREST V1 (Descontinuado)

Atualizado há 18 dias

Isto foi útil?

hashtagVisão geral

hashtagImportando a partir de cURL ou OpenAPI

hashtagParâmetros

hashtagConexão

hashtagAutenticação

hashtagTimeouts

hashtagTratamento de erros

hashtagResposta

hashtagAvançado

hashtagDocumentação

hashtagFluxo de mensagens

hashtagEntrada

hashtagSaída

hashtagREST V2 em ação

hashtagConfigurando os timeouts

hashtagConnect Timeout

hashtagRead Timeout

hashtagWrite Timeout

hashtagCall Timeout

hashtagEnviando um arquivo binário

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

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

hashtagUsando contas

hashtagUsando custom accounts

Visão geral

Importando a partir de cURL ou OpenAPI

Parâmetros

Conexão

Autenticação

Timeouts

Tratamento de erros

Resposta

Avançado

Documentação

Fluxo de mensagens

Entrada

Saída

REST V2 em ação

Configurando os timeouts

Connect Timeout

Read Timeout

Write Timeout

Call Timeout

Enviando um arquivo binário

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

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

Usando contas

Usando custom accounts