# Listas y paginación

> Recorra facturas, clientes o eventos página por página con limit y starting_after.

Las rutas que listan (`GET /v1/invoices`, `GET /v1/customers`, `GET /v1/events`…) contestan una página, la más reciente primero:

```json
{
  "object": "list",
  "data": [{ "id": "inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg", "object": "invoice", "...": "..." }],
  "has_more": true,
  "url": "/v1/invoices"
}
```

| Parámetro | Qué hace |
| --- | --- |
| `limit` | Cuántos por página, de 1 a 100. Por omisión 10. |
| `starting_after` | El `id` del último objeto de la página anterior: la siguiente empieza después de él. |

Mientras `has_more` sea `true` hay más: pida la siguiente con el `id` del último de `data`.

```bash tab="cURL"
curl -G https://api.fiscalisto.com/v1/invoices \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -d limit=100 \
  -d starting_after=inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg
```

```ts tab="TypeScript"
import { Fiscalisto } from "fiscalisto";

// La llave viene de FISCALISTO_API_KEY.
const fiscalisto = new Fiscalisto();

for await (const item of fiscalisto.invoices.list({
  limit: 100,
  starting_after: "inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg",
})) {
  console.log(item.id);
}
```

```python tab="Python"
from fiscalisto import Fiscalisto

# La llave viene de FISCALISTO_API_KEY.
fiscalisto = Fiscalisto()

for item in fiscalisto.invoices.list({
    "limit": 100,
    "starting_after": "inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg",
}):
    print(item["id"])
```

```php tab="PHP"
<?php

use Fiscalisto\Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
$fiscalisto = new Fiscalisto();

foreach ($fiscalisto->invoices->list([
    'limit' => 100,
    'starting_after' => 'inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg',
]) as $item) {
    echo $item['id'], "\n";
}
```

```go tab="Go"
package main

import (
	"context"
	"fmt"
	"log"

	fiscalisto "fiscalisto.com/go"
)

func main() {
	// La llave viene de FISCALISTO_API_KEY.
	client, err := fiscalisto.NewClient("")
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	for item, err := range client.Invoices.ListAutoPaging(ctx, &fiscalisto.ListInvoicesParams{
		Limit:         fiscalisto.Int64(100),
		StartingAfter: fiscalisto.String("inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg"),
	}) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(item.ID)
	}
}
```

```java tab="Java"
import com.fiscalisto.FiscalistoClient;
import com.fiscalisto.model.ListInvoicesParams;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

for (var item : fiscalisto.invoices().listAutoPaging(new ListInvoicesParams()
        .setLimit(100)
        .setStartingAfter("inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg"))) {
    System.out.println(item.getId());
}
```

```csharp tab="C#"
using Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

await foreach (var item in fiscalisto.Invoices.ListAutoPagingAsync(new ListInvoicesParams
{
    Limit = 100,
    StartingAfter = "inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg",
}))
    Console.WriteLine(item.Id);
```

```js title="todas-las-facturas.js"
async function* facturas(filtros = {}) {
  let startingAfter;
  while (true) {
    const q = new URLSearchParams({ limit: "100", ...filtros });
    if (startingAfter) q.set("starting_after", startingAfter);
    const res = await fetch(`https://api.fiscalisto.com/v1/invoices?${q}`, {
      headers: { Authorization: `Bearer ${process.env.FISCALISTO_API_KEY}` },
    });
    const page = await res.json();
    yield* page.data;
    if (!page.has_more) return;
    startingAfter = page.data.at(-1).id;
  }
}

for await (const f of facturas({ status: "valid", created_gte: "2026-10-01" })) {
  console.log(f.uuid, f.total);
}
```

Las páginas no se saltan ni repiten objetos aunque se creen otros mientras recorre la lista.

## Filtros

Cada lista tiene los suyos, por ejemplo:

- Facturas: `issuer`, `status`, `type` (I, E, P, T o N), `customer` (RFC del cliente), `created_gte` y `created_lte`.
- Constancias de retenciones: `issuer`, `status`, `recipient` (RFC) y `year`.
- Clientes: `tax_id`. Productos: `sku` y `product_key`.
- Eventos: `type` (`invoice.stamped`…) y `object` (el id del comprobante, para ver todo lo que le pasó).

Las listas de comprobantes, clientes, productos, empleados y lotes son de un emisor: mande `issuer` si la cuenta tiene varios. Los catálogos del SAT (`q` busca por clave o descripción) y los anticipos contestan una sola lista, sin páginas.

La [referencia](https://fiscalisto.com/docs/api/referencia/facturas/list-invoices) de cada ruta dice cuáles acepta.