# HTTP File Trigger (Upload and Download)

O **HTTP File Trigger** pode ser usado para:

* **Upload**: Enviar arquivos grandes (acima de 5 MB) para um pipeline via HTTP.
* **Download**: Baixar arquivos grandes usando o método GET.

A seguir, você aprenderá a configurar o trigger para ambos os casos.

## Parâmetros

Configure o trigger utilizando os parâmetros abaixo. Os campos que aceitam [expressões **Double Braces**](/documentation/connectors-and-triggers/pt-br/double-braces/overview.md) estão marcados na coluna **Suporta DB**.

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Tipo</th><th>Suporta DB</th><th>Padrão </th></tr></thead><tbody><tr><td><strong>Methods</strong></td><td>Define os métodos aceitos pelo pipeline.</td><td>String</td><td>❌</td><td><code>POST</code>, <code>PUT</code>, <code>GET</code>, <code>PATCH</code> and <code>DELETE</code></td></tr><tr><td><strong>Response Headers</strong></td><td>Cabeçalhos retornados pelo endpoint quando o processamento do pipeline é concluído. Evite caracteres especiais nas chaves, pois podem causar falhas em proxies e gateways.</td><td>Pares chave-valor</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Add Cross-Origin Resource Sharing (CORS)</strong></td><td><p>Quando habilitado, permite adicionar cabeçalhos CORS que serão retornados pelo endpoint após o processamento do pipeline.</p><p>Use vírgula (<code>,</code>) para separar múltiplos valores em um cabeçalho, sem espaços antes ou depois da vírgula. Evite caracteres especiais nas chaves dos cabeçalhos, pois podem causar falhas em proxies ou gateways.</p></td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>CORS Headers</strong></td><td><p>Define CORS especificamente para o pipeline e suas restrições.</p><p>Para configurá-lo globalmente (em vez de individualmente por pipeline), consulte a política <a href="/spaces/cO0A6g1dOsu8BiHYqO67/pages/7aoFRCjBA1H7eamrFiy0">CORS HTTP Header.</a></p></td><td>Pares chave-valor</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Form Data Uploads</strong></td><td>Habilita ou desabilita o recebimento de uploads via form data (multipart/form-data).</td><td>Booleano</td><td>❌</td><td>True</td></tr><tr><td><strong>Body Uploads</strong></td><td>Habilita ou desabilita o recebimento de uploads via body.</td><td>Booleano</td><td>❌</td><td>True</td></tr><tr><td><strong>Body Upload Content Types</strong></td><td>Define os tipos de conteúdo permitidos pelo pipeline para uploads via body.</td><td>String</td><td>❌</td><td><code>application/pdf</code>, <code>application/jpeg</code></td></tr><tr><td><strong>Response Content Types</strong></td><td>Define os tipos de conteúdo permitidos na resposta do pipeline. Exemplo: determina o formato da resposta.</td><td>String</td><td>✅</td><td><code>text/xml</code>, <code>application/xml</code></td></tr><tr><td><strong>Maximum Timeout</strong></td><td><p>Tempo máximo (em milissegundos) que o pipeline pode levar para processar informações antes de retornar uma resposta. Limite: <code>900000</code>.</p><p>Se o processamento ultrapassar esse limite, a requisição é encerrada e retorna um código <code>500</code> sem corpo de resposta.</p></td><td>Integer</td><td>❌</td><td><code>30000</code></td></tr><tr><td><strong>Maximum Request Size</strong></td><td>Define o tamanho máximo do arquivo na requisição de upload (em MB). Máximo: 100 MB.</td><td>Integer</td><td>❌</td><td><code>100</code></td></tr><tr><td><strong>External API</strong></td><td>Quando habilitado, publica a API em um gateway externo.</td><td>Booleano</td><td>❌</td><td>True</td></tr><tr><td><strong>Internal API</strong></td><td>Quando habilitado, publica a API em um gateway interno.</td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>mTLS enabled API</strong></td><td><p>Quando habilitado, publica a API em um gateway dedicado com mTLS, com um host de acesso diferente.</p><p>O pipeline pode ter as opções <strong>External API</strong> e <strong>Internal API</strong> habilitadas, mas recomenda-se mantê-las desativadas.</p><p>Este parâmetro não oferece suporte a <strong>API Key</strong>, <strong>JWT</strong> ou <strong>Basic Auth</strong>. Para habilitá-los no seu realm, <a href="/spaces/3ANg0NQQeslB7Og5K7Ah/pages/cTgqarQgfKeG4UrPbv8D">entre em contato com o Suporte</a>.</p></td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>API Key</strong></td><td>Quando habilitado, o endpoint só pode ser acessado se uma API Key tiver sido previamente configurada na Plataforma Digibee.</td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>Token JWT</strong></td><td>Quando habilitado, solicita o token para consumo da API.</td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>Basic Auth</strong></td><td><p>Quando habilitado, o endpoint só pode ser consumido se uma configuração de Basic Auth estiver presente na requisição.</p><p>Essa configuração pode ser registrada previamente pela página <a href="/spaces/cO0A6g1dOsu8BiHYqO67/pages/VigyQvgFkuqc5CMaQ94X">Consumers</a> na Plataforma da Digibee.</p></td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>Additional API Routes</strong></td><td>Quando habilitado, permite adicionar novas rotas.</td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>Remove Digibee Prefix from Route</strong></td><td><p>Remove o prefixo padrão da rota da Digibee <code>/pipeline/{realm}/v{n}</code> da rota do pipeline. </p><p>Disponível apenas quando os parâmetros <strong>External API</strong> e <strong>Internal API</strong> estão desativados e os parâmetros <strong>mTLS enabled API</strong> e <strong>Additional API Routes</strong> estão habilitados.</p></td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>Routes</strong></td><td>Define rotas personalizadas.</td><td>String</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Rate Limit</strong></td><td><p>Quando habilitado, aplica limitação de taxa ao gateway da API.</p><p>Disponível se <strong>API Key</strong> ou <strong>Basic Auth</strong> estiverem habilitados.</p></td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>Limit by</strong></td><td>Define a entidade à qual os limites serão aplicados.</td><td>String</td><td>❌</td><td>API</td></tr><tr><td><strong>Aggregate by</strong></td><td>Define a entidade usada para agregação dos limites. Opções: <a href="/spaces/cO0A6g1dOsu8BiHYqO67/pages/VigyQvgFkuqc5CMaQ94X">Consumers e Credential</a> (API Key, Basic Auth).</td><td>String</td><td>❌</td><td>Consumer</td></tr><tr><td><strong>Options</strong></td><td>Define o limite de requisições permitidas dentro de um intervalo de tempo.</td><td>Opções de limite e intervalo</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Interval</strong></td><td>Define o intervalo de tempo para o limite de requisições. Opções: <strong>second</strong>, <strong>minute</strong>, <strong>hour</strong>, <strong>day</strong> e <strong>month</strong>.</td><td>String</td><td>❌</td><td>second</td></tr><tr><td><strong>Limit</strong></td><td>Define o número máximo de requisições que os usuários podem fazer dentro do intervalo especificado.</td><td>Integer</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Allow Redelivery Of Messages</strong></td><td>Quando habilitado, permite a reenviar mensagens em caso de falha do Pipeline Engine.</td><td>Booleano</td><td>❌</td><td>False</td></tr></tbody></table>

