Konventionen

Anfragen und Antworten

GET liest. Antworten sind JSON, mit Feldnamen auf Englisch in snake_case. Jede Antwort trägt Cache-Control: no-store. Jedes Objekt hat ein Feld object, das sagt, was es ist (charge, payment, event…).

Beträge

Beträge sind ganze Zahlen in der kleinsten Einheit ihrer Währung (ISO 4217), mit der Währung daneben: 300,00 € ist 30000 mit currency: "EUR"; 3.000 ¥ ist 3000; 25,500 KWD ist 25500.

Jeder Betrag ist der Gesamtbetrag, den der Kunde zahlt (amount_basis: "gross"): Wenn Stable Pro die MwSt. berechnet, ist sie im Gesamtbetrag enthalten, und Stable Pro gibt Nettobetrag und Steuer daneben an. Ein Programm, das seine eigene Steuer auf einen Betrag von Stable Pro anwendet, leitet sie aus diesem Gesamtbetrag ab; es schlägt sie nicht auf.

Beträge haben ein Vorzeichen, wo die Richtung zählt: Eine Korrektur, die eine Belastung senkt, ist negativ, eine Erstattung ist negativ.

Datumsangaben

• Kalenderdaten (Fälligkeiten, Zeiträume, das Datum einer Zahlung) sind YYYY-MM-DD; Monate sind YYYY-MM.
• Zeitpunkte (created_at, issued_at, occurred_at…) sind RFC 3339 in UTC: 2026-11-10T14:32:05.120Z.
• Den Buchungsmonat (accounting_month) berechnet Stable Pro in der Zeitzone des Stalls: Es ist der spätere aus Leistungsmonat und dem Monat, in dem der Vorgang erfasst wurde. Sie müssen nie eine Zeitzonenrechnung machen.

Zeitzone, Währung, Land und Sprache des Stalls stehen in GET /organization.

Codes, keine Texte

Der Vertrag liefert Codes – action, reason, category, origin, Belastungsarten, Ereignistypen – nie Sätze in einer Sprache. Namen für Menschen kommen aus dem Wörterbuch, in der angefragten Sprache:

curl "https://app.stable-pro.com/api/v1/codes?lang=de" -H "Authorization: Bearer sp_live_…"

GET /codes listet jede Familie von Codes, wo jede Familie vorkommt (fields, etwa adjustment.reason) und einen name je Code. Der Name eines reason hängt von seiner action ab: Schlagen Sie ihn mit beiden nach.

Codelisten sind offen: Ein neuer Wert kann innerhalb von v1 hinzukommen. Ihre Integration muss einen Code akzeptieren, den sie noch nicht kennt (und kann seinen Namen aus /codes lesen). taxonomy_version sagt, welche Version der Korrektur-Taxonomie eine Zeile erzeugt hat.

Wo es eine Standardliste gibt, wird sie verwendet: Währung ISO 4217, Land ISO 3166-1 und Unterteilung ISO 3166-2 (IT-MI, US-OH), Steuernummern mit einem Schema nach ISO 6523, Steuerkategorie UNCL 5305 (S, Z, E, AE, K, G, O), Einheiten UNECE Rec. 20 (MON, ANN, C62).

Steuern

Jede Belastung und jede Korrektur gibt an:

• tax_calculated_by: stable_pro (Stable Pro berechnet die MwSt. und gibt sie an) oder external – das heißt nur, dass Stable Pro sie nicht berechnet: Es heißt nicht, dass die Steuer null ist;
• tax_treatment: standard_rated, zero_rated, not_calculated oder undetermined (ein älterer Vorgang, bei dem es nicht bekannt ist);
• taxable_amount und taxes[]: eine Liste, auch mit nur einem Element – { type, jurisdiction, category, rate_bp, amount }. Steuersätze sind in Basispunkten angegeben: 22 % ist 2200.

Eine Belastung wird so gelesen, wie sie jetzt ist: Ihr Betrag und ihre Steuern sind ihre Entstehung, plus ihre Korrekturen, plus jede spätere Steueränderung.

Listen

Eine Liste enthält alle Vorgänge ihrer Art, bezahlt oder nicht: GET /charges sind alle Belastungen an die Kunden (nie die Vergütungen der Mitarbeitenden), GET /customers sind alle mit mindestens einer Belastung, Mitglieder oder Mitarbeitende.

Listen arbeiten mit einem Cursor:

GET /charges?limit=100&starting_after=<ID des zuletzt gelesenen Elements>

• limit von 1 bis 100 (25, wenn es fehlt);
• die Hülle ist { "object": "list", "data": [...], "has_more": true }; fragen Sie erneut mit starting_after = die id des letzten Elements;
• die Reihenfolge ist immer vom ältesten an: created_at, dann id (Quittungen: issued_at, dann id).

Filter

Manche Listen lassen sich mit Filtern eingrenzen; sie gelten zusammen, mit limit und mit dem Cursor. Zum Beispiel die Belastungen eines Kunden in einem Monat:

GET /charges?customer=<ID des Kunden>&accounting_month=2026-10

customer, charge und payment erwarten eine ID; accounting_month erwartet YYYY-MM und ist der Buchungsmonat, der Monat, in dem der Vorgang zählt (siehe „Datumsangaben“ oben).

Unbekannte Parameter und ungültige Werte

Ein Parameter, den der Endpunkt nicht kennt, wird nie ignoriert: Die Antwort ist 400 invalid-request, und invalid_param nennt ihn. So liefert ein falsch geschriebener Filter (accountingmonth statt accounting_month) nie die ganze Liste. Dasselbe gilt für ein limit, einen Cursor oder einen Filter mit ungültigem Wert. Schlüssel und Berechtigungen werden zuerst geprüft: Ohne Schlüssel bleibt die Antwort 401, ohne Berechtigung 403.

Listen dienen zum Suchen und Prüfen; um synchron zu bleiben, lesen Sie die Ereignisse (Ereignisse).

Sprachen

Der Vertrag ist auf Englisch und ändert sich nie mit der Sprache. Sätze für Menschen – das detail eines Fehlers, die Namen in /codes – kommen in der angefragten Sprache: ?lang= hat Vorrang vor Accept-Language; ohne beides Englisch. Verfügbar: en, it, fr, de, es. Die Antwort nennt die Sprache in Content-Language.

Versionen

Die Version steht im Pfad: /api/v1/. Innerhalb von v1 gibt es nur Ergänzungen: ein neues Feld, einen neuen Endpunkt, einen neuen Wert einer Codeliste. Alles, was eine Integration brechen würde, ist eine v2, mit mindestens einem Jahr Parallelbetrieb und den Headern Deprecation und Sunset.

Quittungen sind keine Steuerdokumente

Quittungen von Stable Pro bestätigen eine Zahlung (fiscal_document: false). Das Steuerdokument stellt Ihr Programm aus. Der Stall kann wählen, seinen Kunden keine Quittungen von Stable Pro zu geben, solange Ihr Programm verbunden ist: GET /organization sagt das in receipts_shown_to_customers. Die Quittungen gibt es trotzdem, nummeriert, und Sie können sie lesen.