Paginação

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`

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.

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

Envelope de resposta

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

Variante “últimos N”: logs e DLQ de webhooks

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)

curl "https://api.engineapi.com.br/v1/webhooks/logs?limit=50" \
  -H "Authorization: Bearer SEU_TOKEN"

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

curl "https://api.engineapi.com.br/v1/webhooks/dlq?limit=50" \
  -H "Authorization: Bearer SEU_TOKEN"

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

Próximos passos

Emitir NF-e: GET /v1/nfe usa este mesmo contrato de paginação.
Erros e Rejeições: envelope de erro e catálogo completo de códigos.

Comece aqui

Emissão

Tributação

Erros e operação

IA e automação

Conceitos

Migração

Perguntas frequentes

Query params

Envelope de resposta

Variante “últimos N”: logs e DLQ de webhooks

Próximos passos

​Query params

​Envelope de resposta

​Variante “últimos N”: logs e DLQ de webhooks

​Próximos passos

Query params

Envelope de resposta

Variante “últimos N”: logs e DLQ de webhooks

Próximos passos