## HTTP File Trigger em ação

### Upload

#### Cenário 1: `POST` com tipo de conteúdo de arquivo `multipart/form-data`&#x20;

Se você quiser enviar um arquivo maior que 5 MB, chame o endpoint do pipeline configurado com um **HTTP File Trigger** usando uma requisição `POST` com o tipo de conteúdo de arquivo `multipart/form-data`. Isso permite que o pipeline processe o arquivo. Siga estes passos:

1. Habilite a opção **Form Data Uploads** no **HTTP File Trigger**.
2. Faça a implantação (deploy) do pipeline.
3. Crie um [Consumer](/documentation/developer-guide/pt-br/platform-administration/settings/api-keys-consumers.md) e configure o acesso ao pipeline.
4. Chame o pipeline com o comando cURL:

```sh
curl -d “@file_name” https://godigibee.io/pipeline/realm_name/v1/http-file-upload -v -H 'Content-Type: application/pdf' -H 'apikey: generated_token'
```

* **`file_name`:** Refere-se a um arquivo local.
* **`realm_name`:** Realm onde o pipeline está localizado.
* **`generated_token`**: API Key gerada pelo consumer criado.

O pipeline receberá `arquivos [ ]` array  contendo:

* `fileName`
* `param`
* `contentType`

Isso permite que os arquivos sejam referenciados e acessados ​​a partir do pipeline:

