Paginação

As novas listagens REST em /v2 e as ferramentas MCP paginadas retornam data e pagination. As rotas /v1 continuam ativas com seus contratos anteriores, permitindo migrar cada integração separadamente. Os campos de cada registro mantêm sua serialização. Metadados específicos, como totais financeiros e resumos de instalações ou avaliações, ficam em meta. Ao migrar para /v2, adapte integrações que liam o array diretamente ou campos como inputs, cash_flows, items e clients.

{
  "data": [{ "id": 42 }],
  "pagination": {
    "count": 1,
    "limit": 50,
    "total": null,
    "has_more": true,
    "next": { "cursor": "cursor-retornado-pela-api" }
  }
}

count informa quantos registros a página contém. limit é o tamanho máximo. total informa o total filtrado quando disponível; null significa que não houve contagem global. No cardápio MCP, count e limit contam produtos dentro dos grupos de marcas e categorias.

Mantenha os filtros originais e acrescente os parâmetros de pagination.next a cada requisição. Encerre quando has_more=false e next=null. Nunca interprete a primeira página como o conjunto completo.

Sessões são ordenadas por ID crescente. O cursor fica vinculado ao restaurante, período, marcas e entregador. Trocar esses filtros exige começar sem cursor. As datas inicial e final continuam obrigatórias, inclusivas e em UTC. Na V2 e no MCP não há limite de dias; a V1 mantém seu array completo e limite de três dias inteiros. Períodos invertidos retornam uma página vazia na V2 e [] na V1. A paginação é uma leitura em tempo real; não representa um snapshot imutável.

Os totais de meta.totals no financeiro cobrem o período e os filtros inteiros, inclusive quando data contém apenas uma página. Não some novamente filhos de notas ou títulos ao total principal.

Migração gradual

Use o versionamento de URI do NestJS: substitua /v1 por /v2 somente nas listagens que oferecem a nova versão. Os mesmos tokens, escopos e filtros de restaurante continuam válidos. Leia os registros em data e siga pagination.next. Os detalhes e as escritas continuam nas rotas já publicadas em /v1.

O MCP já usa as consultas paginadas diretamente, sem chamar as rotas REST. Não é necessário migrar uma integração REST para o MCP receber páginas. A V1 permanece disponível; esta entrega não define uma data de remoção.