// referência

Paginação

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

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.

bash

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

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

bash

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

json

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

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

json

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

Paginação

Paginação

Query params

Envelope de resposta

Variante "últimos N": logs e DLQ de webhooks

Próximos passos

Emitir NFe

Erros e Rejeições