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

# Paginação

> Contrato de paginação usado nos endpoints de listagem da engineAPI: page, limit, sortBy, sortOrder e o envelope de resposta.

Os endpoints de listagem da engineAPI (`GET /v1/nfe`, `GET /v1/nfce`, `GET /v1/nfse`)
compartilham o **mesmo contrato** de paginação: os mesmos query params, a mesma
validação, o mesmo envelope de resposta.

## Query params

| Param       | Tipo   | Default     | Regra                                                                     |
| ----------- | ------ | ----------- | ------------------------------------------------------------------------- |
| `page`      | número | `1`         | Mínimo `1`                                                                |
| `limit`     | número | `20`        | Entre `1` e `100`                                                         |
| `sortBy`    | string | `createdAt` | Whitelist fixa (ver abaixo). Valor fora dela cai no default, **sem erro** |
| `sortOrder` | string | `desc`      | `asc` ou `desc`                                                           |

<Info>
  `sortBy` tem uma whitelist de campos permitidos: `createdAt`, `updatedAt`, `number`,
  `amount`, `status`, `vencimento`, `name`. Mandar um valor fora dela **não é erro**: a
  engineAPI silenciosamente ordena por `createdAt` em vez de rejeitar a requisição.
</Info>

```bash theme={null}
curl "https://api.engineapi.com.br/v1/nfe?page=1&limit=20&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer SEU_TOKEN"
```

## Envelope de resposta

```json theme={null}
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "AUTHORIZED",
      "accessKey": "35260211222333000181550010000000011000000019",
      "number": 1,
      "series": 1
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 137,
    "totalPages": 7,
    "hasNext": true,
    "hasPrev": false
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-07-20T18:00:00.000Z"
  }
}
```

`data[]` traz os itens da página atual; `pagination` traz os metadados de paginação;
`meta` é o mesmo envelope padrão de toda resposta da engineAPI. `limit` acima do teto
(`> 100`) ou `page`/`limit` inválidos (`?page=abc`) nunca viram `500`: a engineAPI
sempre clampa para dentro dos limites válidos antes de consultar o banco.

<h2 id="variante-ltimos-n-logs-e-dlq-de-webhooks">
  Variante "últimos N": logs e DLQ de webhooks
</h2>

Os endpoints de **histórico de entregas** e **Dead Letter Queue** de webhooks são a
exceção: não paginam por `page`, só devolvem os últimos N registros por `limit`
(`1`-`100`, default **`50`**, diferente do default `20` da paginação completa). Sem
`sortBy`/`sortOrder` (ordenação fixa: mais recente primeiro) e **sem** o campo
`pagination` no envelope. Os dois endpoints, porém, não têm o mesmo shape entre si:

| Endpoint                | `limit` default | Shape de `data`                                |
| ----------------------- | --------------- | ---------------------------------------------- |
| `GET /v1/webhooks/logs` | `50`            | Array puro dos deliveries                      |
| `GET /v1/webhooks/dlq`  | `50`            | Objeto `{ total, items[] }` (não é array puro) |

```bash theme={null}
curl "https://api.engineapi.com.br/v1/webhooks/logs?limit=50" \
  -H "Authorization: Bearer SEU_TOKEN"
```

```json theme={null}
{
  "data": [
    {
      "id": "9f1c2b3a-...-uuid",
      "eventType": "invoice.authorized",
      "status": "delivered",
      "attempts": 1,
      "lastError": null,
      "createdAt": "2026-07-20T12:00:00.000Z",
      "deliveredAt": "2026-07-20T12:00:01.000Z"
    }
  ],
  "meta": { "requestId": "req_abc123", "timestamp": "2026-07-20T18:00:00.000Z" }
}
```

```bash theme={null}
curl "https://api.engineapi.com.br/v1/webhooks/dlq?limit=50" \
  -H "Authorization: Bearer SEU_TOKEN"
```

```json theme={null}
{
  "data": {
    "total": 3,
    "items": [
      {
        "id": "9f1c2b3a-...-uuid",
        "eventType": "invoice.authorized",
        "status": "dead_letter",
        "attempts": 5,
        "lastError": "HTTP 500: Internal Server Error",
        "createdAt": "2026-07-20T08:00:00.000Z"
      }
    ]
  },
  "meta": { "requestId": "req_abc123", "timestamp": "2026-07-20T18:00:00.000Z" }
}
```

Ver também o [guia de Webhooks](/guides/webhooks#dead-letter-queue-dlq).

## Próximos passos

* [Emitir NF-e](/guides/emitir-nfe): `GET /v1/nfe` usa este mesmo contrato de paginação.
* [Erros e Rejeições](/guides/errors): envelope de erro e catálogo completo de códigos.