# Paginação por cursor

Como as listagens devolvem páginas com limit, after, has_more e next_cursor, e como percorrer todas as páginas sem perder registos.


As listagens da API não usam números de página. Cada resposta traz um lote de registos e, quando há mais, um cursor opaco que aponta para o último registo devolvido. O pedido seguinte envia esse cursor e recebe o lote que vem depois.

## Parâmetros do pedido

| Parâmetro | Onde | Comportamento |
| :--- | :--- | :--- |
| `limit` | query | Número máximo de registos na página. Sem valor, o servidor usa 20; acima de 100, o servidor reduz para 100 sem devolver erro. |
| `after` | query | O valor de `next_cursor` da página anterior. Na primeira página, não o envie. |

O nome do parâmetro é `after` em todas as listagens declaradas com `PageAfter` na especificação OpenAPI. Os filtros próprios de cada recurso (por exemplo `status` ou `q`) combinam-se com estes dois; veja [Filtrar e pesquisar](/docs/getting-started/expanding-filtering).

## Campos da resposta

| Campo | Tipo | Significado |
| :--- | :--- | :--- |
| `data` | array | Os registos desta página. |
| `has_more` | boolean | `true` quando existem registos depois do último de `data`. |
| `next_cursor` | string | Presente apenas quando `has_more` é `true`. Passe-o em `after`. |

Na listagem de clientes, a ordem é do mais recente para o mais antigo, por data de criação e, em caso de empate, por identificador. Como o cursor guarda a posição do último registo e não um número de página, um cliente criado enquanto percorre a lista fica antes do ponto onde está e não aparece duas vezes nem empurra registos para a página seguinte.

## Exemplo de pedido e resposta

```bash
curl -sS "$BUSINESS_API/customers?limit=2" \
  -H "Authorization: Bearer $API_KEY"
```

```json
{
  "data": [
    {
      "id": "cus_2kFq8VmZ3xNcR7tLpW4hYb9sDeA",
      "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
      "customer_type": "individual",
      "category": "residential",
      "display_name": "Amélia Cossa",
      "phone": "+258841234567",
      "status": "active",
      "created_at": "2026-11-19T09:05:12.481203Z",
      "updated_at": "2026-11-19T09:05:12.481203Z"
    },
    {
      "id": "cus_2kFq9AbN4yPdS8uMqX5iZc0tEfB",
      "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
      "customer_type": "business",
      "category": "institutional",
      "display_name": "Escola Primária de Malhangalene",
      "status": "active",
      "created_at": "2026-11-19T08:20:00.123456789Z",
      "updated_at": "2026-11-19T08:20:00.123456789Z"
    }
  ],
  "has_more": true,
  "next_cursor": "Y3VzXzJrRnE5QWJONHlQZFM4dU1xWDVpWmMwdEVmQnwxNzk1MDc2NDAwMTIzNDU2Nzg5"
}
```

Para a página seguinte, repita o pedido com `after=Y3VzXzJrRnE5QWJONHlQZFM4dU1xWDVpWmMwdEVmQnwxNzk1MDc2NDAwMTIzNDU2Nzg5`. Trate o cursor como texto opaco: não o descodifique nem o construa à mão.

## Percorrer todas as páginas

```javascript
let after = "";
let customers = [];
do {
  const url = new URL("$BUSINESS_API/customers");
  url.searchParams.set("limit", "100");
  if (after) url.searchParams.set("after", after);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.API_KEY}` } });
  if (res.status >= 400) throw new Error(`HTTP ${res.status}`);
  const page = await res.json();
  customers = customers.concat(page.data);
  after = page.has_more ? page.next_cursor : "";
} while (after);
```

```python
import os, requests

after = None
customers = []
while True:
    params = {"limit": 100}
    if after:
        params["after"] = after
    res = requests.get(
        "$BUSINESS_API/customers",
        params=params,
        headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    )
    res.raise_for_status()
    page = res.json()
    customers.extend(page["data"])
    if not page["has_more"]:
        break
    after = page["next_cursor"]
```

Na linha de comandos, `gotactl customers list --all` segue as páginas por si, e `gotactl api GET business:/customers --paginate` faz o mesmo para qualquer listagem.

## Erros de paginação

Um cursor que o servidor não consegue descodificar, normalmente por ter sido alterado ou copiado de forma incompleta, é recusado com `400` e `error_code: "request.cursor_invalid"`; recomece a partir da primeira página. Nas listagens de clientes, um `limit` que não seja um número inteiro não negativo também devolve `400`, com `error_code: "request.invalid"`; corrija o valor e repita o pedido. O formato completo dos erros está em [Erros](/docs/getting-started/errors).

## Próximos passos

- [Filtrar e pesquisar nas listagens](/docs/getting-started/expanding-filtering)
- [Importar clientes em lote](/docs/guides/import-customers)
- [Referência da Business API](/docs/api/business)

