Konventionen
Diese Konventionen gelten für die produktive Partner-Schnittstelle. Jede Quickstart verlinkt hierher, statt sie zu wiederholen.
- Zeitstempel: ISO-8601, Standard-Zeitzone Berlin
- Alle Zeitstempel sind ISO-8601-formatiert. Ohne explizite Zeitzone gilt Europe/Berlin als Standard. Zeitfelder in Antworten enthalten immer einen Offset.
- 2026-07-05T14:30:00+02:00
- Geldbeträge: Cent-Zahl und Euro-Anzeige im Zwilling
- Jeder Geldbetrag kommt als ganzzahlige Cent-Zahl (amountCents) UND als formatierter Euro-String zur Anzeige. Rechne immer mit der Cent-Zahl, nie mit dem formatierten String.
- { "amountCents": 349, "amountDisplay": "3,49 €" }
- Idempotenz: clientOrderId und isReplay
- Jeder Versand-Aufruf trägt eine selbst gewählte clientOrderId. Ein wiederholter Aufruf mit derselben clientOrderId liefert dieselbe Antwort zurück und erzeugt keinen zweiten Versand. Die Antwort markiert eine Wiederholung mit isReplay: true, sodass ein Agent nach einem Timeout gefahrlos erneut aufrufen kann.
- { "clientOrderId": "agent-2026-07-05-001", "isReplay": false }
- dryRun auf jedem verändernden Tool
- Jedes Tool, das einen Zustand ändert (mutating: true), akzeptiert dryRun: true. Damit laufen alle sechs Versand-Prüfungen und die Kostenschätzung, ohne dass ein Brief, eine Buchung oder eine Freigabe entsteht. So probierst du eine Anfrage gefahrlos aus, bevor du sie scharf schaltest.
- { "dryRun": true }
- Token-Rechte: fest ab dem Erzeugen, kein Nachrüsten
- Die Rechte werden beim Erzeugen fest in den Token geschrieben. Sie wachsen später nicht mit: Wenn ein Token mehr können soll, erzeuge im Dashboard unter /dashboard/tokens einen neuen Token oder nutze dort "Ersetzen". Beim Ersetzen wird der alte Token im selben Schritt widerrufen, es gibt keine Übergangsfrist. Bei einer OAuth-Verbindung entspricht das einer neuen Autorisierung, nicht einem Refresh. Fehlt einem Aufruf ein Recht, antwortet der Server mit FORBIDDEN_SCOPE und nennt das fehlende Recht und das Tool.
- FORBIDDEN_SCOPE -> neuen Token mit dem fehlenden Recht erzeugen
Vertrauen und Live-Status
Maschinenlesbare Servicefakten und der aktuelle Betriebsstatus der Partner-Schnittstelle stehen jederzeit offen zur Verfügung, ohne Login.