```json
{
  "body": null,
  "form": {},
  "headers": {
  ...
  },
  "queryAndPath": {},
  "method": "POST",
  "contentType": "application/pdf",
  "path": "/pipeline/realm_name/v1/http-file-upload",
  "files": [
    {      
      "fileName": "55acdc09-c0fc-4f6a-b3ee-f4199076b0c4",
      "param": "body",
      "contentType": "application/pdf"    
    }  
  ]
}

```

#### Cenário 2: `POST` com tipo de conteúdo `multipart/form-data` de vários arquivos.&#x20;

Suponha que você tenha vários arquivos maiores que 5 MB. Você pode chamar um endpoint de um pipeline configurado com um **HTTP File Trigger** usando uma requisição `POST` com um tipo de conteúdo `multipart/form-data`, permitindo que o pipeline processe esses arquivos. Siga estes passos:

1. Habilite a opção **Form Data Uploads** no **HTTP File Trigger**.
2. Faça a implantação (deploy) do pipeline.
3. Crie um [Consumer](/documentation/developer-guide/pt-br/platform-administration/settings/api-keys-consumers.md) e configure o acesso ao pipeline.
4. Chame o pipeline com o comando cURL:

```sh
curl -F dgbfile1=@file_name1 -F dgbfile2=@file_name2 https://godigibee.io/pipeline/realm_name/v1/http-file-upload -v -H 'apikey: generated_token'
```

* **`file_name1`:** Refere-se a um arquivo local.
* **`file_name2`:** Refere-se a um arquivo local.
* **`realm_name`:** Realm onde o pipeline está localizado.
* **`generated_token`**: Refere-se a API Key gerada pelo consumidor criado.

O pipeline receberá `arquivos [ ]` array contendo:

* `fileName`
* `originalFileName`
* `param`
* `charset`
* `contentLength`
* `contentType`

Isso permite que os arquivos sejam referenciados e acessados ​​a partir do pipeline:

```json
{
  "body": "",
  "form": {},
  "headers": {
    ...
  },
  "queryAndPath": {},
  "method": "POST",
  "contentType": "multipart/form-data; boundary=------------------------b3c985803b952f2c",
  "path": "/pipeline/realm_name/v1/http-file-upload",
  "files": [
    {
      "fileName": "96f3ecb2-1c72-4980-9f01-6f44cafc719f",
      "originalFileName": "file1",
      "param": "dgbfile1",
      "contentType": "application/octet-stream",
      "charset": "UTF-8",
      "contentLength": 5242880
    },
    {
      "fileName": "58fb844f-a1d1-4788-b9b4-30df4b69165e",
      "originalFileName": "file2",
      "param": "dgbfile2",
      "contentType": "application/octet-stream",
      "charset": "UTF-8",
      "contentLength": 5242880
    }
  ]
}

```

#### Cenário 3: `POST` com qualquer tipo de conteúdo e body com mais de 5MB

Suponha que você tenha vários arquivos maiores que 5 MB. Você pode chamar um endpoint de pipeline configurado com um **HTTP File Trigger** usando uma requisição `POST` com qualquer tipo de conteúdo, permitindo que o pipeline processe esses arquivos. Siga estes passos:

