Novità

Ogni fatto economico di una scuderia ha la sua novità (un oggetto event): un addebito creato, una correzione, un incasso che arriva, una ricevuta emessa o annullata, i dati di un cliente che cambiano. Le novità le scrive il database nella stessa transazione del fatto, e sono numerate nell'ordine in cui diventano visibili.

GET /events?after=<cursore>&limit=100

La garanzia

Se una novità è visibile, ogni novità precedente della stessa scuderia è già visibile, o non esisterà mai.

Quindi leggere «tutto ciò che viene dopo il mio cursore» non salta mai niente: nessuna novità precedente può comparire più tardi. Nella numerazione possono esserci dei buchi (una transazione annullata), e non fanno danni, perché non chiedi mai «il numero successivo».

Come leggere

1. La prima volta chiama GET /events senza after: parti dalla prima novità della scuderia, storia compresa.
2. Elabora ogni novità in ordine: leggi l'oggetto a cui punta (data.url) e fai il tuo lavoro.
3. Quando la pagina è elaborata, salva next_cursor.
4. Chiama di nuovo con after=<next_cursor>. Ripeti finché has_more è true; quando è false, aspetta e richiedi più tardi (per esempio ogni pochi minuti).

{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "6f1d1e0c-…",
      "type": "adjustment.created",
      "data": { "object": "adjustment", "id": "8d0c2f6e-…", "url": "/api/v1/adjustments/8d0c2f6e-…" },
      "occurred_at": "2026-12-05T09:14:03.512Z",
      "recorded_at": "2026-12-05T09:14:03.540Z",
      "historical": false
    }
  ],
  "has_more": false,
  "next_cursor": "6f1d1e0c-…"
}

• Le novità sono leggere: dicono quale oggetto è stato creato o cambiato, mai gli importi. Leggi l'oggetto.
• Almeno una volta: dopo un'interruzione riparti dall'ultimo cursore che hai salvato, e può capitare di leggere una pagina due volte. Elaborare di nuovo una novità non fa danni — punta a un fatto che non cambia, o ai dati attuali di un cliente — e l'id della novità ti fa riconoscere quelle già elaborate. Gli id delle novità sono unici fra tutte le scuderie.
• next_cursor può essere l'id di una novità che non ti viene mostrata: salvalo sempre così com'è.
• has_more: true con meno di limit novità — anche nessuna — vuol dire che alcune novità non erano per te e il registro continua: chiedi di nuovo.
• Un cursore che non è una novità di questa scuderia è un 400 su after.

Tipi di novità

Ogni novità si vede solo col permesso dell'oggetto a cui punta. Si vede solo il lato da incassare, cioè quello che i clienti devono alla scuderia, pagato o no: i compensi dello staff non compaiono mai. Non esiste customer.created: un cliente nasce col suo primo addebito, e charge.created porta il suo customer_id. L'elenco dei tipi è aperto: accetta un tipo che ancora non conosci. I nomi in ogni lingua sono in /codes (event_type).

Se la tua chiave ottiene un permesso nuovo, le novità che prima non vedeva stanno dietro il tuo cursore: rileggi dall'inizio (senza after) per averle.

La storia

Quando una scuderia comincia a usare l'API, tutta la sua storia è già nel registro: le novità dei fatti di prima portano historical: true, sono in ordine di data del fatto e vengono prima di ogni novità del presente. occurred_at è sempre la data del fatto; recorded_at è quando la novità è stata scritta.

Mentre la storia di una scuderia viene caricata, /events risponde 503 con type: …/events-not-ready e Retry-After. Ci vogliono pochi secondi.

Una novità sola

GET /events/{id} restituisce una novità, con le stesse regole. Una novità di un'altra scuderia, di un tipo che la tua chiave non può leggere, o che non esiste: 404.