Paginação

Todos os endpoints de listagem seguem o mesmo padrão de paginação.

Parâmetros de query

Parâmetro	Tipo	Padrão	Descrição
page	integer	1	Número da página (começa em 1)
pageSize	integer	20	Itens por página (máx: 100)
search	string	—	Busca textual nos campos principais

Parâmetros de filtro adicionais

Cada endpoint pode aceitar filtros específicos do domínio. Por exemplo:

GET /api/properties?page=1&pageSize=20&search=centro&status=Available&type=Apartment
GET /api/payments?page=1&pageSize=50&period=2026-05&status=Pending
GET /api/contracts?page=1&pageSize=20&type=Lease

---

Formato da resposta

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "code": "AP-001",
      "status": "Available"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 45,
  "totalPages": 3,
  "hasNext": true,
  "hasPrevious": false
}

Campos do envelope de paginação

Campo	Tipo	Descrição
data	array	Itens da página atual
page	integer	Página atual
pageSize	integer	Tamanho da página
total	integer	Total de itens (sem paginação)
totalPages	integer	Total de páginas
hasNext	boolean	Existe próxima página
hasPrevious	boolean	Existe página anterior

---

Exemplos de uso

Primeira página

GET /api/properties?page=1&pageSize=20

Próxima página

GET /api/properties?page=2&pageSize=20

Com busca textual

GET /api/clients?page=1&search=João

Com múltiplos filtros

GET /api/properties?page=1&pageSize=10&status=Available&type=Apartment&search=centro

---

Implementação no Angular

O service base usa HttpParams para montar a query string:

getProperties(params: PropertyFilter): Observable<PaginatedResponse<Property>> {
  let httpParams = new HttpParams()
    .set('page', params.page?.toString() ?? '1')
    .set('pageSize', params.pageSize?.toString() ?? '20');

  if (params.search) httpParams = httpParams.set('search', params.search);
  if (params.status) httpParams = httpParams.set('status', params.status);

  return this.http.get<PaginatedResponse<Property>>(
    `${this.apiUrl}/properties`,
    { params: httpParams }
  );
}

Modelo TypeScript

// pagination.model.ts
export interface PaginatedResponse<T> {
  data: T[];
  page: number;
  pageSize: number;
  total: number;
  totalPages: number;
  hasNext: boolean;
  hasPrevious: boolean;
}

export interface PaginationParams {
  page?: number;
  pageSize?: number;
  search?: string;
}

---

Limites e recomendações

• pageSize máximo: 100 itens
• pageSize padrão: 20 itens
• Para listas com muitos registros, prefira pageSize entre 10 e 50
• O campo total reflete o total real de itens após aplicar filtros, excluindo soft-deleted
• A busca textual (search) funciona sobre os campos mais relevantes de cada recurso (nome, código, e-mail, etc.)