# REST V2

O **REST V2** realiza chamadas a endpoints de HTTP, tornando muito simples ações como `GET`, `POST`, `PUT` e `DELETE`.

A grande diferença para a V1 é a adoção de expressões em Double Braces para compor URL, headers, query parameters e corpo da mensagem, permitindo acesso direto aos dados do pipeline.

{% hint style="info" %}
Este conector suporta assistência de IA para realizar a configuração. [Saiba mais](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/build-overview/canvas/connector-ai-assistant).
{% endhint %}

## **Parâmetros**

Dê uma olhada nos parâmetros de configuração do conector. Parâmetros suportados por [expressões Double Braces](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/overview) estão marcados com `(DB)`.

### **Aba Section Rest Connector V2**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>URL</strong> <code>(DB)</code></td><td>Endereço que receberá a chamada HTTP. Este parâmetro suporta Double Braces, mas a referência a informações de conta não é permitida.</td><td><a href="https://viacep.com.br/ws/%7B%7B"><code>https://viacep.com.br/ws/{{</code></a> <code>DEFAULT(message.$.cep, "04547-130") }}/json/</code></td><td>String</td></tr><tr><td><strong>Headers</strong> <code>(DB)</code></td><td>Configura todos os tipos de headers necessários para chamada, por exemplo: <code>Content-Type: application/json</code> ou <code>multipart/form-data</code>. Esse parâmetro suporta Double Braces para os campos key e value. No entanto, a referência a informações da conta é permitida apenas para os campos de value.</td><td><code>Content-Type: application/json</code></td><td>Pares de chave-valor</td></tr><tr><td><strong>Query Params</strong> <code>(DB)</code></td><td>Configura os query parameters necessários para a chamada. Este parâmetro suporta Double Braces apenas para campos de <code>value</code>.</td><td>N/A</td><td>Pares de chave-valor</td></tr><tr><td><strong>Verb</strong></td><td>Especifica o verbo que indica o método HTTP.</td><td><code>GET</code></td><td>String</td></tr><tr><td><strong>Use Dynamic Account</strong></td><td>Quando a opção estiver ativada, o conector irá usar a conta dinamicamente. Quando estiver desativada, a conta será usada estaticamente.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Account Name</strong></td><td>Nome da conta a ser definida. O nome da conta deve ser gerado dinamicamente através do conector <a href="../tools/store-account"><strong>Store Account</strong></a>. Este parâmetro fica disponível apenas se o parâmetro <strong>Use Dynamic Account</strong> estiver <strong>ativo</strong>.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Scoped</strong></td><td>Quando a opção estiver ativada, a conta armazenada é isolada para outro sub-processo. Nesse caso, os sub-processos verão sua própria versão dos dados da conta armazenada. Essa opção não é suportada para contas usadas em headers ou body. Este parâmetro fica disponível apenas se o parâmetro <strong>Use Dynamic Account</strong> estiver <strong>ativo</strong>. Para saber mais sobre a funcionalidade <strong>Scoped</strong>, leia a <a href="https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/overview/runtime/pipeline-engine/dynamic-accounts">documentação de Suporte a credenciais dinâmicas</a>.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Account</strong></td><td>Conta a ser utilizada pelo conector. Contas suportadas: ApiKey, AWS v4, Basic, Certificate Chain, Custom Auth Header, Google Key, Oauth2, Oauth Bearer Token e NTLM.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Custom Account #1</strong></td><td>Conta adicional a ser utilizada pelo conector por meio de Double Braces <code>{{ account.custom-1.value }}</code></td><td>N/A</td><td>String</td></tr><tr><td><strong>Custom Account #2</strong></td><td>Conta adicional a ser utilizada pelo conector por meio de Double Braces <code>{{ account.custom-2.value }}</code></td><td>N/A</td><td>String</td></tr><tr><td><strong>Connect Timeout</strong></td><td>Tempo máximo para estabelecer uma conexão com o servidor. Começa a contar ao tentar se conectar (DNS + handshake TCP + TLS, se aplicável). <a href="#configurando-os-timeouts">Saiba mais</a>.</td><td>30000</td><td>Inteiro</td></tr><tr><td><strong>Read Timeout</strong></td><td>Tempo máximo de espera para ler dados do servidor (após a conexão ser estabelecida). Começa a contar após o envio da requisição, enquanto aguarda a resposta. <a href="#configurando-os-timeouts">Saiba mais</a>.</td><td>30000</td><td>Inteiro</td></tr><tr><td><strong>Write Timeout</strong></td><td>Tempo máximo para enviar dados da requisição para o servidor, em milissegundos. Começa a contar durante o envio do corpo da requisição. <a href="#configurando-os-timeouts">Saiba mais</a>.</td><td>30000</td><td>Inteiro</td></tr><tr><td><strong>Call Timeout</strong></td><td>Tempo total permitido para a requisição inteira (conexão, escrita, leitura), em milissegundos. Começa a contar desde o início até o fim de toda a chamada HTTP. <a href="#configurando-os-timeouts">Saiba mais</a>.</td><td>30000</td><td>Inteiro</td></tr><tr><td><strong>Stop On Client Error</strong></td><td>Se ativada, a opção interrompe a execução do pipeline quando ocorre um erro HTTP da família 4xx na chamada ao endpoint.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Stop On Server Error</strong></td><td>Se ativada, a opção interrompe a execução do pipeline quando ocorre um erro HTTP da família 5xx na chamada ao endpoint.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Advanced Settings</strong></td><td>Configurações avançadas.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Raw Mode</strong></td><td>Se ativada, a opção recebe ou passa um payload que não é JSON.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Raw Mode As Base64</strong></td><td>Quando ativada, a opção mostra o retorno como base64.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Save As Local File</strong></td><td>Quando ativada, a opção salva o retorno como um arquivo no diretório local do pipeline.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Response File Name</strong> <code>(DB)</code></td><td>Nome do arquivo ou caminho completo do arquivo (por exemplo, <code>tmp/processed/file.txt</code>). Este parâmetro suporta Double Braces, mas a referência a informações de conta não é permitida.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Allow Insecure Endpoints</strong></td><td>Quando ativada, a opção permite que chamadas a endpoints HTTPS não seguros sejam realizadas.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Enable Retries</strong></td><td>Quando ativada, a opção permite que sejam feitas novas tentativas.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Number Of Retries</strong></td><td>Número máximo de tentativas antes de desistir da chamada.</td><td>0</td><td>Inteiro</td></tr><tr><td><strong>Time To Wait Between Retries</strong></td><td>Tempo máximo entre tentativas (em milissegundos).</td><td>0</td><td>Inteiro</td></tr><tr><td><strong>Compress Body With GZIP</strong></td><td>Quando ativada, a opção permite que o body seja comprimido com GZIP.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Force HTTP 1.1</strong></td><td>Quando ativada, a opção força a solicitação a ser executada utilizando HTTP 1.1.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Override Response Charset</strong></td><td>Quando ativada, a opção irá sobrescrever o charset retornado do endpoint para o charset especificado na propriedade “Response Charset”; do contrário, o retorno do charset no header “Content-Type” será respeitado. Se nenhum charset no header “Content-Type” for retornado, será utilizado o padrão UTF-8.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Response Charset</strong></td><td>Utilizado somente quando a opção “Override Response Charset” estiver ativada, forçará o uso do charset especificado na propriedade (Padrão: UTF-8).</td><td>UTF-8</td><td>String</td></tr><tr><td><strong>Disable Connection Pooling</strong></td><td>Quando ativada, a opção não mantém as conexões em um pool. O seu uso é recomendado para endpoints que apresentam problemas de compatibilidade quando conexões são reutilizadas.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Invalidate SSL Sessions on Every Call</strong></td><td>Quando ativada, a opção invalida sessões SSL em todas as chamadas.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Enable Follow Redirect</strong></td><td>Quando ativado, a execução do pipeline seguirá automaticamente os redirecionamentos para respostas 302. Caso contrário, a resposta original com status 302 será retornada, permitindo a inspeção dos dados antes que o redirecionamento seja seguido.</td><td>True</td><td>Booleano</td></tr></tbody></table>

