Aller au contenu

Pagination des listes

Les listes (GET /v1/mailings, GET /v1/requests) sont paginées par curseur, du plus récent au plus ancien. Le curseur est stable : un élément ajouté pendant votre parcours ne crée ni doublon ni trou.

  • limit : nombre d’éléments par page, de 1 à 100 (20 par défaut).
  • cursor : la valeur nextCursor de la page précédente. Absent : première page.
Requête
curl "https://api.vitef.com/v1/mailings?limit=2" \
  -H "Authorization: Bearer $VITEF_API_KEY"
Réponse 200
{
  "data": [
    {
      "title": "Lettre de résiliation SFR",
      "mode": "ar",
      "modeLabel": "Recommandé avec AR",
      "status": "posted",
      "statusLabel": "Remise à La Poste",
      "step": 2,
      "lastStep": 5,
      "trackingNumber": "1A15760000001",
      "createdAt": "2026-09-23T10:00:00.000Z",
      "events": [
        {
          "step": 0,
          "status": "paid",
          "label": "Payée",
          "at": "2026-09-23T10:00:00.000Z"
        },
        {
          "step": 1,
          "status": "printed",
          "label": "Imprimée",
          "at": "2026-09-23T10:00:00.000Z"
        },
        {
          "step": 2,
          "status": "posted",
          "label": "Remise à La Poste",
          "at": "2026-09-23T10:00:00.000Z"
        }
      ],
      "id": "e1209b63-3764-49e3-bf9c-154e9be830da",
      "orderId": null,
      "recipient": [
        "SFR Résiliation",
        "TSA 30103",
        "69947 Lyon Cedex 20"
      ],
      "amountCents": 0,
      "reference": "BAIL-2026-042",
      "test": true,
      "proofs": [
        {
          "kind": "filing",
          "label": "Preuve de dépôt"
        }
      ],
      "document": "… (lettre envoyée)"
    },
    {
      "title": "Lettre de résiliation SFR",
      "mode": "ar",
      "modeLabel": "Recommandé avec AR",
      "status": "paid",
      "statusLabel": "Payée",
      "step": 0,
      "lastStep": 5,
      "trackingNumber": "1A15760000001",
      "createdAt": "2026-09-23T10:00:00.000Z",
      "events": [
        {
          "step": 0,
          "status": "paid",
          "label": "Payée",
          "at": "2026-09-23T10:00:00.000Z"
        }
      ],
      "id": "0b7e4f2a-91c3-4d58-b6a0-2f8e3c1d9a47",
      "orderId": null,
      "recipient": [
        "SFR Résiliation",
        "TSA 30103",
        "69947 Lyon Cedex 20"
      ],
      "amountCents": 0,
      "reference": "BAIL-2026-041",
      "test": true,
      "proofs": [],
      "document": "… (lettre envoyée)"
    }
  ],
  "nextCursor": "WyIyMDI2LTA5LTIzVDA5OjQwOjAwLjAwMFoiLCIwYjdlNGYyYS05MWMzLTRkNTgtYjZhMC0yZjhlM2MxZDlhNDciXQ",
  "hasMore": true
}

hasMore vaut true tant qu’il reste des éléments ; nextCursor est alors à passer dans cursor, il vaut null à la dernière page. Le curseur est opaque : ne le décodez pas, ne le construisez pas. Illisible : 400 invalid_cursor.

Parcourir toute la liste

let cursor = null;
do {
  const url = new URL('https://api.vitef.com/v1/mailings');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.VITEF_API_KEY}` } });
  const page = await res.json();
  for (const mailing of page.data) console.log(mailing.id, mailing.status);
  cursor = page.nextCursor;
} while (cursor);
import os
import requests

cursor = None
while True:
    params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
    r = requests.get("https://api.vitef.com/v1/mailings", params=params, headers={"Authorization": f"Bearer {os.environ['VITEF_API_KEY']}"}, timeout=30)
    r.raise_for_status()
    page = r.json()
    for mailing in page["data"]:
        print(mailing["id"], mailing["status"])
    cursor = page["nextCursor"]
    if not cursor:
        break

Filtres

GET /v1/mailings accepte aussi reference (votre référence, à l’identique) et status (paid, posted, delivered…).