Stable Pro API · v1

Ereignisse

Synchron bleiben: lesen, was nach Ihrem Cursor geschehen ist, in Reihenfolge und ohne etwas zu verlieren.

Jeder wirtschaftliche Vorgang eines Stalls hat ein Ereignis (ein Objekt event): Eine Belastung wird erstellt, eine Korrektur vorgenommen, eine Zahlung geht ein, eine Quittung wird ausgestellt oder storniert, die Daten eines Kunden ändern sich. Ereignisse schreibt die Datenbank in derselben Transaktion wie den Vorgang, und sie sind in der Reihenfolge nummeriert, in der sie sichtbar werden.

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

Die Garantie

Ist ein Ereignis sichtbar, ist jedes frühere Ereignis desselben Stalls bereits sichtbar – oder wird nie existieren.

Das Lesen von „allem nach meinem Cursor“ überspringt also nie etwas: Kein früheres Ereignis kann später auftauchen. Lücken in der Nummerierung kann es geben (eine abgebrochene Transaktion); sie sind harmlos, weil Sie nie nach „der nächsten Nummer“ fragen.

So lesen Sie

Beim ersten Mal rufen Sie GET /events ohne after auf: Sie beginnen beim ersten Ereignis des Stalls, Geschichte eingeschlossen.
Verarbeiten Sie jedes Ereignis in Reihenfolge: Lesen Sie das Objekt, auf das es verweist (data.url), und erledigen Sie Ihre Arbeit.
Wenn die Seite verarbeitet ist, speichern Sie next_cursor.
Rufen Sie erneut mit after=<next_cursor> auf. Wiederholen Sie das, solange has_more true ist; ist es false, warten Sie und fragen Sie später erneut (zum Beispiel alle paar Minuten).

{
  "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-…"
}

Ereignisse sind schlank: Sie sagen, welches Objekt erstellt oder geändert wurde, nie die Beträge. Lesen Sie das Objekt.
Mindestens einmal: Nach einer Unterbrechung beginnen Sie wieder beim zuletzt gespeicherten Cursor und lesen eine Seite womöglich zweimal. Ein Ereignis erneut zu verarbeiten schadet nicht – es verweist auf einen Vorgang, der sich nicht ändert, oder auf die aktuellen Daten eines Kunden –, und an der id des Ereignisses erkennen Sie bereits verarbeitete Ereignisse. Ereignis-IDs sind über alle Ställe hinweg eindeutig.
next_cursor kann die ID eines Ereignisses sein, das Ihnen nicht angezeigt wird: Speichern Sie ihn immer so, wie er ist.
has_more: true mit weniger als limit Ereignissen – sogar keinem – heißt, dass einige Ereignisse nicht für Sie waren und das Protokoll weitergeht: Fragen Sie erneut.
Ein Cursor, der kein Ereignis dieses Stalls ist, ergibt einen 400 auf after.

Ereignistypen

Typ	Verweist auf	Berechtigung
`customer.updated`	den Kunden	`customers:read`
`charge.created`	die Belastung	`charges:read`
`charge.due_date_changed`	die Belastung (lesen Sie ihre neue `due_date`)	`charges:read`
`charge.tax_changed`	die Belastung (lesen Sie ihre neuen Steuern)	`charges:read`
`adjustment.created`	die Korrektur	`charges:read`
`payment.created`	die Geldbewegung	`payments:read`
`allocation.created`	die Zuordnung einer Zahlung zu einer Belastung	`payments:read`
`credit_entry.created`	die Guthabenbewegung	`payments:read`
`receipt.issued`	die Quittung	`receipts:read`
`receipt.voided`	die Quittung	`receipts:read`

Jedes Ereignis wird nur mit der Berechtigung des Objekts angezeigt, auf das es verweist. Angezeigt wird nur die Seite der Forderungen, also das, was die Kunden dem Stall schulden, bezahlt oder nicht: Vergütungen der Mitarbeitenden erscheinen nie. Es gibt kein customer.created: Ein Kunde entsteht mit seiner ersten Belastung, und charge.created trägt seine customer_id. Die Liste der Typen ist offen: Akzeptieren Sie einen Typ, den Sie noch nicht kennen. Namen in jeder Sprache stehen in /codes (event_type).

Erhält Ihr Schlüssel eine neue Berechtigung, liegen die Ereignisse, die er vorher nicht sah, hinter Ihrem Cursor: Lesen Sie erneut von Anfang an (ohne after), um sie zu bekommen.

Geschichte

Wenn ein Stall beginnt, die API zu nutzen, steht seine ganze Geschichte bereits im Protokoll: Ereignisse früherer Vorgänge tragen historical: true, sind nach dem Datum des Vorgangs geordnet und kommen vor jedem Ereignis der Gegenwart. occurred_at ist immer das Datum des Vorgangs; recorded_at ist der Zeitpunkt, zu dem das Ereignis geschrieben wurde.

Während die Geschichte eines Stalls geladen wird, antwortet /events mit 503, type: …/events-not-ready und Retry-After. Es dauert Sekunden.

Ein einzelnes Ereignis

GET /events/{id} liefert ein Ereignis, mit denselben Regeln. Ein Ereignis eines anderen Stalls, eines Typs, den Ihr Schlüssel nicht lesen kann, oder eines, das nicht existiert: 404.