Zum Inhalt springen

Meldungen

Kursmeldungen

Vermittelt ein Betrieb Kurse einer Skischule, muss die Schule jede Buchung erfahren. Statt abzufragen, kann sie sich melden lassen: Ski4me sendet bei jedem Ereignis eine signierte Nachricht an eine Adresse der Schule.

Wer lieber selbst nachsieht, nimmt die Endpunkte unter Kurse. Der Rumpf ist in beiden Fällen derselbe.

Den Endpunkt legt ein Admin des Betriebs im Portal an, unter Einstellungen, Abschnitt Partner.

  1. Neuer Endpunkt: ein Name, die Adresse der Schule und die Ereignisse, die sie bekommen soll.
  2. Das Geheimnis erscheint genau einmal. Es beginnt mit whsec_ und gehört zur Schule: mit ihm prüft sie die Signatur jeder Meldung.
  3. Testmeldung sendet sofort eine Meldung mit erfundenen Daten und zeigt die Antwort der Gegenstelle.

Die Adresse muss mit https:// beginnen und von außen erreichbar sein. Zugangsdaten gehören nicht in die Adresse. Adressen in privaten Netzen werden abgelehnt, und das wird vor jedem Versuch neu geprüft.

Geheimnis erneuern stellt ein neues aus. Das alte gilt ab diesem Moment nicht mehr.

Ereignis Wann
course.booked Ein Kurs ist gebucht und die Zahlung bestätigt. Vor der Bestätigung geht nichts hinaus.
course.cancelled Die Buchung wurde storniert. Der Platz ist frei.
course.changed Termin, Variante, Treffpunkt, Sprache oder Teilnehmerzahl haben sich geändert.

Ausgelöst werden derzeit course.booked und course.cancelled. course.changed ist vorgesehen und lässt sich schon abonnieren; ein Empfänger, der es heute einplant, braucht später nichts nachzuziehen.

Gemeldet wird je Kursposten, nicht je Buchung. Bucht ein Gast zwei Kurse, kommen zwei Meldungen, und jede ist für sich zustellbar.

So ging die Meldung zur Buchung SB-261114-WWNP hinaus:

MeldungPOSThttps://skischule-bergdorf.example/hooks/ski4me

Content-Type
application/json
User-Agent
SUMWARE-Skiverleih-Meldung/1
X-Skirent-Event
course.booked
X-Skirent-Delivery
01a1db4c-2a2e-710b-b76a-5b07501e7821
X-Skirent-Signature
t=1794680606,v1=b73242c707f3b58511d48aa7c161a748754a150098b0eabe044248d35e81c43d
{
"event": "course.booked",
"delivery": "01a1db4c-2a2e-710b-b76a-5b07501e7821",
"sentAt": "2026-11-14T18:23:26.640Z",
"tenant": "talstation",
"course": {
"uid": "01a1db4a-b5a4-7331-84c1-5c71a25feb38",
"bookingRef": "SB-261114-WWNP",
"status": "booked",
"provider": "eigen",
"courseId": "kinder-3t",
"courseName": "Kinderkurs, 3 Tage",
"variantId": "1",
"date": "2026-12-28",
"days": 3,
"timeFrom": "10:00",
"meetingPointId": "schule",
"meetingPointName": "Treffpunkt der Skischule",
"skillId": "beginner",
"skillName": "Anfänger",
"language": "de",
"persons": 1,
"participants": [
{
"firstName": "Leon",
"lastName": "Berger",
"age": 11
}
],
"contact": {
"name": "Martin Berger",
"email": "martin.berger@example.org",
"phone": "+49 000 0000002"
},
"amountCents": 19500,
"currency": "EUR",
"bookedAt": "2026-11-14T18:22:44.270Z",
"updatedAt": "2026-11-14T18:21:08.900Z",
"reportedAt": null
}
}
Kopf Bedeutung
X-Skirent-Event das Ereignis
X-Skirent-Delivery Kennung dieser Zustellung. Sie ist der Schlüssel gegen Doppelverarbeitung.
X-Skirent-Signature Zeit und Signatur, siehe Signatur prüfen
User-Agent SUMWARE-Skiverleih-Meldung/1
Feld Bedeutung
event das Ereignis, wie im Kopf
delivery Kennung der Zustellung, wie im Kopf
sentAt Zeitpunkt des Sendens
tenant Kurzname des Betriebs, der vermittelt hat
test true bei einer Testmeldung, sonst fehlt das Feld
course der Kursposten, mit denselben Feldern wie unter Kurse

Im Kursposten steht, was ein Kursleiter braucht. Was nicht darin steht: nichts aus dem Verleih derselben Buchung, keine Unterkunft, keine Zimmernummer, keine Zahlungsdaten, kein Prüfcode und nicht die Provision des Betriebs.

Der Rumpf entsteht in dem Moment, in dem gesendet wird. Das Ereignis nennt, was geschehen ist; der Rumpf nennt, wie es jetzt steht.

Kommt eine Meldung course.booked verspätet an, weil die Gegenstelle nicht erreichbar war, kann course.status darin schon cancelled lauten. Verlassen Sie sich für den Stand auf den Rumpf.

MeldungPOSThttps://skischule-bergdorf.example/hooks/ski4me

