Rental-Szenarien: Anwendung, API und Webhooks

Vor den Szenarien: Wer erstellt was?

Ihr Vermietsystem verwaltet Buchung, Preise, Zahlungen und kaufmännische Entscheidungen. TrakarIA behandelt die physische Fahrzeuginspektion: Abfahrt, Rückgabe, Nachweise, Vergleich und Berichte. Dasselbe Fahrzeug kann in vielen aufeinanderfolgenden Vermietungen verwendet werden.

Bei einer Systemanbindung gibt es zwei unterschiedliche Zugangsarten:

Zugang	Wer verwendet ihn?	Zweck
Gruppen-API-Schlüssel	Das Backend Ihrer Vermietsoftware	Fahrzeuge und Rental-Vorgänge synchronisieren, Inspektionen vorbereiten und Ergebnisse lesen. Niemals im Browser des Mitarbeiters verwenden.
TrakarIA-Konto	Die Person, die die Inspektion durchführt	In der Anwendung anmelden, Fotos aufnehmen und validieren. Ein API-Schlüssel ersetzt dieses Konto nicht.

Szenario nach Geschäftszweck wählen

Szenario	Wann verwenden?	Erforderliches API-Verhalten
Vorausbuchung	Das Vermietsystem kennt die Buchung vor der Abholung	Planung und optionalen Kundenkontext vor der physischen Übergabe synchronisieren
Walk-in-Übergabe	Der Kunde erscheint, bevor eine vollständige Buchung besteht	Rental-Vorgang nur mit stabilen externen Kennungen anlegen und später mit höherer Quellrevision ergänzen
Rückgabe mit Änderung	Der vollständige Lebenszyklus soll durchlaufen werden	Abfahrtsbasis bewahren, Rückgabe validieren und Vergleichsbericht abrufen
Stornierung	Die Buchung wird vor Beginn der Inspektion storniert	Rental-Vorgang stornieren und Planungsbelegung freigeben, ohne den Prüfverlauf zu löschen

Synchronisierung ist eine ausdrückliche Aktion: Ihr Backend sendet PUT /v1/vehicles/by-external/{external_id} für das Fahrzeug und PUT /v1/rentals/by-external/{external_id} für den mit der Buchung verknüpften Rental-Vorgang. Dieser erscheint sofort in der TrakarIA-Planung. Zum Anlegen werden nur die externe Kennung in der Route und vehicle_external_id benötigt. Zeiten, Referenzen, Standorte, Kontakt und Fahrer können im Voraus, bei der tatsächlichen Übergabe oder später mit einer höheren Quellrevision geliefert werden. Ohne Abfahrtszeit gilt der Erstellungszeitpunkt; ohne Rückgabezeit bleibt der Planungseintrag offen. TrakarIA liefert öffentliche Rental- und Planungskennungen. Verwenden Sie dieselben externen Kennungen, um dieselben Ressourcen zu aktualisieren. Ohne diese Aufrufe wird keine Buchung automatisch synchronisiert.

Damit eine Inspektion für einen synchronisierten Vorgang über die öffentliche API verfügbar ist, ruft Ihr Backend zusätzlich POST /v1/rentals/{rental_id}/inspections zuerst für die Abfahrt und später für die Rückgabe auf. Die zurückgegebene launch_url öffnet nur den richtigen TrakarIA-Ablauf. Der Mitarbeiter kann denselben Ablauf auch in der Anwendung finden, doch das Anlegen des Vorgangs und Zuordnen der Inspektion bleiben API-Schritte.

Nach der Validierung können zwei offizielle Berichtstypen bestehen: departure nach der Übergabe und comparison nach der Rückgabe. Beide sind als JSON und PDF verfügbar; das PDF kann später als das JSON fertig werden. Einen dritten Berichtstyp return gibt es nicht. GET /v1/rentals/{rental_id}/report zeigt verfügbare Berichtskennungen, GET /v1/reports/{report_id} liest eine JSON-Version und GET /v1/reports/{report_id}/pdf lädt deren PDF.

Webhooks sind optional. Für automatische Benachrichtigungen fügen Sie dem API-Schlüssel unter Organisation → Integrationen → API-Schlüssel → Webhooks verwalten ein HTTP- oder HTTPS-Ziel hinzu. Abonnieren Sie rental.departure.completed, rental.return.completed und optional rental.report.pdf_ready. TrakarIA sendet ein signiertes POST an diese URL; Ihr Backend prüft die Signatur und lädt den Bericht über die API. Der Webhook enthält nicht den vollständigen Bericht. Ohne Ziel kann das Backend GET /v1/events und die Berichtsrouten abfragen. Ohne API-Integration erhält das Vermietsystem weder diese Ereignisse noch Berichte über die öffentliche API. Siehe Webhooks und Wiederherstellung.

