Rental-scenario's: applicatie, API en webhooks

Eerst: wie maakt wat?

Je verhuursoftware beheert reservering, prijzen, betalingen en commerciële beslissingen. TrakarIA behandelt de fysieke voertuiginspectie: uitgifte, retour, bewijs, vergelijking en rapporten. Hetzelfde voertuig kan opeenvolgende verhuurcycli doorlopen.

Toegang	Gebruiker	Doel
Groepsgebonden API-sleutel	De backend van verhuursoftware	Voertuigen en dossiers synchroniseren, inspecties openen en resultaten lezen. Nooit in de browser.
TrakarIA-account	De persoon die inspecteert	Aanmelden, foto’s maken en valideren. De API-sleutel vervangt dit account niet.

Kies op basis van bedrijfsdoel

Scenario	Wanneer	Vereist API-gedrag
Vooraf geboekt	Reservering is vóór ophalen bekend	Synchroniseer planning en optionele klantcontext vóór overdracht
Walk-in bij uitgifte	Klant arriveert voordat alle boekingsdata bestaan	Maak Rental met stabiele ID’s en verrijk met een nieuwere revisie
Retour met wijziging	Volledige cyclus doorlopen	Bewaar vertrekbaseline, valideer retour en haal vergelijking op
Annulering	Boeking wordt vóór inspectiestart geannuleerd	Annuleer Rental en geef planning vrij zonder auditspoor te wissen

Synchronisatie is expliciet: stuur PUT /v1/vehicles/by-external/{external_id} en PUT /v1/rentals/by-external/{external_id}. De Rental verschijnt direct in de planning. Alleen route-ID en vehicle_external_id zijn nodig; datums, referenties, locaties, contact en bestuurders kunnen vooraf, tijdens uitgifte of later met een nieuwere revisie volgen. Zonder vertrektijd geldt creatietijd; zonder retourtijd blijft de planning open. Hergebruik externe ID’s om dezelfde resources te wijzigen. Zonder deze oproepen wordt geen boeking automatisch gesynchroniseerd.

Bereid de inspectie voor met POST /v1/rentals/{rental_id}/inspections, eerst departure, daarna return. De launch_url opent alleen de juiste workflow; persoonlijke authenticatie blijft verplicht.

Er zijn twee officiële rapporttypen: departure en comparison. Beide hebben JSON en PDF; PDF kan later klaar zijn. De rapportindex levert de actuele ID’s. Webhooks zijn optioneel: configureer een bestemming en selecteer voltooiingsgebeurtenissen. Verifieer de handtekening en lees het rapport via de API. Zonder bestemming gebruik je GET /v1/events. Uitgaande API-opdrachten zijn geen inkomende webhookgebeurtenissen.

Na validatie:

wordt de inspectie completed;
arriveert de ondertekende gebeurtenis of herstel je haar via GET /v1/events;
leest de backend de index en archiveert onveranderlijke JSON;
vraagt hij de PDF op; bij 202 volgt hij Retry-After of de job.

Scenario 1: gekoppelde software met knop “Inspectie openen”

De backend synchroniseert voertuig en reservering, bewaart Rental id en planning.entry_id en gebruikt oplopende bronrevisies.
Bij uitgifte roept hij de inspectieroute aan met {"type":"departure"} en Idempotency-Key, bewaart het inspectie-ID en toont een knop naar launch_url.
De medewerker opent, meldt zich aan, neemt foto’s en valideert. De link verleent geen rechten.
Na rental.departure.completed of polling archiveert de backend het departure-rapport en haalt de PDF wanneer gereed.
Bij retour gebruikt hij hetzelfde endpoint met {"type":"return"} en een nieuwe idempotentiesleutel.
rental.return.completed signaleert het comparison-rapport; financiële beslissingen blijven in verhuursoftware.

Scenario 2: gekoppelde software zonder knop

De API-sleutel blijft nodig. De backend synchroniseert en bereidt voor, maar negeert launch_url. De medewerker vindt en hervat de voorbereide inspectie in de TrakarIA-applicatie en maakt geen tweede cyclus voor dezelfde boeking. Resultaten volgen scenario 1.

Scenario 3: alles in TrakarIA, zonder API

Er is geen partnerkey of synchronisatie. De medewerker kiest of maakt een voertuig, voltooit uitgifte en retour in dezelfde cyclus en bekijkt resultaten in TrakarIA. Externe software ontvangt geen webhook of rapport. Een app-only cyclus wordt later niet automatisch aan /v1/rentals gekoppeld.

Scenario 4: reservering of rapport verandert

Vóór de eerste inspectie: wijzig ondersteunde velden via upsert of PATCH met een nieuwere bronmarkering. Lees na 409 eerst het huidige dossier.
Annulering vóór vertrek: /cancel annuleert dossier én planningsvermelding.
Na inspectiestart: voertuigtoewijzing bevriest; na vertrek ook geplande tijd en locatie. Toegestane correcties maken een nieuwe onveranderlijke rapportversie.
Na correctie: archiveer elk nieuw report_id en versie; rental.report.corrected kan dit melden.

Scenario 5: webhookontvanger offline

Verifieer en dedupliceer, haal daarna de huidige resource op. Gebruik na uitval GET /v1/events met cursor of created_after; verschuif de cursor pas na verwerking. Retentie is 30 dagen.

Scenario 6: inspectielink verlopen

Lees de inspectie. Is die nog open, roep dan /launch aan met een nieuwe Idempotency-Key en open de nieuwe link. Dit hervat dezelfde inspectie en de medewerker moet nog steeds inloggen.

Wat je integratie bewaart

Gegeven	Reden
Groep plus externe voertuig- en reserverings-ID’s	Exact dezelfde records na herhaling terugvinden
Publieke Rental- en inspectie-ID’s	De bedoelde workflow openen zonder private Kernel-ID’s
Planning entry ID	De agendareservering identificeren
Eén idempotentiesleutel per commando	Veilig herhalen na verlies van een reactie
Gebeurteniscursor en verwerkte ID’s	Meldingen herstellen en dedupliceren
Rapport-ID, type, versie en hash	Vertrek- en vergelijkingsversies apart archiveren

Bewaar API-sleutel en webhookgeheim server-side. Gebruik launch_url niet als duurzaam ID. De startgids toont eerste aanvragen en de Rental API-referentie bepaalt de exacte velden.