1. Habilite a opção **Body Uploads** no **HTTP File Trigger**.
2. Faça a implantação (deploy) do pipeline.
3. Crie um [Consumer ](/documentation/developer-guide/pt-br/platform-administration/settings/api-keys-consumers.md)e configure-o para ter acesso ao pipeline.
4. Chame o pipeline utilizando o seguinte comando cURL:

```sh
curl -d '@file_name1' https://godigibee.io/pipeline/realm_name/v1/http-file-upload -v -H 'apikey: generated_token'
```

O pipeline receberá `arquivos [ ]` array contendo:

* `fileName`
* `param`
* `charset`
* `contentType`

Isso permite que os arquivos sejam referenciados e acessados ​​a partir do pipeline:

```json
{
  "body": null,
  "form": {},
  "headers": {
    ...
  },
  "queryAndPath": {},
  "method": "POST",
  "contentType": "application/pdf",
  "path": "/pipeline/realm_name/v1/http-file-upload",
  "files": [
    {
      "fileName": "55acdc09-c0fc-4f6a-b3ee-f4199076b0c4",
      "param": "body",
      "contentType": "application/pdf"
    }
  ]
}

```

### Download

#### Cenário: `GET` com qualquer tipo de conteúdo

Suponha que você tenha um arquivo com mais de 5 MB. Você pode chamar um endpoint de pipeline configurado com um **HTTP File Trigger** usando uma solicitação `GET` com qualquer tipo de conteúdo. O pipeline recebe e processa o arquivo, retornando-o de acordo com o tipo de conteúdo de saída e seu conteúdo original. Siga estes passos:

1. Inclua o método `GET` e especifique os **Response Content Types** no HTTP File Trigger.
2. Adicione um [File Reader ](/documentation/connectors-and-triggers/pt-br/connectors/files/file-reader.md)ao pipeline para pesquisar o arquivo a ser processado. Por exemplo, você pode configurar um conector [WGet](/documentation/connectors-and-triggers/pt-br/connectors/web-protocols/wget.md) para recuperar um arquivo de uma URL enviada ao endpoint durante uma chamada.
3. Insira um [JSON Generator](/documentation/connectors-and-triggers/pt-br/connectors/tools/json-generator.md) como a última etapa do seu pipeline para produzir um JSON no seguinte formato:

```json
{ 
    "file": "file-download.pdf",
    "Content-Type": "application/pdf"
}
```

4. Faça a implantação (deploy) do pipeline.
5. Crie um [Consumer ](/documentation/developer-guide/pt-br/platform-administration/settings/api-keys-consumers.md)e configure-o para ter acesso ao pipeline.
6. Chame o pipeline utilizando o seguinte comando cURL:

```sh
curl https://godigibee.io/pipeline/realm_name/v1/pipeline_name -v -H 'Content-Type: application/pdf' -H 'apikey: generated_token' -H 'urlDownload: http://url/path'
```

* **`realm_name`**: Refere-se ao realm onde o pipeline está localizado.&#x20;
* **`generated_token`**: Refere-se à **API Key** gerada pelo consumer criado recentemente.&#x20;
* **`urlDownload`**: Refere-se ao parâmetro enviado ao conector **WGet** para preencher o campo URL.\
  O atributo é opcional, mas permite uma abordagem mais flexível usando [Double Braces](/documentation/connectors-and-triggers/pt-br/double-braces/overview.md).\
  Funciona perfeitamente se o caminho for definido diretamente no conector **WGet**.

## Resposta do HTTP File Trigger

### Upload - Resposta

Para definir o formato da resposta do pipeline, adicione um conector de transformação, por exemplo o [**Transformer (JOLT)**](/documentation/connectors-and-triggers/pt-br/connectors/tools/jolt-v2.md), como a última etapa do pipeline e configure a resposta desejada:

