Stable Pro API · v1
Authentifizierung und Berechtigungen
Schlüssel, Umgebungen, Berechtigungen, Anfragelimits.
Schlüssel
Jede Anfrage trägt einen Schlüssel im Header Authorization:
Authorization: Bearer sp_live_7Kq2…
Ein Schlüssel ist sp_live_ (Produktion) oder sp_test_ (Staging), gefolgt von 40 Buchstaben und Ziffern. Der Stall ergibt sich aus dem Schlüssel: Sie übergeben nie die ID eines Stalls, und ein Schlüssel liest nur einen Stall.
Schlüssel erstellt der Inhaber des Stalls in Stable Pro unter Einstellungen → Verbindungen. Eine Verbindung ist Ihr Programm; sie kann im Lauf der Zeit mehr als einen Schlüssel haben. Der Inhaber sieht von jedem Schlüssel die letzten vier Zeichen, die letzte Verwendung und die Zahl der Anfragen, und er kann ihn jederzeit widerrufen.
- Ein Schlüssel wird nur einmal angezeigt, bei seiner Erstellung. Stable Pro speichert nur einen Fingerabdruck: Geht er verloren, erstellt der Inhaber einen neuen.
- Rotation: Erstellt der Inhaber einen neuen Schlüssel für die Verbindung, funktioniert der vorherige noch 7 Tage und dann nicht mehr. Ersetzen Sie ihn in diesem Zeitraum in Ihrem Programm.
- Ablauf: Der Inhaber kann einem Schlüssel ein Ablaufdatum geben (90 Tage, ein Jahr oder keines).
- Ein
sp_test_-Schlüssel wird in der Produktion abgelehnt, einsp_live_-Schlüssel im Staging (401,reason: wrong_environment).
Ist ein Schlüssel nicht gültig, lautet die Antwort 401 mit WWW-Authenticate: Bearer und einem reason: missing, malformed, wrong_environment, unknown, connection_revoked, revoked, expired, rotated.
GET /connection liefert die Verbindung des aufrufenden Schlüssels: ihren Namen, ihre Berechtigungen und den Schlüssel selbst (nie das Geheimnis).
Berechtigungen
Der Inhaber wählt, was die Verbindung lesen darf:
| Berechtigung | Öffnet |
|---|---|
charges:read | Belastungen und Korrekturen, den Saldo der Kunden |
payments:read | Zahlungen und Erstattungen, Zuordnungen, Guthabenbewegungen |
receipts:read | die Quittungen von Stable Pro und ihr PDF |
customers:read | die Kunden: Kennung, Art, Name, ob noch aktiv |
customers.fiscal:read | die Rechnungsdaten der Kunden: strukturierte Adresse, Steuernummern, Steuer-ID; und die Steuerdaten derjenigen, die für einen Kunden bezahlt haben |
Eine Anfrage ohne die Berechtigung ihres Endpunkts antwortet mit 403, type: …/forbidden und missing_permission. Ohne customers.fiscal:read fehlen die Rechnungsdaten in der Antwort, sie sind nicht null: Sie sind gar nicht vorhanden, verschachtelte Objekte eingeschlossen. Jedes Lesen von Rechnungsdaten wird im Anfrageprotokoll des Stalls gesondert gezählt.
/connection, /organization, /codes und /events brauchen keine bestimmte Berechtigung. Jedes Ereignis wird nur mit der Berechtigung des Objekts angezeigt, auf das es verweist (siehe Ereignisse).
Der Bereich Buchhaltung
Die API gehört zum Bereich Buchhaltung im Tarif des Stalls. Hat der Stall ihn nicht, antwortet jede Anfrage mit 403 und type: …/accounting-disabled.
Anfragelimits
| Limit | Wert | Bei Überschreitung |
|---|---|---|
| pro Schlüssel | 60 Anfragen pro Minute | 429, Retry-After: 60 |
| pro Stall | 10.000 Anfragen pro Tag | 429, Retry-After: 86400 |
Ist der Begrenzer selbst nicht verfügbar, antwortet die API mit 503 und Retry-After: 30: Sie lässt nie eine Anfrage ungeprüft durch.
Nur lesen
Version 1 liest. Sie kann in Stable Pro nichts erstellen, ändern oder löschen. Das Zurückschreiben der Dokumente, die Ihr Programm ausstellt (Nummer, Status, welche Vorgänge sie abdecken), ist die nächste Phase der API.