{% hint style="info" %}
Atualmente, os parâmetros **Use Dynamic Account**, **Account Name** e **Scoped** podem ser usados apenas no Pipeline Engine v2.&#x20;
{% endhint %}

### **Aba Documentation**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td>Seção para documentar qualquer informação necessária sobre a configuração do conector e regras de negócio.</td><td>N/A</td><td>String</td></tr></tbody></table>

## **Fluxo de Mensagens**

### **Entrada**

Você pode usar a seguinte configuração no corpo da mensagem e pode fazer uso dela através de Double Braces:

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

{% hint style="warning" %}
Não se aplica ao verbo `GET`.
{% endhint %}

### **Saída**

* **em caso de sucesso**

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

* **em caso de sucesso (com a utilização da flag "Raw Mode As Base64")**

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

* **em caso de sucesso (com a utilização da flag “Save As Local File”)**

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

* **em caso de erro**

```json
{
    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 falhará 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 (por exemplo, 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, basta informar:

* o endpoint de destino
* o content type (MIME Type do arquivo) no header (ex.: application/pdf)
* o caminho onde o arquivo se encontra (apontar no campo **File Name**)

### **Como fazer requisições utilizando o content-type: MultiPart/form-data**

A primeira coisa que você precisa fazer é especificar esse header no conector: `(Content-Type: Multipart/form-data)`

Em seguida, depois de selecionar qualquer verbo HTTP (com exceção do `GET`), um campo vai se abrir para que você especifique o corpo do payload a ser enviado. Este deve ser o padrão para:

* **especificar campos**

```json
{
"fields": {
     "nome_do_campo1": "valor_do_campo_1",
     "nome_do_campo2": "valor_do_campo_2",
     ...
    }
}
```

* **especificar arquivos**

```json
{
    "files": {
      "nome_do_campo_do_arquivo1": "caminho_que_se_encontra_o_arquivo1",
      "nome_do_campo_do_arquivo2": "caminho_que_se_encontra_o_arquivo2",
      ...
    }
}
```

Caso precise de ambas as especificações, você pode combiná-las com expressões em Double Braces:

```json
{
    "files": {
        "file": {{ message.fileName }},
        "file2": {{ message.fileName2 }}
    },
    "fields": {
        "nome": {{ message.name }},
        "'endereço": {{ message.endereco }}
    }
}
```

### **Como fazer requisições utilizando o content-type: application/x-www-form-urlencoded**

A primeira coisa que você precisa fazer é especificar esse header no conector:&#x20;

`(Content-Type: application/x-www-form-urlencoded)`

Em seguida, depois de selecionar qualquer verbo HTTP (com exceção do GET), um campo vai se abrir para que você especifique o corpo do payload a ser enviado.

Exemplo:

```json
{ 
    "nome_do_campo1": {{ message.campo1}}, 
    "nome_do_campo2": {{ message.campo2}}, 
    ...
}
```

### **Usando contas**

No **REST V2**, você pode configurar três tipos de parâmetros de conta:

* **Account**
* **Custom Account #1**
* **Custom Account #2**

A diferença entre os parâmetros é que se você definir o parâmetro **Account**, o conector irá automaticamente preparar a requisição com as informações da conta, de acordo com a tecnologia de autenticação. No entanto, se você configurar uma ou mais **Custom Accounts**, elas só poderão ser usadas para referenciar suas informações em outros campos através de Double Braces.

{% hint style="info" %}
O parâmetro **Account** sempre tem precedência sobre **Custom Accounts**.
{% endhint %}

Estes são os tipos de contas suportados no **REST V2**:

* API Key
* AWS V4
* Basic
* Certificate Chain
* Custom Auth Header
* Google Key
* OAuth2
* OAuth Bearer Token
* NTLM

Saiba mais sobre como o **REST V2** prepara a autorização dependendo do tipo de conta:

#### **API Key**

Com os valores **URL-PARAM-NAME** e **API-KEY** definidos no tipo de conta API Key, a Plataforma adiciona um novo conjunto de parâmetros de consulta e valores na requisição da seguinte forma:

```
https://www.address.com?<URL-PARAM-NAME>=<API-KEY>
```

#### **AWS V4**

Se você precisar acessar um serviço AWS através de uma chamada de API REST, é necessário usar este tipo de conta. Internamente, a plataforma gera os cabeçalhos de autenticação da AWS e assina a mensagem com a assinatura AWS 4.

{% hint style="info" %}
Verifique a documentação do serviço AWS que você deseja acessar para ver quais cabeçalhos ou parâmetros adicionais precisam ser configurados para a chamada de API REST.
{% endhint %}

#### **Basic**

Se **USERNAME** e **PASSWORD** estiverem definidos no tipo de conta Basic, a Plataforma codifica os dados em formato BASE64 e adiciona um cabeçalho de autorização à requisição da seguinte forma:

```
Authorization: Basic <ENCODED-INFORMATION>
```

#### **Certificate Chain**

Quando este tipo de conta é definido, a Plataforma usa o **CHAIN** para validar e estabelecer uma conexão segura com o servidor da API.

#### **Custom Auth Header**

Com **HEADER-NAME** e **HEADER-VALUE** definidos no tipo de conta Custom Auth Header, a Plataforma cria um cabeçalho personalizado e o insere na requisição da seguinte forma:

```
<HEADER-NAME>: <HEADER-VALUE>
```

#### **Google Key**

Se você precisar acessar um serviço do Google através de uma chamada de API REST, é necessário usar este tipo de conta. Internamente, a plataforma gera o Google Authentication Token e o insere em um cabeçalho de autenticação da seguinte forma:

```
Authorization: Bearer <GOOGLE-JWT-TOKEN>
```

{% hint style="info" %}
Verifique a documentação do serviço do Google que você deseja acessar para ver quais cabeçalhos ou parâmetros adicionais precisam ser configurados para a chamada de API REST.
{% endhint %}

#### **OAuth 2**

Este tipo de conta aciona diferentes comportamentos dependendo do que o respectivo provedor espera. Veja como a Plataforma lida com a autenticação OAuth 2 com os provedores suportados pela Digibee:

* **Microsoft e Google:** para esses provedores, a Plataforma gera o access token e o insere em um cabeçalho de autorização da seguinte forma: `Authorization: Bearer <PROVIDER_ACCESS_TOKEN>`
* **Mercado Livre:** para este provedor, a Plataforma gera o access token e o insere como o valor de um parâmetro de consulta na requisição, da seguinte forma: `https://www.address.com?access_token=<API-KEY>`

#### **OAuth Bearer Token**

Se você já tiver um *token* OAuth, pode armazená-lo neste tipo de conta e a Plataforma o criará da seguinte forma e o substituirá em um cabeçalho de Autorização:

```
Authorization: Bearer <TOKEN>
```

Mais informações podem ser encontradas na [documentação de Contas](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/accounts).