Dokumentation
Von der ersten Anfrage bis zum sauberen Umgang mit Fehlern: alles in einer Sprache, die man auch ohne Vorwissen versteht.
Erste Anfrage
Alle Beispiele beziehen sich auf Version 2026-07-01.
curl -s https://api.ryh.de/api/public/v1/info \
-H "Authorization: Bearer <zugriffstoken>" \
-H "X-Ryh-Tenant: <betrieb>"Platzhalter in spitzen Klammern ersetzt du durch eigene Werte. In der Dokumentation stehen bewusst keine echten Schlüssel.
API-Beschreibung herunterladen
Aktuelle Version 2026-07-01 vom 2026-07-01. Die Dateien entstehen direkt aus der veröffentlichten Schnittstelle – ohne Nacharbeit.
OpenAPI als JSON
Für Generatoren, Testwerkzeuge und eigene Anbindungen.
ryh-api-2026-07-01.openapi.json
OpenAPI als YAML
Gut lesbar für Prüfungen und die Ablage in der Versionsverwaltung.
ryh-api-2026-07-01.openapi.yaml
Versionierung
2 veröffentlichte Stände. Keine Änderung mit Anpassungsbedarf in der aktuellen Version.
- Änderung: Referenz wird generiert – Die Endpunktliste entsteht direkt aus der veröffentlichten API-Beschreibung.
- Neue Funktion: Zustellprotokoll für Webhooks – Zustellungen lassen sich einsehen und gezielt erneut auslösen.
- Sicherheitsupdate: Vorgangsschlüssel bei verändernden Aufrufen – Verändernde Aufrufe verlangen einen Vorgangsschlüssel und verhindern so Doppelbuchungen.
Umgebungen
Sandbox und Produktion sind vollständig getrennt.
Sandbox
Zum Ausprobieren. Getrennte Datenbasis, getrennte Zugänge, keine echten Gäste.
In der Sandbox liegen ausschließlich erfundene Testdaten.
Produktion
Echter Betrieb mit echten Gästen. Zugänge sind personengebunden und nachvollziehbar.
Produktive Daten dürfen niemals in die Sandbox kopiert werden.
Authentifizierung mit OAuth 2.1
Vier Abläufe für vier Situationen.
Client Credentials
Server-zu-Server-Anbindungen ohne handelnde Person.
- OAuth-Client im Entwicklerportal anlegen und Berechtigungen wählen.
- Geheimnis einmalig sichern – es wird danach nie wieder vollständig angezeigt.
- Zugriffstoken beim Autorisierungsserver anfordern.
- Token als Bearer-Token an die Schnittstelle senden.
- Nur für vertrauenswürdige Server.
- Geheimnis regelmäßig rotieren.
Authorization Code
Anwendungen, die im Namen einer angemeldeten Person handeln.
- Person zur Anmeldung weiterleiten.
- Nach Zustimmung einen kurzlebigen Code entgegennehmen.
- Code gegen ein Zugriffstoken tauschen.
- Token serverseitig speichern, niemals im Browser ablegen.
- Zustimmung nennt Anwendung, Konto und angefragte Rechte.
Authorization Code mit PKCE
Mobile Apps und Anwendungen ohne sicheres Geheimnis.
- Zufälligen Verifier erzeugen und daraus die Challenge ableiten.
- Anmeldung mit Challenge starten.
- Code mit dem Verifier gegen ein Token tauschen.
- Pflicht für öffentliche Clients.
- Kein Client-Geheimnis in der App speichern.
Service Accounts
Dauerhafte Automatisierungen eines Betriebs.
- Service Account je Betrieb und Zweck anlegen.
- Rollen und Geltungsbereich festlegen.
- Zugang mit Ablaufdatum versehen und überwachen.
- Ein Konto pro Zweck – keine gemeinsam genutzten Zugänge.
Pflichtangaben in jeder Anfrage
- Authorization
- Bearer-Token aus dem OAuth-Ablauf.
- X-Ryh-Tenant
- Betrieb, für den der Aufruf gilt.
- Idempotency-Key
- Bei verändernden Aufrufen: Vorgangsschlüssel gegen Doppelbuchungen.
Regeln für Zugangsdaten
- Keine festen Schlüssel im Quellcode oder in der Versionsverwaltung.
- Zugangsdaten gehören in eine geschützte Ablage der jeweiligen Umgebung.
- Tokens sind kurzlebig und werden erneuert, nicht verlängert.
- Jeder Zugang trägt einen Zweck, eine verantwortliche Person und ein Ablaufdatum.
- Anmeldung von Personen (Passkeys, Passwort, Zwei-Faktor) ist im Security Center beschrieben, nicht hier.
Fehlermeldungen
Antworten enthalten eine Vorgangskennung, aber keine internen Details. Für die Ursachenanalyse genügt uns diese Kennung.
| Kennung | Status | Bedeutung | Mögliche Ursachen | Lösung |
|---|---|---|---|---|
| unauthorized | 401 | Der Aufruf war nicht angemeldet. | Token fehlt, Token abgelaufen, Falsche Umgebung | Neues Zugriffstoken anfordern und die Umgebung prüfen. |
| forbidden | 403 | Der Zugang darf diese Aktion nicht ausführen. | Fehlende Rolle, Betrieb nicht freigegeben | Berechtigungen des Zugangs im Entwicklerportal prüfen. |
| not_found | 404 | Der angefragte Eintrag existiert nicht. | Falsche Kennung, Eintrag gehört zu einem anderen Betrieb | Kennung und Betrieb im Kopf der Anfrage abgleichen. |
| invalid_request | 400 | Die Anfrage war unvollständig oder unpassend. | Pflichtfeld fehlt, Falscher Datentyp | Anfrage gegen die veröffentlichte Beschreibung prüfen. |
| capability_denied | 409 | Die angefragte Fähigkeit ist für diese Verbindung nicht freigegeben. | Fähigkeit nicht gebucht, Verbindung pausiert | Fähigkeit im Integration Hub freischalten lassen. |
| idempotency_conflict | 409 | Gleicher Vorgangsschlüssel mit abweichendem Inhalt. | Schlüssel wiederverwendet, Inhalt nachträglich geändert | Für jeden neuen Vorgang einen neuen Schlüssel erzeugen. |
| idempotency_required | 428 | Für diesen Aufruf ist ein Vorgangsschlüssel Pflicht. | Kopf Idempotency-Key fehlt | Vorgangsschlüssel mitsenden. |
| rate_limited | 429 | Es wurden zu viele Aufrufe in kurzer Zeit gesendet. | Lastspitze, Wiederholung ohne Wartezeit | Wartezeit aus der Antwort beachten und mit wachsendem Abstand erneut versuchen. |
| internal | 500 | Auf unserer Seite ist etwas schiefgelaufen. | Störung im Betrieb | Vorgangskennung notieren, Status Center prüfen und den Developer Support informieren. |
Grenzwerte
Grenzwerte werden je Zugang, Betrieb und Umgebung konfiguriert. Die aktuell gültigen Werte stehen im Entwicklerportal und in den Antwortköpfen.
Antwortköpfe
- X-RateLimit-Limit
- Aktuell gültiger Grenzwert für dieses Zeitfenster.
- X-RateLimit-Remaining
- Verbleibende Aufrufe im Zeitfenster.
- Retry-After
- Empfohlene Wartezeit in Sekunden.
Verhalten
- Bei Überschreitung antwortet die Schnittstelle mit 429 und einer Wartezeit.
- Wiederholungen mit wachsendem Abstand und leichter Streuung senden.
- Dauerhaft hohe Last vorher mit uns abstimmen statt aufteilen.