Einstieg
Formate und Versionierung
Versionierung
Abschnitt betitelt „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.
Anfragen und Antworten
Abschnitt betitelt „Anfragen und Antworten“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.
Kennungen
Abschnitt betitelt „Kennungen“| 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.
Serverseitige Preisberechnung
Abschnitt betitelt „Serverseitige Preisberechnung“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.
Sprache
Abschnitt betitelt „Sprache“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.
curl "https://skirent.sumware.at/api/ext/v1/bookings/SB-000000-XXXX" \ -H "Authorization: Bearer $SKI4ME_KEY" \ -H "Accept-Language: it"const res = await fetch("https://skirent.sumware.at/api/ext/v1/bookings/SB-000000-XXXX", { headers: { Authorization: `Bearer ${process.env.SKI4ME_KEY}`, "Accept-Language": "it", },});
const data = await res.json();if (!res.ok) throw new Error(`${data.error.code}: ${data.error.hint}`);console.log(data);import osimport requests
res = requests.get( "https://skirent.sumware.at/api/ext/v1/bookings/SB-000000-XXXX", headers={ "Authorization": f"Bearer {os.environ['SKI4ME_KEY']}", "Accept-Language": "it", }, timeout=10,)data = res.json()if not res.ok: raise RuntimeError(f"{data['error']['code']}: {data['error']['hint']}")print(data)<?php
$ch = curl_init('https://skirent.sumware.at/api/ext/v1/bookings/SB-000000-XXXX');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('SKI4ME_KEY'), 'Accept-Language: it', ],]);$body = curl_exec($ch);$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$data = json_decode($body, true);if ($status >= 400) { throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['hint']);}print_r($data);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.
Paginierung
Abschnitt betitelt „Paginierung“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.
HTTP-Methoden
Abschnitt betitelt „HTTP-Methoden“| 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.
curl -X DELETE "https://skirent.sumware.at/api/ext/v1/bookings/SB-261114-WWNP" \ -H "Authorization: Bearer $SKI4ME_KEY"const res = await fetch("https://skirent.sumware.at/api/ext/v1/bookings/SB-261114-WWNP", { method: "DELETE", headers: { Authorization: `Bearer ${process.env.SKI4ME_KEY}`, },});
const data = await res.json();if (!res.ok) throw new Error(`${data.error.code}: ${data.error.hint}`);console.log(data);import osimport requests
res = requests.delete( "https://skirent.sumware.at/api/ext/v1/bookings/SB-261114-WWNP", headers={"Authorization": f"Bearer {os.environ['SKI4ME_KEY']}"}, timeout=10,)data = res.json()if not res.ok: raise RuntimeError(f"{data['error']['code']}: {data['error']['hint']}")print(data)<?php
$ch = curl_init('https://skirent.sumware.at/api/ext/v1/bookings/SB-261114-WWNP');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_CUSTOMREQUEST => 'DELETE', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('SKI4ME_KEY'), ],]);$body = curl_exec($ch);$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$data = json_decode($body, true);if ($status >= 400) { throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['hint']);}print_r($data);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/" }}