Verwechseln Sie ausgehende API-Anfragen nicht mit eingehenden Webhooks. PUT /v1/rentals/... und POST /v1/inspections/... sind Befehle Ihres Backends. rental.departure.completed, rental.return.completed und rental.report.pdf_ready werden an Ihren Empfänger gesendet. Ein konfigurierter Empfänger ist lediglich empfangsbereit; erst ein erfolgreich signaturgeprüftes Ereignis belegt eine Zustellung.

Nach validierter Abfahrt oder Rückgabe gilt:

1. Die öffentliche Inspektion erhält den Status completed.
2. Der signierte Abschluss-Webhook trifft ein oder dasselbe Ereignis wird über GET /v1/events nachgeholt.
3. Das Backend liest den aktuellen Berichtsindex und archiviert das unveränderliche JSON.
4. Es fordert das PDF an. 202 bedeutet, dass es noch erzeugt wird; das Backend beachtet Retry-After oder verfolgt den zurückgegebenen Auftrag bis zur Bereitschaft.

Szenario 1: Angebundene Vermietsoftware mit „Inspektion öffnen“

Voraussetzungen: Ein Administrator hat einen API-Schlüssel erstellt, den Ihr Backend sicher speichert. Für automatische Meldungen wurde zusätzlich ein Webhook-Ziel konfiguriert. Beispiel: Fahrzeug FLEET-42 ist in Ihrem System als RES-1042 gebucht.

1. Das Backend sendet PUT /v1/vehicles/by-external/FLEET-42 und danach PUT /v1/rentals/by-external/RES-1042 mit vehicle_external_id: FLEET-42. Die Buchung erscheint sofort in der Planung. Speichern Sie Rental-id und planning.entry_id. Bei einer späteren Änderung senden Sie eine streng höhere source_revision; mit Beginn der Inspektion wird die Fahrzeugzuweisung festgeschrieben.
2. Bei der Abfahrt ruft das Backend POST /v1/rentals/{rental_id}/inspections mit {"type":"departure"} und einem Idempotency-Key auf. Es speichert die Inspektionskennung und zeigt eine Schaltfläche für die launch_url.
3. Der Mitarbeiter öffnet den Link, meldet sich mit dem TrakarIA-Konto an, inspiziert und fotografiert das Fahrzeug und validiert die Abfahrt. Der Link allein berechtigt nicht zur Inspektion; TrakarIA prüft die persönlichen Berechtigungen.
4. Bei konfiguriertem Webhook empfängt das Backend rental.departure.completed, prüft die Signatur, liest GET /v1/rentals/{rental_id}/report und lädt danach den JSON-Bericht departure über dessen report_id. Das PDF wird geladen, sobald es bereitsteht. Ohne Webhook wird der Zustand per API abgefragt.
5. Bei der Rückgabe ruft das Backend denselben Inspektionsendpunkt mit {"type":"return"} und einem neuen Idempotency-Key auf und öffnet die neue launch_url. Der Mitarbeiter validiert in TrakarIA den Vergleich.
6. rental.return.completed meldet bei konfiguriertem Webhook, dass das Vergleichs-JSON bereitsteht. Das Backend liest den Berichtsindex, archiviert report_id und Version und lädt das PDF. Abrechnungsentscheidungen verbleiben im Vermietsystem.

Szenario 2: Angebundene Vermietsoftware ohne Startschaltfläche

Ein API-Schlüssel bleibt erforderlich. Nur die Navigationsschaltfläche entfällt; das Backend synchronisiert Fahrzeug und Buchung weiterhin.

1. Das Backend führt beide PUT-Aufrufe aus Szenario 1 aus und bereitet die Abfahrt über POST /v1/rentals/{rental_id}/inspections vor. Die launch_url darf ignoriert werden.
2. Der Mitarbeiter öffnet die TrakarIA-Anwendung, wählt Gruppe und Fahrzeug und setzt die bereits vorbereitete Abfahrtsinspektion fort. Für dieselbe Buchung wird kein zweiter Rental-Vorgang angelegt.
3. Nach der Validierung lädt das Backend den Abfahrtsbericht wie in Szenario 1. Für die Rückgabe bereitet es {"type":"return"} per API vor; der Mitarbeiter setzt die Rückgabe desselben Fahrzeugs in TrakarIA fort. Webhooks und Berichte folgen bei konfiguriertem Ziel demselben Muster.

Dieses Modell eignet sich für Teams, die bereits in TrakarIA arbeiten. Das manuelle Öffnen der Anwendung ersetzt nicht die Synchronisierungs- und Vorbereitungsaufrufe des Backends.

Szenario 3: Vollständig in TrakarIA, ohne API-Integration

