---
title: "Paginación y filtros"
description: "Convención para list endpoints: pageNumber, pageSize y search; respuesta PagedResult con items, totalCount y totalPages."
canonical: https://factura.com.do/desarrolladores/paginacion
lang: es
generator: factura.com.do docs-index
---

Convenciones 

# Paginación y filtros

Casi todos los list endpoints aceptan los mismos tres query params y devuelven la misma forma de `PagedResult<T>`. Aprendes una vez e integras en todos los recursos paginados; las dos excepciones (`units` y `payment-terms`) están descritas abajo.

## Resumen

La paginación es **offset-based**: `pageNumber` y `pageSize`. La respuesta incluye `totalCount` y `totalPages` precomputado. Filtros adicionales (`isActive` en clientes, proveedores y productos) están documentados en cada página de recurso si aplica. `GET /api/v1/units` devuelve la lista completa sin `PagedResult`; `GET /api/v1/payment-terms` extiende la forma con `lastModification`.

## Query params

| Param      | Tipo   | Default | Descripción                                                                    |
| ---------- | ------ | ------- | ------------------------------------------------------------------------------ |
| search     | string | —       | Texto de búsqueda libre. Cada recurso define los campos sobre los que matchea. |
| pageNumber | int    | 1       | 1-indexado.                                                                    |
| pageSize   | int    | 10      | Tamaño de página. Sin máximo publicado.                                        |

## Forma de respuesta

La forma `PagedResult<T>` es la misma en facturas, notas, compras, gastos, contactos, productos, impuestos, retenciones y monedas. `totalCount` es el conteo total sin filtro de paginación y `totalPages` ya viene calculado por la API.

paged-result.json

```

{

  "items": [

    {

      "customerId": "5f0c3a8e-2b7d-4c1e-9a6f-3d8b2e1c7a40",

      "legalName": "Empresa Receptora SRL",

      "taxIdentification": "131000001"

    }

  ],

  "totalCount": 87,

  "pageNumber": 2,

  "pageSize": 50,

  "totalPages": 2

}


```

## Ejemplo

Listar la segunda página de clientes con tamaño 50, filtrando por la palabra `industrial`.

GET /api/v1/customers

cURL TypeScript 

list-customers.sh

```

curl "https://tuempresa.factura.com.do/api/v1/customers?pageNumber=2&pageSize=50&search=industrial" \

  -H "X-Api-Key: $FACTURA_API_KEY"


```

list-customers.ts

```

const params = new URLSearchParams({

  pageNumber: "2",

  pageSize: "50",

  search: "industrial",

});


const res = await fetch(

  `https://tuempresa.factura.com.do/api/v1/customers?${params}`,

  { headers: { "X-Api-Key": process.env.FACTURA_API_KEY! } },

);

if (!res.ok) throw new Error(`factura.com.do: ${res.status}`);

const { items, totalCount, pageNumber, pageSize, totalPages } = await res.json();


```

Si superas un tamaño razonable, parte el trabajo

No publicamos un máximo formal de `pageSize`. Para sincronizaciones masivas, parte la carga en bloques de 100 a 250 ítems y aprovecha `totalCount` de la primera respuesta para calcular cuántas páginas vienen.

## Siguientes pasos

Siguiente paso 

## Continúa por aquí

- [  Catálogo El recurso con más list endpoints paginados (productos, impuestos, monedas). ](/desarrolladores/catalogo)
- [  Contactos Lista clientes y proveedores con search por nombre o RNC. ](/desarrolladores/contactos)
- [  Errores Cómo reacciona la API si pageSize o pageNumber están fuera de rango. ](/desarrolladores/errores)