Paginação por scroll_id - Yampi Developer Portal

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

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:

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

Resposta:

{
    "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:

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

Resposta:

{
    "scroll_id": "aBcDeFgHiJkLMnO12345",
    "data": [
        // Próximos registros
    ],
    "meta": {}
}

3. Fim da paginação

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

{
    "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:

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

​Visão geral

​1. Primeira requisição

​2. Requisições subsequentes

​3. Fim da paginação

​Boas práticas

​Endpoints suportados

Visão geral

1. Primeira requisição

2. Requisições subsequentes

3. Fim da paginação

Boas práticas

Endpoints suportados