Content-Type
application/json
User-Agent
SUMWARE-Skiverleih-Meldung/1
X-Skirent-Event
course.cancelled
X-Skirent-Delivery
01a1f805-d9a8-75e0-a50c-2313e4831032
X-Skirent-Signature
t=1795162534,v1=8dae81a2c69f0c4c99201fe3a9d541355a8c8ca1be0b5744cbd97efd00cf6ffb
{
"event": "course.cancelled",
"delivery": "01a1f805-d9a8-75e0-a50c-2313e4831032",
"sentAt": "2026-11-20T08:15:34.770Z",
"tenant": "talstation",
"course": {
"uid": "01a1d0a1-941e-7285-840a-b1ba0e382d8d",
"bookingRef": "SB-261112-WDZH",
"status": "cancelled",
"provider": "eigen",
"courseId": "privat-1h",
"courseName": "Private ski lesson",
"variantId": "3",
"date": "2026-12-29",
"days": 1,
"timeFrom": "13:30",
"meetingPointId": "schule",
"meetingPointName": "the ski school meeting point",
"skillId": "advanced",
"skillName": "Advanced",
"language": "en",
"persons": 1,
"participants": [
{
"firstName": "Petra",
"lastName": "Novak",
"age": 36
}
],
"contact": {
"name": "Petra Novak",
"email": "petra.novak@example.org",
"phone": "+43 000 000004"
},
"amountCents": 7900,
"currency": "EUR",
"bookedAt": "2026-11-12T16:41:47.944Z",
"updatedAt": "2026-11-20T08:14:55.400Z",
"reportedAt": "2026-11-14T18:23:26.640Z"
}
}

uid ist dieselbe wie in der Meldung zur Buchung. Über sie finden Sie den Kurs in Ihrem System wieder.

Als zugestellt gilt allein eine Antwort mit Status 2xx. Der Rumpf der Antwort spielt keine Rolle. Je Versuch wartet Ski4me zehn Sekunden.

Antwort der Gegenstelle Was geschieht
2xx zugestellt
408, 429, 5xx, keine Verbindung, keine Antwort in zehn Sekunden Wiederholung
jeder andere Status 4xx gescheitert, keine Wiederholung
3xx Umleitungen werden nicht verfolgt. Gilt als Ablehnung.

Wiederholt wird sechsmal, mit wachsendem Abstand: nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 12 Stunden und 24 Stunden. Danach steht die Zustellung im Portal als gescheitert, und der Admin kann sie mit Erneut senden von Hand anstoßen.

Antworten Sie deshalb schnell mit 2xx und arbeiten Sie die Meldung danach ab.

  • Doppelt: Eine Wiederholung trägt dieselbe Kennung in X-Skirent-Delivery. Wer sie ein zweites Mal sieht, hat die Meldung schon und antwortet trotzdem mit 2xx.
  • Reihenfolge: Eine Reihenfolge ist nicht zugesagt. Eine wiederholte Meldung kann nach einer späteren ankommen. Weil der Rumpf den Stand zum Zeitpunkt des Sendens nennt, gewinnt die Meldung mit dem jüngeren sentAt.

Die Testmeldung trägt test: true, die Buchungsnummer TEST-000000 und einen Kurs, den es nicht gibt. Sie wird nicht wiederholt.

MeldungPOSThttps://skischule-bergdorf.example/hooks/ski4me

Content-Type
application/json
User-Agent
SUMWARE-Skiverleih-Meldung/1
X-Skirent-Event
course.booked
X-Skirent-Delivery
01a1db4c-d50a-7497-8d47-2dfe466de15a
X-Skirent-Signature
t=1794680608,v1=947b98a12f0168d047e7b79a57f0a6ffe82681c1b2164c3175d176de0d2a4983
{
"event": "course.booked",
"delivery": "01a1db4c-d50a-7497-8d47-2dfe466de15a",
"sentAt": "2026-11-14T18:23:28.010Z",
"tenant": "talstation",
"test": true,
"course": {
"uid": "00000000-0000-7000-8000-000000000000",
"bookingRef": "TEST-000000",
"status": "booked",
"provider": "eigen",
"courseId": "0",
"courseName": "Testkurs",
"variantId": "0",
"date": "2026-11-14",
"days": 1,
"timeFrom": "10:00",
"meetingPointId": null,
"meetingPointName": "Testtreffpunkt",
"skillId": null,
"skillName": null,
"language": "de",
"persons": 1,
"participants": [
{
"firstName": "Erika",
"lastName": "Muster",
"age": 30
}
],
"contact": {
"name": "Erika Muster",
"email": "erika@example.org",
"phone": "+43 000 000000"
},
"amountCents": 0,
"currency": "EUR",
"bookedAt": "2026-11-14T18:23:28.010Z",
"updatedAt": "2026-11-14T18:23:28.010Z",
"reportedAt": null
}
}

Ein Empfänger prüft die Signatur auch hier und legt für eine Testmeldung keinen Kurs an.

Zu jedem Endpunkt zeigt das Portal die letzten Zustellungen mit Ereignis, Buchung, Zahl der Versuche, Status der Antwort und dem Anfang der Antwort. Die Zustände heißen dort wartet, zugestellt, gescheitert und aufgegeben.

Aufgegeben wird eine Zustellung, wenn sich die Meldung nicht mehr bauen lässt, etwa weil die Gastdaten nach der Löschfrist nicht mehr lesbar sind.

Die erste erfolgreiche Meldung macht den Kurs im Portal zum gemeldeten. Einen Rückweg gibt es nicht: die Schule kann über diesen Weg nichts an Ski4me senden.