Zum Hauptinhalt springen

Integration der öffentlichen API

Erste Schritte​

1. API-Key erstellen​

Melde dich an und erstelle unter API-Schlüssel in deinem Konto einen API-Key. Bewahre ihn sicher auf; der Schlüssel wird nur einmal angezeigt. Vergib nur die Berechtigungen, die deine Integration braucht (siehe Authentifizierung).

2. Erste Anfrage​

curl -H "X-API-Key: YOUR_KEY" \
https://api.my-playrooms.de/v1/playrooms

Der Katalog-Endpunkt ist öffentlich. Für Buchungsendpunkte fügst du X-API-Key hinzu.

3. Antwort verarbeiten​

[
{
"id": "pl_123",
"urlPath": "lustspielzimmer",
"name": "Lustspielzimmer",
"city": "Berlin",
"rating": 4.8,
"ratingCount": 12,
"pricePerHour": 40,
"pricePerNight": 150
}
]

Die Katalog-Antwort ist direkt ein JSON-Array, kein data-Umschlag. Die aktuelle Seitengröße beträgt 20, Pagination-Metadaten werden nicht zurückgegeben. Optionale Query-Parameter sind locationSearchTerm, bookingType, checkInDate, guestCount und currentPage.

Zahlungssitzung erstellen​

POST /v1/orders erstellt eine Buchung und POST /v1/orders/{orderId}/payment erstellt eine gehostete Zahlungssitzung. Die API führt die Kartenzahlung des Gasts nicht selbst aus.

Rate-Limits​

  • 200 Anfragen pro 60 Sekunden für die öffentliche API
  • Pro API-Key, wenn X-API-Key gesendet wird, sonst pro Client-IP
  • Kein dokumentiertes Tageslimit

Fehlerbehandlung​

CodeBeschreibung
400Ungültige Anfrage oder fachlicher Validierungsfehler
401Fehlender, ungültiger oder widerrufener API-Key
403Gültiger API-Key ohne die nötige wirksame Berechtigung
404Ressource oder Buchung nicht gefunden
409Idempotency-Key mit anderer Anfrage wiederverwendet, oder früherer Versuch nicht als abgeschlossen bestätigt
429Rate-Limit überschritten
500Unerwarteter Serverfehler

Anwendungsfehler verwenden normalerweise RFC-7807-ProblemDetails mit title, status und detail. Ein stabiles code-Feld ist nicht Teil des aktuellen Vertrags.