Facturino / Documentation / Pagination

Pagination

Tous les endpoints qui retournent une liste utilisent une pagination par curseur (cursor-based) inspirée du modèle Stripe. C'est plus robuste qu'une pagination par offset : les résultats restent stables même si de nouveaux documents sont créés pendant le parcours.

Paramètres

ParamètreTypeDescription
limitintegerNombre d'éléments par page. Défaut : 25, maximum : 100.
starting_afterstringCurseur — ID du dernier élément de la page précédente. Renvoie les éléments suivants.

La pagination est unidirectionnelle (du plus récent au plus ancien). Pour revenir à une page antérieure, reparcourez la chaîne de curseurs depuis le début — ou conservez les curseurs des pages déjà visitées côté client.

Exemple

Premier appel :

$ curl "https://facturino.com/api/v1/invoices?limit=25" \
  -H "Authorization: Bearer fac_test_..."

Réponse :

{
  "object": "list",
  "data": [
    { "id": "inv_a1b2c3", "object": "invoice", /* ... */ },
    { "id": "inv_d4e5f6", "object": "invoice", /* ... */ }
  ],
  "has_more": true,
  "next_cursor": "inv_d4e5f6",
  "url": "/v1/invoices"
}

Page suivante — utilisez l'ID du dernier élément retourné :

$ curl "https://facturino.com/api/v1/invoices?limit=25&starting_after=inv_d4e5f6" \
  -H "Authorization: Bearer fac_test_..."

Format de réponse

ChampDescription
objectToujours "list"
dataTableau des éléments de la page
has_moretrue s'il existe au moins une page suivante.
next_cursorID du dernier élément de la page actuelle (à passer dans starting_after pour la page suivante). Non-null si has_more est true.
urlChemin canonique de l'endpoint, pour faciliter le debug.

Ordre des résultats

Par défaut, les listes sont retournées du plus récent au plus ancien (par created décroissant). Cet ordre est garanti stable même en cas d'inserts simultanés, contrairement à une pagination par offset.

Certains endpoints exposent un paramètre order ou sort pour personnaliser le tri — consultez la référence interactive pour les endpoints concernés.

Combiner avec des filtres

Les paramètres de filtrage (status, customerId, date_from, date_to…) se combinent avec la pagination. Le curseur reste valide tant que les filtres ne changent pas entre deux appels.

Exemple : toutes les factures payées sur avril 2026 :

GET /v1/invoices?status=paid&date_from=2026-04-01&date_to=2026-05-01&limit=100

Ne pas changer les filtres entre deux pages. Si vous modifiez status ou customerId au milieu d'un parcours, le curseur peut pointer vers un élément qui n'est plus dans la liste — vous obtiendrez alors une page vide même si des résultats existent. Repartez de zéro après tout changement de filtre.

Pagination via les SDKs

Tous les SDKs officiels exposent à la fois la pagination manuelle et une auto-pagination (iterator).

Node.js :

// Pagination manuelle
let cursor = undefined
do {
  const page = await facturino.invoices.list({
    limit: 100,
    startingAfter: cursor,
  })
  for (const invoice of page.data) {
    process(invoice)
  }
  cursor = page.has_more ? page.next_cursor : undefined
} while (cursor)

// Auto-pagination avec async iterator
for await (const invoice of facturino.invoices.listAll({ status: 'paid' })) {
  process(invoice)
}

Python :

# Pagination manuelle
cursor = None
while True:
    page = client.invoices.list(limit=100, starting_after=cursor)
    for invoice in page.data:
        process(invoice)
    if not page.has_more:
        break
    cursor = page.next_cursor

# Auto-pagination
for invoice in client.invoices.list_all(status="paid"):
    process(invoice)

PHP :

$cursor = null;
do {
    $page = \Facturino\Invoice::all([
        'limit' => 100,
        'starting_after' => $cursor,
    ]);
    foreach ($page->data as $invoice) {
        process($invoice);
    }
    $cursor = $page->hasMore ? $page->nextCursor : null;
} while ($cursor);

Bonnes pratiques

  • Utilisez limit=100 pour les parcours massifs — moins de round-trips réseau.
  • Persistez le curseur en cas de processus long. Reprenez là où vous vous étiez arrêté plutôt que de tout reparser.
  • Ne stockez pas les curseurs longtemps — un document supprimé peut invalider un curseur. Utilisez-les pour des opérations courtes (< 24 h).
  • Préférez les webhooks au polling pour suivre les changements de statut en temps réel — voir Webhooks.

Étapes suivantes