> 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/web-scraper-api/features/custom-parser/getting-started.md).

# Começando

Aprenda a usar o Custom Parser da Oxylabs. Nesta página, você encontrará exemplos abrangentes, dicas e detalhes sobre o que acontece se a análise falhar.

## Como usar o Custom Parser <a href="#how-to-use-custom-parser" id="how-to-use-custom-parser"></a>

### Exemplo de cenário

Extraia o **preço do primeiro produto** listado em um site de e-commerce, **`https://sandbox.oxylabs.io/products?q=super+mario`**:

<figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FsyYKUF76MWH5no3UxjZW%2Fimage.png?alt=media&amp;token=9b40f065-61e3-447a-b72e-a68d1cdd385e" alt="" width="375"><figcaption></figcaption></figure>

Há três maneiras de criar um parser. Esta página mostra a mais rápida, OxyCopilot, e as outras duas são abordadas em páginas próprias:

* [Gerar parsers com OxyCopilot](#generate-parsers-with-oxycopilot)
* [Gerar parsers via API](/products/pt-br/web-scraper-api/features/custom-parser/generating-parsing-instructions-via-api.md)
* [Escrever instruções de parsing manualmente](/products/pt-br/web-scraper-api/features/custom-parser/writing-instructions-manually/tips-for-writing-xpath-expressions.md#how-to-write-parsing-instructions-inlineextension)

### Gerar parsers com OxyCopilot

O OxyCopilot permite que você descreva suas necessidades em inglês simples para **criar automaticamente scrapers e parsers** para um site. Aprenda o básico seguindo as etapas abaixo e confira [a documentação do OxyCopilot](/products/pt-br/web-scraper-api/web-scraper-api-playground/oxycopilot.md#custom-parser-builder) para mais informações.

{% hint style="success" %}
Abra o [**Playground do Web Scraper API**](https://dashboard.oxylabs.io/en/api-playground) no nosso painel para acessar o OxyCopilot.
{% endhint %}

{% stepper %}
{% step %}

#### Insira a(s) URL(s)

Clique no **botão OxyCopilot** no canto superior esquerdo e insira até 3 URLs do mesmo tipo de página e clique em **Avançar**. Vamos usar esta URL sandbox: **`https://sandbox.oxylabs.io/products?q=super+mario`**.

<figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FFmFBG02HI7hRLK7L2cj5%2Fimage.png?alt=media&amp;token=9aaeebfb-2bad-443e-be66-2570235f3299" alt="" width="545"><figcaption></figcaption></figure>

{% hint style="info" %}
Você também pode configurar o scraper manualmente preenchendo os campos **Site**, **Scraper**e, **URL** campos no topo e ajustando **parâmetros adicionais** como renderização de JavaScript no menu lateral.
{% endhint %}
{% endstep %}

{% step %}

#### Configure os parâmetros do scraper

Em seguida, especifique os parâmetros do scraper, as instruções do navegador e ative a renderização de JavaScript se o site de destino exigir isso.

A página sandbox não precisa de renderização de JavaScript, então mantenha os padrões e clique em **Avançar**.&#x20;

{% hint style="info" %}
A renderização é importante quando os dados que você quer não estão no HTML que o servidor envia, mas são adicionados por JavaScript depois que a página carrega, como é comum em preços, listagens de produtos e avaliações. Sem renderização, Custom Parser vê apenas o HTML inicial, então instruções que apontam para esses dados não retornam nada. Leia mais sobre [**renderização de JavaScript**](/products/pt-br/web-scraper-api/features/js-rendering-and-browser-control.md#javascript-rendering).
{% endhint %}

<figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FnywZ0UXzVmsthQQmIbht%2Fimage.png?alt=media&amp;token=9be92716-53c5-4230-a6ba-b1484c532be7" alt="" width="470"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Escreva o prompt

Explique os dados que você quer extrair de uma página. Certifique-se de ser descritivo e fornecer as informações mais importantes. Você pode encontrar exemplos de prompt para sites populares em nossa [biblioteca de prompts do OxyCopilot](https://oxylabs.io/resources/prompts-code-samples).

Cole o prompt a seguir para extrair o preço do primeiro produto:

```
Extraia o preço do primeiro produto na página.
```

<figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FOG3MoIvtLoulTzaPFq26%2Fimage.png?alt=media&amp;token=3565708a-082c-4e42-b62c-98f60ff73a73" alt="" width="470"><figcaption></figcaption></figure>

Clique no **Gerar instruções** botão para enviar seu prompt.
{% endstep %}

{% step %}

#### Revise os dados e as instruções analisados

Quando o OxyCopilot terminar, você verá a janela a seguir, onde os dados analisados estão no lado direito:

<figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2F8Yd8bNBQXPwscHKdSK1U%2Fimage.png?alt=media&amp;token=ce799a13-a229-43b6-9de9-36cfd4873990" alt=""><figcaption></figcaption></figure>

Se quiser fazer algum ajuste, você pode fazer isso aqui. Modifique a URL(s), refine o prompt, ative a renderização de JavaScript ou [edite o esquema de parsing](/products/pt-br/web-scraper-api/web-scraper-api-playground/oxycopilot.md#step-2-optional-adjust-parsing-schema) para atender às suas necessidades. Quando você atualizar qualquer campo nesta janela, pode executar a solicitação novamente selecionando **Iniciar nova solicitação**.

Você também pode **visualizar e editar diretamente as instruções de parsing** aqui:

<figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FvW521rQpr277NpSDPSP8%2Fimage.png?alt=media&amp;token=ecf24ec7-a5b6-42bc-877e-79d9187dcf39" alt=""><figcaption></figcaption></figure>

Quando estiver satisfeito com o resultado, **Carregar instruções** para continuar.

<figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2F2bVplkgKW67lmAd7zWS9%2Fimage.png?alt=media&amp;token=5c067a5e-0b0e-4d47-b28d-c96e07deedcf" alt="" width="469"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Salvar o parser como um preset

Você pode salvar facilmente suas instruções de parsing como um [preset de parser](/products/pt-br/web-scraper-api/features/custom-parser/parser-presets.md)Isso permite reutilizar o preset no OxyCopilot e com suas solicitações de API.

No Playground do Web Scraper API, você pode opcionalmente escolher o usuário para o qual salvar o preset. Quando estiver tudo pronto, basta clicar em **Salvar**:

<figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FKuZLB7HY6298sZhClts8%2Fimage.png?alt=media&amp;token=f0429fc1-ad0a-4159-bf23-60b0bcccc25e" alt=""><figcaption></figcaption></figure>

Um pop-up aparecerá solicitando que você nomeie o preset e adicione uma descrição opcional:

<figure><img src="https://1795063165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FnpBJz2wlknd0kfAR1ayx%2Fimage.png?alt=media&amp;token=3e031dc5-3bd1-49a3-bdb8-81cb1473adc2" alt="" width="333"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Usar o preset com solicitações de API

Para usar um preset com suas solicitações do Web Scraper API, defina `parse` como `true` e especifique o nome do preset com o parâmetro `parser_preset` .

**Endpoint:** `POST https://realtime.oxylabs.io/v1/queries`

```json
{
    "source": "universal",
    "url": "https://sandbox.oxylabs.io/products",
    "parse": true,
    "parser_preset": "sandbox_first_product_price"
}
```

Ao executar a solicitação, você obterá a seguinte saída JSON:

```json
{
    "results": [
        {
            "_request": {...},
            "_response": {...},
            "content": {
                "parse_status_code": 12000,
                "price": 91.99
            },
            "created_at": "2026-09-08 11:21:03",
            "is_render_forced": false,
            "job_id": "7503049765014236161",
            "page": 1,
            "parser_preset": "sandbox_first_product_price",
            "parser_type": "preset",
            "session_info": {...},
            "status_code": 200,
            "type": "parsed",
            "updated_at": "2026-09-08 11:21:09",
            "url": "https://sandbox.oxylabs.io/products"
        }
    ]
}

```

{% endstep %}
{% endstepper %}

## Uso avançado

O OxyCopilot é a maneira mais rápida de criar um parser, mas cada etapa dele também está disponível diretamente pela API:

* **Gerar instruções de parsing via API** – envie um prompt ou um esquema JSON junto com algumas URLs de exemplo e receba instruções prontas para uso. Veja [**Gerando instruções de parsing via API**](/products/pt-br/web-scraper-api/features/custom-parser/generating-parsing-instructions-via-api.md).
* **Salvar e gerenciar presets via API** – crie, atualize, liste e exclua presets de parser e habilite a auto-recuperação. Veja [**Presets de parser**](/products/pt-br/web-scraper-api/features/custom-parser/parser-presets.md).
* **Escrever instruções de parsing manualmente** – monte seu próprio pipeline de extração com XPath e seletores CSS. Comece com [**Como escrever instruções de parsing**](/products/pt-br/web-scraper-api/features/custom-parser/writing-instructions-manually.md), depois navegue pelos [**Exemplos de instruções de parsing**](/products/pt-br/web-scraper-api/features/custom-parser/writing-instructions-manually/parsing-instruction-examples.md).

## O que acontece se o parsing falhar ao usar o Custom Parser <a href="#what-happens-if-parsing-fails-when-using-custom-parser" id="what-happens-if-parsing-fails-when-using-custom-parser"></a>

Se o Custom Parser não conseguir aplicar uma de suas instruções, o job ainda será concluído com sucesso: o resultado traz parse\_status\_code (processado com avisos) e uma lista `parse_status_code` `12005` (processado com avisos) e uma `_warnings` descrevendo qual instrução falhou e por quê. Você é cobrado por esses resultados.&#x20;

Por exemplo, esta solicitação pede um campo cujo XPath não corresponde a nada na página:

```json
{
    "source": "universal",
    "url": "https://sandbox.oxylabs.io/products",
    "parse": true,
    "parsing_instructions": {
        "first_product_price": {
            "_fns": [
                {
                    "_fn": "xpath_one",
                    "_args": [
                        "//div[contains(@class, 'price-wrapper')]/text()"
                    ]
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        },
        "number_of_reviews": {
            "_fns": [
                {
                    "_fn": "xpath",
                    "_args": [
                        "//this-will-not-match-anything"
                    ]
                },
                {
                    "_fn": "length"
                }
            ]
        }
    }
}
```

O preço é extraído normalmente, o campo com falha é retornado como `null`, com um aviso:

```json
{
    "results": [
        {
            "_request": {...},
            "_response": {...},
            "content": {
                "_warnings": [
                    {
                        "_fn": "xpath",
                        "_fn_idx": 0,
                        "_msg": "As expressões XPath não corresponderam a nenhum dado.",
                        "_path": ".number_of_reviews"
                    }
                ],
                "first_product_price": 91.99,
                "number_of_reviews": null,
                "parse_status_code": 12005
            },
            "created_at": "2026-09-08 09:00:40",
            "is_render_forced": false,
            "job_id": "7503014433245923329",
            "page": 1,
            "parser_preset": null,
            "parser_type": "custom",
            "session_info": {...},
            "status_code": 200,
            "type": "parsed",
            "updated_at": "2026-09-08 09:00:44",
            "url": "https://sandbox.oxylabs.io/products"
        }
    ]
}
```

Para ignorar um campo com falha em vez de receber um aviso, veja [**Exemplos de instruções de parsing › Tratamento de erros**](/products/pt-br/web-scraper-api/features/custom-parser/writing-instructions-manually/parsing-instruction-examples.md#error-handling).

Se o Custom Parser encontrar uma exceção e falhar durante a operação de parsing, ele pode retornar códigos de status `12002`, `12006`e, `12007`. Você não será cobrado por esses erros inesperados.

Instruções que fazem referência a uma função inexistente são rejeitadas no envio e nenhum job é criado. A API retorna um HTTP `400` erro nomeando a função ausente e seu caminho: a função `not_a_real_fn` não está definida.

## Códigos de status <a href="#status-codes" id="status-codes"></a>

Veja nossos códigos de status descritos [**aqui**](/products/pt-br/web-scraper-api/response-codes.md#parsers).


---

# 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 dynamically by asking a question.

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

```
GET https://developers.oxylabs.io/products/pt-br/web-scraper-api/features/custom-parser/getting-started.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.