Zum Inhalt springen

Einstieg

Formate und Versionierung

Was unter /api/ext/v1 steht, bleibt stehen. Kommt etwas Neues, kommt es als Feld dazu. Muss etwas weg, erscheint /api/ext/v2 daneben, und v1 läuft weiter.

Für Ihr Programm heißt das:

  • Unbekannte Felder überlesen. Eine Antwort kann morgen ein Feld mehr tragen als heute.
  • Auf Namen bauen, nicht auf Reihenfolge. Die Reihenfolge der Felder ist nicht zugesagt.
  • Auf unbekannte Werte vorbereitet sein. Wo eine Antwort heute zwei Arten nennt, kann eine dritte dazukommen.

Die Schnittstelle beschreibt sich selbst: https://skirent.sumware.at/api/ext/openapi.json liefert ein OpenAPI-Dokument in der Fassung 3.1, ohne Schlüssel. Es entsteht aus derselben Tabelle im Code, aus der auch die Routen entstehen. Die Fassung mit Beispielen steht hier unter OpenAPI-Dokument.

Rumpf und Antwort sind JSON in UTF-8. Schreibende Anfragen senden Content-Type: application/json.

Was Form Beispiel
Betrag ganze Zahl in Cent, Feldname endet auf Cents 39000 für € 390,00
Datum JJJJ-MM-TT 2026-12-27
Zeitstempel ISO 8601 mit Z 2026-12-27T08:12:46.278Z
Uhrzeit HH:MM 10:00
Land ISO 3166-1 alpha-2 AT
Währung ISO 4217 EUR
Sprache Code aus zwei Buchstaben de

Beträge sind nie Kommazahlen. Die Umsatzsteuer ist in den Beträgen enthalten; wie viel davon Steuer ist, nennt vatCents.

Was Form Beispiel
Buchung SB-JJMMTT-XXXX: Tag des Anlegens und vier Zeichen aus einem Alphabet ohne 0, O, 1, I und L SB-261114-WWNP
Auftrag, Unterkunft ganze Zahl, eindeutig innerhalb des Betriebs 3
Schlüssel, Kursposten, Zustellung UUID in der Fassung 7 01a1db4a-b5a4-7331-84c1-5c71a25feb38

Nummern von Aufträgen und Unterkünften gelten nur innerhalb eines Betriebs. Dieselbe Zahl bezeichnet in einem anderen Betrieb etwas anderes.

Kein Betrag aus einer Anfrage wird übernommen. Wer eine Buchung anlegt, schickt Positionen, und der Server baut den Preis daraus neu auf, mit derselben Rechnung wie Website und Portal.

Felder, die das Schema nicht kennt, werden verworfen und nicht abgelehnt. Ein mitgeschicktes amount führt zu keinem Fehler, sondern zu einer Antwort ohne dieses amount.

Einmal Berechnetes bleibt stehen: Positionen und Summen einer Buchung sind ein Abzug zum Buchungszeitpunkt. Ändert der Betrieb im Januar seine Preise, ändert sich keine Buchung aus dem Dezember.

Meldungen an Menschen, also message und hint eines Fehlers, kommen in der Sprache der Anfrage. Sie steuern das mit dem Kopf Accept-Language.

Sprache Code
Deutsch (Vorgabe ohne Kopf) de
Englisch en
Italienisch it
Slowenisch sl

Eine Sprache, die nicht dabei ist, bekommt Englisch. Das Feld code ändert sich mit der Sprache nie.

Terminal-Fenster
curl "https://skirent.sumware.at/api/ext/v1/bookings/SB-000000-XXXX" \
-H "Authorization: Bearer $SKI4ME_KEY" \
-H "Accept-Language: it"

Antwort404Not Found

{
"error": {
"code": "not_found",
"message": "Questa prenotazione non esiste.",
"status": 404,
"hint": "Controlla il riferimento.",
"documentation_url": "https://skirent.sumware.at/api/"
}
}

Beschriftungen in Buchungen, etwa label einer Position, stehen in der Sprache der Buchung. Der Katalog kommt in der Standardsprache des Betriebs.

Die Liste der Buchungen blättert mit page und perPage und nennt in jeder Antwort total und pages. Die übrigen Listen nehmen limit und liefern höchstens so viele Einträge.

Wer nur Änderungen braucht, fragt bei den Kursen mit since: die Antwort trägt asOf, und dieser Wert ist das since der nächsten Abfrage.

Methode Bedeutung
GET liest, ändert nichts
POST legt an oder löst einen Vorgang aus
PATCH ändert die genannten Felder
DELETE entfernt oder legt still

Ein bekannter Pfad mit falscher Methode antwortet 405 mit Allow und nie 404.

Terminal-Fenster
curl -X DELETE "https://skirent.sumware.at/api/ext/v1/bookings/SB-261114-WWNP" \
-H "Authorization: Bearer $SKI4ME_KEY"

Antwort405Method Not Allowed

Allow
GET, HEAD, OPTIONS, PATCH
{
"error": {
"code": "method_not_allowed",
"message": "DELETE wird hier nicht angenommen.",
"status": 405,
"hint": "Diesen Pfad mit GET oder HEAD oder OPTIONS oder PATCH aufrufen.",
"documentation_url": "https://skirent.sumware.at/api/"
}
}