> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/pt-br/api-da-web/scrape/modos-de-entrega.md).

# Modos de entrega

Descubra como a Web API entrega os resultados: respostas em Realtime, jobs assíncronos com polling ou callbacks, entrega em armazenamento em nuvem e requisições em lote.

A Web API oferece três modos de entrega para atender a diferentes requisitos de carga de trabalho e volumes de execução.&#x20;

<table><thead><tr><th width="315">Entrega</th><th width="92">Máximo de itens</th><th width="143">Alvos</th><th width="215">Usado para...</th></tr></thead><tbody><tr><td><a href="#realtime"><strong>Realtime</strong></a> (Síncrono)<br><code>POST /v1/scrape/{source}</code></td><td>1</td><td>Todos os endpoints</td><td>Solicitações de baixa latência e testes</td></tr><tr><td><a href="#single-job-delivery-async"><strong>Async Single</strong></a> (Polling)<br><code>POST /v1/async/scrape/{source}</code></td><td>1</td><td>Todos os endpoints</td><td>Alta concorrência e volume</td></tr><tr><td><a href="#batch-delivery-async"><strong>Async Batch</strong></a> (Fila em lote)<br><code>POST /v1/async/scrape/batch/{source}</code></td><td>5,000</td><td>Selecionar endpoints</td><td>Ingestão em lote</td></tr></tbody></table>

A maioria dos `/scrape` endpoints é oferecida como opção para **Realtime** e **Async** como modos de entrega de resultados; o caminho determina quando e como você recebe o resultado.

```http
POST /v1/scrape/...          # realtime: o resultado é a resposta
POST /v1/async/scrape/...    # async: cria um trabalho e recupera o resultado separadamente
```

## Realtime

```http
POST /v1/scrape/{source}
```

A entrega em tempo real processa a coleta na conexão HTTP inicial. A solicitação fica bloqueada até que a renderização, a resolução de acesso e a análise sejam concluídas, retornando o conteúdo no corpo da resposta. Defina um timeout do cliente de pelo menos 150 segundos.

```bash
curl -X POST https://webapi.oxylabs.io/v1/scrape/amazon/product \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "B0CX23V2ZK",
    "domain": "com",
    "output": ["json"]
  }'
```

