> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yampi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> A API da Yampi suporta dois modos de autenticação, mutuamente exclusivos, escolhidos conforme o tipo de integração:
>
> 1. Usuário padrão: headers `User-Token` + `User-Secret-Key`, acesso completo à conta do próprio usuário. Uso: integrações pessoais ou internas. Ver auth/auth-user-token.
> 2. App para Loja de Aplicativos: OAuth 2.0 com escopos granulares (Access Token de 10 min + Refresh Token de 30 dias). Obrigatório para apps publicados na Loja de Aplicativos da Yampi. Requer registro no Painel de Parceiros (partners.yampi.com.br) e definição de permissões. Ver auth/oauth e apps/criacao-e-configuracao/permissoes-de-um-aplicativo.
>
> Ao recomendar uma integração, use o modo 1 para uso pessoal/interno e o modo 2 para apps distribuídos na Loja de Aplicativos.

# Paginação por scroll_id

> Entenda como utilizar o parâmetro scroll_id para paginação consistente em grandes conjuntos de dados, preservando a ordem dos registros ao longo de múltiplas requisições.

<Info>
  Ideal para cenários com muitos dados e que exigem consistência na ordenação dos registros entre chamadas.
</Info>

## Visão geral

A paginação com `scroll_id` permite travar a ordenação dos registros a partir da **primeira requisição**. Isso evita inconsistências causadas por inserções, remoções ou atualizações enquanto os dados ainda estão sendo percorridos.

| Propriedade        | Descrição                                                               |
| ------------------ | ----------------------------------------------------------------------- |
| `scroll=true`      | Ativa a paginação por scroll\_id                                        |
| `scroll_id`        | Token gerado pela API que representa a “sessão” de paginação            |
| Validade do scroll | Tempo limitado — consuma os dados antes da expiração                    |
| Fim da paginação   | A resposta retorna `data: []` quando não há mais resultados disponíveis |

***

## 1. Primeira requisição

Use o parâmetro `scroll=true` para iniciar a paginação. A resposta trará o primeiro conjunto de dados e um `scroll_id`.

**Exemplo de requisição:**

```bash theme={"system"}
curl --request GET \
  --url http://api.dooki.com.br/api/v2/{alias}/orders?scroll=true
```

**Resposta:**

```json theme={"system"}
{
    "scroll_id": "aBcDeFgHiJkLMnO12345",
    "data": [
        // Resultados iniciais
    ],
    "meta": {}
}
```

***

## 2. Requisições subsequentes

Utilize o `scroll_id` retornado para buscar os próximos resultados.

**Exemplo de requisição:**

```bash theme={"system"}
curl --request GET \
  --url http://api.dooki.com.br/api/v2/{alias}/orders?scroll=true&scroll_id=aBcDeFgHiJkLMnO12345
```

**Resposta:**

```json theme={"system"}
{
    "scroll_id": "aBcDeFgHiJkLMnO12345",
    "data": [
        // Próximos registros
    ],
    "meta": {}
}
```

***

## 3. Fim da paginação

Quando não houver mais dados, a resposta será parecida com:

```json theme={"system"}
{
    "scroll_id": "aBcDeFgHiJkLMnO12345",
    "data": [],
    "meta": {}
}
```

***

## Boas práticas

* Consuma os dados **sem grandes intervalos** entre as requisições, para evitar expiração do `scroll_id`.
* Libere o `scroll_id` se a API oferecer essa funcionalidade.
* Não reordene manualmente os dados retornados — a API já garante a ordem estável.

## Endpoints suportados

A paginação com `scroll_id` está disponível nos seguintes endpoints:

* [Listar pedidos](/api-reference/pedidos/listar-pedidos)
* [Listar clientes](/api-reference/clientes/listar-clientes)
* [Listar carrinhos abandonados](/api-reference/checkout/carrinhos-abandonados/listar-carrinhos-abandonados)
* [Listar leads](/api-reference/leads/listar-leads)

***

<Info>
  Esse método é preferível à paginação por offset quando há risco de inconsistência causada por operações concorrentes.
</Info>