Hier bestehen weder Partner-API-Schlüssel noch Synchronisierung mit dem Vermietsystem. Der Mitarbeiter verwendet ausschließlich das eigene TrakarIA-Konto und Gruppenberechtigungen.

1. Im Rental-Bereich wählt oder erstellt die Person ein Fahrzeug und beginnt die Abfahrt. TrakarIA erstellt den Inspektionszyklus; die für den Ablauf benötigten Angaben, etwa eine Reservierungsreferenz, werden in der Anwendung erfasst.
2. Die Person erfasst Nachweise und validiert die Abfahrt. Später findet sie dasselbe Fahrzeug und denselben Zyklus, beginnt die Rückgabe und validiert den Vergleich.
3. Das Team liest die Ergebnisse in TrakarIA. Es wurde keine Buchung automatisch aus dem Vermietsystem importiert, und dieses System erhält weder Webhook noch Bericht über die öffentliche API.

Ein ausschließlich in der Anwendung erstellter Zyklus ist nicht automatisch mit einem öffentlichen /v1/rentals-Vorgang verknüpft. Planen Sie bei einer späteren Integration ausdrücklich, wie Fahrzeuge und Vermietungen zugeordnet werden; ältere Zyklen erscheinen nicht automatisch in der API.

Szenario 4: Buchungs- oder Berichtsangaben ändern sich

• Vor der ersten Inspektion: Das Backend ändert unterstützte Felder über PUT .../by-external/{external_id} oder PATCH /v1/rentals/{rental_id} mit einem neueren Quellmarker. Nach 409 liest es den aktuellen Vorgang, bevor es erneut sendet.
• Stornierung vor Abfahrt: POST /v1/rentals/{rental_id}/cancel storniert Vorgang und Planungseintrag.
• Nach Beginn der Inspektion: Die Fahrzeugzuweisung ist festgeschrieben. Nach validierter Abfahrt werden auch geplante Zeiten und Standorte festgeschrieben. Eine unterstützte Korrektur kann eine neue unveränderliche Version des Abfahrts- oder Vergleichsberichts erzeugen.
• Nach einer Korrektur: Das Backend archiviert jede neue report_id und Version, statt den vorherigen Bericht stillschweigend zu ersetzen. rental.report.corrected kann dies bei konfiguriertem Ziel melden.

Berichte und Nachweise erläutern aktuelle und historische Versionen. Diese Routen betreffen Vorgänge, die über die öffentliche API erstellt und zugeordnet wurden.

Szenario 5: Webhook-Empfänger ist nicht erreichbar

Dieses Szenario betrifft nur eine API-Integration mit Webhook-Ziel. Zustellungen können wiederholt oder außerhalb der Reihenfolge eintreffen. Prüfen Sie jede Signatur, deduplizieren Sie anhand von webhook-id und laden Sie den aktuellen Bericht. Rufen Sie nach einem Ausfall GET /v1/events mit dem gespeicherten Cursor oder einem passenden created_after auf und verschieben Sie den Cursor erst nach der Verarbeitung. Ereignisse werden 30 Tage aufbewahrt. Siehe Webhooks und Wiederherstellung.

Szenario 6: Inspektionslink ist abgelaufen

Lesen Sie in einem angebundenen Szenario GET /v1/inspections/{inspection_id}. Ist die Inspektion noch offen, rufen Sie POST /v1/inspections/{inspection_id}/launch mit einem neuen Idempotency-Key auf und öffnen Sie den neuen Link. Dieselbe Inspektion wird fortgesetzt; der Mitarbeiter muss weiterhin angemeldet und berechtigt sein.

Was Ihre Integration speichern sollte

Daten	Grund
Gruppe sowie externe Fahrzeug- und Reservierungskennungen	Nach Wiederholungen oder Personalwechseln exakt dieselben Datensätze abgleichen
Öffentliche Rental- und Inspektionskennungen	Den beabsichtigten Ablauf ohne private Kernel-Kennungen öffnen und abfragen
Planungseintragskennung	Bestätigen, welcher Kalendereintrag die synchronisierte Buchung darstellt
Ein Idempotenzschlüssel je Befehl	Sicher wiederholen, wenn eine Erstellungsantwort verloren geht
Ereigniscursor und verarbeitete Ereigniskennungen	Webhook-Benachrichtigungen nachholen und deduplizieren
Berichtskennung, Typ, Version und Inhaltshash	Revisionen von Abfahrt und Vergleich getrennt archivieren

Bewahren Sie im angebundenen Szenario API-Schlüssel und Webhook-Geheimnis ausschließlich serverseitig auf. Verwenden Sie den Startlink nicht als dauerhafte Kennung; erneuern Sie ihn bei Bedarf. Erste Schritte zeigen die ersten Anfragen, die Rental-API-Referenz definiert die exakten Felder.