{% hint style="info" %}
Alguns endpoints não oferecem suporte à entrega em tempo real (por exemplo, downloads do YouTube, ChatGPT, Gemini e Perplexity). Confirme se o seu alvo é compatível em [Descoberta de endpoints](https://developers.oxylabs.io/products/pt-br/api-da-web/scrape/descoberta-de-endpoint.md) ou consulte a [Referência da API](https://developers.oxylabs.io/api-reference).
{% endhint %}

## Entrega de trabalho único (assíncrona)

```http
POST /v1/async/scrape/{source}
```

A entrega assíncrona de um trabalho único enfileira uma solicitação de coleta e retorna imediatamente um status HTTP `202 Accepted` contendo o identificador do trabalho.

```bash
curl https://webapi.oxylabs.io/v1/async/scrape/media/youtube/metadata \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query": "a1cWkClBXLI", "output": ["json"]}'
```

Quando um job é aceito, o ID do job é retornado em `metadata.request_id`.

```json
{
  "state": "pending",
  "params": { "query": "a1cWkClBXLI", "output": ["json"] },
  "metadata": { "timestamp": 1787599164, "request_id": "7497734325668954113" }
}
```

O status do job enviado pode ser consultado por meio de `state` resultados:

<table data-header-hidden><thead><tr><th width="172"></th><th></th></tr></thead><tbody><tr><td><code>state: "pending"</code></td><td>O job está na fila ou em execução. O array <code>results</code> permanece vazio (<code>[]</code>).</td></tr><tr><td><code>state: "done"</code></td><td>Job concluído. O array <code>results</code> contém a saída analisada.</td></tr><tr><td><code>state: "faulted"</code></td><td>A extração falhou. Consulte <code>results[].metadata.status_code</code> para obter detalhes.</td></tr></tbody></table>

### Recuperação da saída

Os resultados são recuperados por meio de [polling](#polling-endpoint-get-v1-async-scrape-jobid), [webhooks](#webhooks-callback_url) (URL de callback) ou uploads diretos para [armazenamento em nuvem](#cloud-storage-upload-storage).

#### **Endpoint de polling (`GET /v1/async/scrape/{jobId}`)**

Envie o valor numérico de `metadata.request_id` para o endpoint de polling.

```bash
curl -X GET https://webapi.oxylabs.io/v1/async/scrape/7497971512142465025 \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY"
```

#### **Webhooks (`callback_url`)**

Inclua `callback_url` no corpo da solicitação inicial. Quando a execução mudar para `done` ou `faulted`, a API envia uma solicitação HTTP `POST` com os resultados do job para o endpoint especificado.

```json
{
  "query": "B0CX23V2ZK",
  "output": ["json"],
  "callback_url": "https://your-api.example.com/webhooks-oxylabs"
}
```

A URL é validada no momento do envio; URLs malformadas são rejeitadas com o erro `400`.

### **Upload para armazenamento em nuvem (`storage`)**

Usando `storage` O parâmetro grava o resultado em um bucket, além de disponibilizá-lo por polling e webhooks. **Somente caminhos assíncronos** – solicitações Realtime com `storage` são rejeitadas com `400`.

```json
//POST /v1/async/scrape/amazon/product
{
  "query": "B0CX23V2ZK",
  "output": ["json"],
  "storage": {
    "type": "s3",
    "url": "s3://your-bucket-name/scraped-data"
  }
}
```

<table><thead><tr><th width="142">Campo</th><th>Valores</th></tr></thead><tbody><tr><td><code>storage.type</code></td><td><code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>, <code>tos</code>.</td></tr><tr><td><code>storage.url</code></td><td>Caminho do bucket e da pasta, sem nome de arquivo. O resultado é salvo como <code>{request_id}.json</code> no local escolhido.</td></tr></tbody></table>

{% hint style="warning" %}
**`storage.url` não é validado.** Um URL válido com um destino incorreto ou digitado com erro é aceito; o trabalho é executado e cobrado, mas a entrega falha. Valores que não sejam URLs são rejeitados com `400`.

**`storage.type` é verificado em relação à lista acima.** Um tipo inválido retorna `400`. Teste o destino uma vez com uma única solicitação antes de usar um lote.

**`s3_gzip` funciona como `s3`** mas envia um arquivo compactado com gzip (`{request_id}.json.gz`).

**Se você solicitar várias saídas** (por exemplo, `["json", "html"]` ), todas serão salvas no mesmo arquivo.
{% endhint %}

Siga os guias rápidos abaixo para configurar a entrega em armazenamento na nuvem para os provedores compatíveis:

<details>

<summary>Google Cloud Storage</summary>

```json
{
  "query": "B0CX23V2ZK",
  "output": ["json"],
  "storage": {
    "type": "gcs",
    "url": "bucket_name/path"
  }
}
```

Para permitir que a Oxylabs envie resultados para seu bucket do GCS, crie uma função personalizada com permissão de upload e atribua-a à conta de serviço da Oxylabs:

{% stepper %}
{% step %}
**Criar uma função personalizada**

<div align="left"><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-32292235b253d2435d5e0a8d88558c068872956d%2Fgcs-1.png?alt=media" alt=""></div>
{% endstep %}

{% step %}
**Insira um título (por exemplo, `Oxylabs Uploader`) e adicione a permissão `storage.objects.create` Atribua-a à Oxylabs**

<div align="left"><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-815bad910c08ed706d3df43ddb20fff0f0563d6d%2Fgcs-2.png?alt=media" alt=""></div>
{% endstep %}

{% step %}
**Atribua-a à Oxylabs**

Abra o **Permissões** aba, clique **Adicionar**, no campo **Novos membros** digite o seguinte **e-mail da conta de serviço da Oxylabs**:

```
oxyserps-storage@oxyserps-storage.iam.gserviceaccount.com
```

<div align="left"><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-df5b74908cc6943c8d620b5e14487f2d003ebe43%2Fgcs-3.png?alt=media" alt=""></div>
{% endstep %}

{% step %}
**Selecione a função personalizada** que você criou na etapa 1 e clique em **Salvar.**
{% endstep %}
{% endstepper %}

</details>

<details>

<summary>Amazon S3</summary>

```json
{
  "query": "B0CX23V2ZK",
  "output": ["json"],
  "storage": {
    "type": "s3",
    "url": "s3://your-bucket-name/path"
  }
}
```

Para que os resultados do seu trabalho sejam enviados ao seu bucket do Amazon S3, configure as permissões de acesso para nosso serviço. Para isso, acesse o [**console do S3**](https://s3.console.aws.amazon.com/) → **`Buckets`** → selecione seu bucket (crie um se ainda não tiver) → **`Permissions`** aba → **`Bucket policy`** → **`Edit`**.

<div align="left"><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-1c27676a6e925e4a8c257cf422e991c8a6a1af2c%2Fs3_bucket_policy.png?alt=media" alt=""></div>

Você pode encontrar a política do bucket abaixo ou na área de exemplo de código.

{% file src="/files/84c463db620bbf6d7d2c55b109d8ab03aaf6bccf" %}

Não se esqueça de alterar o nome do bucket em `YOUR_BUCKET_NAME`. Essa política nos permite gravar no seu bucket, concede a você acesso aos arquivos enviados e nos permite identificar a localização do bucket.

```json
{
    "Version": "2012-10-17",
    "Id": "Policy1577442634787",
    "Statement": [
        {
            "Sid": "Stmt1577442633719",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::324311890426:user/oxylabs.s3.uploader"
            },
            "Action": "s3:GetBucketLocation",
            "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
        },
        {
            "Sid": "Stmt1577442633719",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::324311890426:user/oxylabs.s3.uploader"
            },
            "Action": [
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
        }
    ]
}
```

</details>

<details>

<summary>Alibaba Cloud Object Storage Service (OSS)</summary>

```json
{
  "query": "B0CX23V2ZK",
  "output": ["json"],
  "storage": {
    "type": "s3_compatible",
    "url": "https://ACCESS_KEY_ID:ACCESS_KEY_SECRET@BUCKET_NAME.oss-REGION.aliyuncs.com/FOLDER_NAME"
  }
}
```

#### Como formar a URL de armazenamento <a href="#forming-the-storage-url" id="forming-the-storage-url"></a>

Formato da URL de armazenamento:

```http
https://ACCESS_KEY_ID:ACCESS_KEY_SECRET@BUCKET_NAME.oss-REGION.aliyuncs.com/FOLDER_NAME
```

{% hint style="warning" %}
Não há suporte para o envio de arquivos à raiz do bucket. `storage.url` deve incluir o nome de uma pasta.
{% endhint %}

Veja onde encontrar o `BUCKET_NAME` e `oss-REGION` do seu bucket:

<figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-3258197766d6326f572b9230603b3f700738db36%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Criar a chave de acesso e o segredo <a href="#creating-the-access-key-and-secret" id="creating-the-access-key-and-secret"></a>

Para usar a interface compatível com S3 com o Alibaba OSS, você precisa criar o `ACCESS_KEY_ID` e `ACCESS_KEY_SECRET` conforme mostrado abaixo. Para mais informações, consulte [Como usar os SDKs do Amazon S3 para acessar o OSS](https://www.alibabacloud.com/help/en/oss/developer-reference/use-amazon-s3-sdks-to-access-oss?spm=a2c63.p38356.0.i1).

{% stepper %}
{% step %}
Acesse o **menu da conta AccessKey**

<div align="left"><figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-7a0c00eac6fd02fed28c7be5a5522985de3625d5%2Fimage.png?alt=media" alt="" width="422"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
Faça login no **RAM console**

Acesse o [RAM console](https://ram.console.aliyun.com/) usando uma **Alibaba Cloud** ou um **RAM User** com privilégios administrativos.
{% endstep %}

{% step %}
Acesse **Identidades** → **Usuários** no painel de navegação à esquerda
{% endstep %}

{% step %}
Selecione **Criar usuário** e use o **AccessKey do RAM User:**

<div align="left"><figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-e06b15f92c10028d2f5c368321821a90abf01f3f%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-4103046af7ce401cd189cd53f238fddf41b64ab5%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Conceder permissões ao RAM User**

O RAM User recém-criado não tem permissões. Você precisa conceder as permissões **AliyunOSSFullAccess** ao RAM User. Em seguida, o RAM User poderá acessar os recursos necessários da Alibaba Cloud. Para mais informações, consulte [Conceder permissões a RAM Users](https://www.alibabacloud.com/help/en/ram/user-guide/grant-permissions-to-the-ram-user#task-187800).

<div align="left"><figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-6d76a9af42bd9f8eaabdbee6c4baadd5824a0a09%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
Obtenha seu **AccessKey ID** e **AccessKey Secret**

Depois que as permissões forem concedidas, volte à seção **Autenticação** e, na seção **Access Key** selecione **Criar AccessKey**. Escolha criar uma AccessKey para um serviço de **terceiros**. Em seguida, você verá um `ACCESS_KEY_ID` e `ACCESS_KEY_SECRET`, que você poderá usar nas suas solicitações.
{% endstep %}
{% endstepper %}

#### Limites de taxa do Alibaba OSS <a href="#alibaba-oss-ratelimits" id="alibaba-oss-ratelimits"></a>

Ao fazer uploads simultâneos para o Alibaba OSS, é possível atingir os limites de taxa da conta ou do bucket, e os uploads começam a expirar com o seguinte erro:

<div align="left"><figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-8c6734c7968642444e43843fb1f200f0ab739c81%2Fimage.png?alt=media" alt="" width="563"><figcaption></figcaption></figure></div>

Nesse caso, entre em contato com o suporte do Alibaba OSS para aumentar os limites de taxa do seu OSS.

</details>

<details>

<summary>BytePlus Torch Object Storage (TOS)</summary>

Para estabelecer uma conexão com sucesso, você precisará de:

* Um bucket TOS configurado corretamente.
* Sua chave de acesso e chave secreta.
* Um endpoint compatível com S3.

Você pode encontrar uma lista de todos os endpoints S3 disponíveis na [documentação](https://docs.byteplus.com/en/docs/tos/docs-region-and-endpoint).

O payload a seguir envia os resultados para seu bucket TOS, e o resultado é salvo como\
`{request_id}.json` no caminho especificado.:

```json
{
  "query": "B0CX23V2ZK",
  "output": ["json"],
  "storage": {
    "type": "tos",
    "url": "https://ACCESS_KEY:SECRET_KEY@ENDPOINT/BUCKET_NAME/PATH"
  }
}
```

#### Formato da URL de armazenamento

O `storage.url` deve ser construído usando suas credenciais TOS e os detalhes do bucket.

```bash
https://access_key:secret_key@endpoint/bucket_name/path
```

| Componente    | Descrição                                                                        |
| ------------- | -------------------------------------------------------------------------------- |
| `access_key`  | Seu ID de chave de acesso do BytePlus.                                           |
| `secret_key`  | Sua chave secreta de acesso do BytePlus.                                         |
| `endpoint`    | O endpoint específico da região (por exemplo, `tos-cn-hongkong.bytepluses.com`). |
| `bucket_name` | Nome do bucket de destino.                                                       |
| `path`        | *(Opcional)* Caminho da pasta específica do bucket.                              |

{% hint style="warning" %}
Se sua chave de acesso ou chave secreta contiver caracteres especiais (como `/`, `+`, ou `=`), eles **devem ser codificados para URL** antes da criação da string.
{% endhint %}

</details>

<details>

<summary>Outro armazenamento compatível com S3</summary>

Se quiser que seus resultados sejam enviados para um local de armazenamento compatível com S3, inclua a `ACCESS_KEY:SECRET` string de autenticação do seu bucket no valor de `storage.url` do payload:

```json
{
  "query": "B0CX23V2ZK",
  "output": ["json"],
  "storage": {
    "type": "s3_compatible",
    "url": "https://ACCESS_KEY:SECRET@HOST/BUCKET_PATH"
  }
}
```

1. No console do seu provedor de armazenamento, **crie uma chave de acesso e uma chave secreta** que possa gravar no bucket de destino.
2. Criar `storage.url` a partir dos seus valores:
   * `ACCESS_KEY`: sua chave de acesso.
   * `SECRET`: sua chave secreta.
   * `HOST`: o host do endpoint S3 do seu provedor.
   * `BUCKET_PATH`: o nome do bucket, opcionalmente seguido de um caminho de pasta.

Exemplo: `https://ACCESS_KEY:SECRET@s3.example.com/my-bucket/results`

</details>

## Entrega em lote (assíncrona)

{% hint style="warning" %}
O roteamento em lote está disponível apenas para algumas `/scrape` fontes. Confirme se o destino é elegível em [Endpoint Discovery](https://developers.oxylabs.io/products/pt-br/api-da-web/scrape/descoberta-de-endpoint.md) ou consulte a [Referência da API](https://developers.oxylabs.io/api-reference).
{% endhint %}

```http
POST /v1/async/scrape/batch/{source}
```

A entrega em lote envia até 5.000 tarefas de scraping em uma única solicitação HTTP. Em vez de receber uma única string `url` ou `query` , o campo de entrada aceita um array de strings. Todos os outros campos do payload são aplicados a cada tarefa do lote.

```bash
curl -X POST https://webapi.oxylabs.io/v1/async/scrape/batch/amazon/product \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": ["B0CX23V2ZK", "B09B33PQS9", "INVALID_ASIN_XYZ"],
    "domain": "com",
    "output": ["json"]
  }'
```

Os endpoints em lote retornam o status HTTP `202 Accepted` com um array contendo o status de cada tarefa em `data[]` e um array `errors[]` que lista os itens rejeitados (por exemplo, devido à formatação inválida do ASIN ou à sintaxe inválida da URL). Veja o exemplo abaixo:

<details>

<summary>Exemplo de saída</summary>

```json
{
  "data": [
    {
      "state": "pending",
      "params": {
        "query": "B0CX23V2ZK",
        "output": [
          "json"
        ],
        "json": {
          "schema": null,
          "prompt": null
        },
        "location": null,
        "device": "desktop",
        "run_js": null,
        "storage": {
          "type": null,
          "url": null
        },
        "callback_url": null,
        "client_notes": null,
        "domain": "com",
        "locale": null,
        "autoselect_variant": false,
        "check_empty_geo": null,
        "safe_search": true,
        "currency": null
      },
      "metadata": {
        "timestamp": 1790852882,
        "request_id": "7511381408825235457"
      }
    },
    {
      "state": "pending",
      "params": {
        "query": "B09B33PQS9",
        "output": [
          "json"
        ],
        "json": {
          "schema": null,
          "prompt": null
        },
        "location": null,
        "device": "desktop",
        "run_js": null,
        "storage": {
          "type": null,
          "url": null
        },
        "callback_url": null,
        "client_notes": null,
        "domain": "com",
        "locale": null,
        "autoselect_variant": false,
        "check_empty_geo": null,
        "safe_search": true,
        "currency": null
      },
      "metadata": {
        "timestamp": 1790852882,
        "request_id": "7511381408825229313"
      }
    }
  ],
  "errors": [
    {
      "detail": "ASIN should only contain alphanumeric values.",
      "pointer": "/query/2"
    }
  ]
}
```

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/pt-br/api-da-web/scrape/modos-de-entrega.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