```json
{  
    "body": "<xml>Output 1</xml>",  
    "code": 200,  
    "Content-Type": "application/xml"
}
```

#### Limitações de resposta para payloads acima de 5 MB

Para cargas (payloads) maiores que 5 MB, recomenda-se que o pipeline retorne um **arquivo**, em vez de um payload. Use o conector [**File Writer** ](/documentation/connectors-and-triggers/pt-br/connectors/files/file-writer.md)para gerar o arquivo e referencie-o na resposta do pipeline usando a propriedade `file`, em vez de `body`:

```json
{
"file": {{ message.fileName }},
"code": 200,
"Content-Type": "application/json"
}
```

### Download - Resposta

Para definir o formato da resposta do pipeline, adicione um conector de transformação, por exemplo o [**Transformer (JOLT)**](/documentation/connectors-and-triggers/pt-br/connectors/tools/jolt-v2.md), como a última etapa do pipeline e configure a resposta desejada:

```json
{  
    "file": "file-download.pdf",  
    "code": 200,  
    "Content-Type": "application/pdf"
}
```

O HTTP File Trigger também pode responder com corpos que não sejam arquivos, de forma semelhante ao [HTTP Trigger](/documentation/connectors-and-triggers/pt-br/triggers/web-protocols/http.md). Para isso, a última etapa do pipeline deve ter a seguinte estrutura:

```json
{ 
    "body": "information that will be written in the endpoint output", 
    "Content-Type": "body content type", 
    "code": <a HTTP return code>
}
```

### Propriedades das respostas

A mesma estrutura de resposta se aplica tanto a cenários de **upload** quanto de **download**.

* **`code`:** Código de status HTTP retornado pelo endpoint após o término da requisição.
* **`body`:** Corpo da mensagem de resposta. Este campo deve ser uma **string**. Se for necessário enviar dados em **JSON**, use a função [TOSTRING](/documentation/connectors-and-triggers/pt-br/double-braces/double-braces-functions.md#de-string).
* **`content-type`:** tipo de conteúdo do corpo da resposta. Todos os tipos de conteúdo são suportados, mas devem ser declarados no campo **Response Content Types**.

## Boas práticas

### Configuração global de autenticação

O parâmetro de configuração global reforça a autenticação de todos os pipelines usando o HTTP File Trigger. Quando ativado, os pipelines só podem ser publicados se pelo menos um método de autenticação (**API Key** or **Basic Auth**) é configurado.

### Remove Digibee Prefix from Route

Ao remover o prefixo padrão e definir a rota por meio do parâmetro **Additional API Route** certifique-se de não usar uma rota já atribuída a outro pipeline. Se houver várias versões principais do mesmo pipeline, lembre-se de que o controle de versão da rota deve ser gerenciado manualmente, pois não há um caminho de controle de versão automático (por exemplo: `/pipeline/realm/v1/`).

### Rate Limit

Ative o **Rate Limit** para restringir o número de requisições de API dentro de um intervalo específico. Use a configuração recomendada:

* **Limit by:** API
* **Aggregate by:** Credential (API Key, Basic Auth)
* **Options:**
  * Interval: second → Limit: 100
  * Interval: minute → Limit: 1000
  * Interval: hour → Limit: 5000

Se a API incluir caminhos adicionais, o limite se aplicará a todos eles coletivamente. Para ativar o Rate Limit, a API deve usar uma **chave de API** ou **Basic Auth**, permitindo a agregação por grupos de credenciais (opção **Consumer**) ou credenciais individuais (opção **Credentials**).

{% hint style="info" %}
Se vários parâmetros de intervalo tiverem o mesmo valor, apenas um será considerado. O parâmetro **Limit** deve ser sempre maior que zero. Configurações de limitação de taxa incorretas ou incompletas serão ignoradas e um log de aviso será gerado. Você pode visualizar este log na páginas de [Pipeline Logs](/documentation/developer-guide/pt-br/development-cycle/dashboards/pipeline-logs.md).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/triggers/web-protocols/http-file.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
