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.

Beispielaufruf

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

Herunterladen Im Browser ansehen

OpenAPI als YAML

Gut lesbar für Prüfungen und die Ablage in der Versionsverwaltung.

ryh-api-2026-07-01.openapi.yaml

Herunterladen Im Browser ansehen

Versionierung

2 veröffentlichte Stände. Keine Änderung mit Anpassungsbedarf in der aktuellen Version.

2026-07-012026-07-01Aktuell

Ä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.

2026-06-122026-06-12

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.

Fehlermeldungen der Ryh API mit Ursache und Lösung
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.

Fehlerantworten enthalten eine Vorgangskennung. Diese Kennung reicht uns im Support – bitte keine Tokens oder Rohdaten mitschicken.