Rental scenarios: application, API and webhooks

Before the scenarios: who creates what?

You can run scenario 1 end to end in the TrakarIA Integration Lab. Start in simulation, or use a group API key to send test records to the environment selected by the deployed Lab.

Your rental system owns the booking, prices, payments and commercial decisions. TrakarIA handles the physical vehicle inspection: departure, return, evidence, comparison and reports. The same vehicle can be used in many successive rentals.

Two different forms of access are involved when you connect the systems:

Access	Who uses it?	What is it for?
Group API key	Your rental software’s backend	Synchronize vehicles and dossiers, open inspections and read results. Never put it in the operator’s browser.
TrakarIA account	The person performing the inspection	Sign in to the application, take photos and validate. An API key cannot replace this account.

Synchronization is a specific action: your backend sends PUT /v1/vehicles/by-external/{external_id} for the vehicle and PUT /v1/rentals/by-external/{external_id} for the dossier linked to its booking. The Rental is immediately visible in the TrakarIA planning. Only the route external ID and vehicle_external_id are needed to create it; dates, references, locations, contact and drivers may be supplied in advance, at physical handover, or later with a newer source revision. A missing departure defaults to creation time and a missing return keeps the planning entry open-ended. TrakarIA returns public Rental and planning entry IDs. Reuse the same external IDs to update the same resources. Without these calls, no booking is synchronized automatically.

For a synchronized dossier to have an inspection available through the public API, your backend also calls POST /v1/rentals/{rental_id}/inspections for departure and then for return. The returned launch_url only opens the right workflow in TrakarIA. The operator may find that workflow in the application without clicking the link, but creating the dossier and associating the inspection remain API steps.

After validation, there can be two official report kinds: departure after handover and comparison after return. Each is available as JSON and PDF; its PDF may be ready later than its JSON. There is no third return report kind. GET /v1/rentals/{rental_id}/report shows the available report IDs; GET /v1/reports/{report_id} reads one JSON report and GET /v1/reports/{report_id}/pdf downloads its PDF.

Webhooks are optional. If you want your backend to be notified automatically, add an HTTP or HTTPS destination to its API key under Organization → Integrations → API keys → Manage webhooks. Subscribe to rental.departure.completed, rental.return.completed and optionally rental.report.pdf_ready. TrakarIA sends a signed POST to that URL; your backend verifies the signature and fetches the report through the API. The webhook does not contain the full report. Without a webhook destination, your backend can check GET /v1/events and the report routes. Without an API integration, your rental system receives neither these events nor reports through the public API. See webhooks and recovery.

Scenario 1: connected rental software with an “Open inspection” button

Prerequisites: an administrator created an API key and your backend stores it. For automatic notifications, they also configured a webhook destination. Example: vehicle FLEET-42 is booked as RES-1042 in your system.

1. Your backend sends PUT /v1/vehicles/by-external/FLEET-42, then PUT /v1/rentals/by-external/RES-1042 with vehicle_external_id: FLEET-42. The booking appears immediately in planning. It stores the returned public Rental id and planning.entry_id. On a later change, it sends a strictly newer source_revision; vehicle assignment is frozen once the inspection starts.
2. At departure, your backend calls POST /v1/rentals/{rental_id}/inspections with {"type":"departure"} and an Idempotency-Key. It stores the inspection ID and shows a button that opens the returned launch_url.
3. The operator opens the link, signs in with their TrakarIA account, inspects the vehicle, takes photos and validates departure. The link alone does not authorize the inspection: TrakarIA checks their permissions.
4. If a webhook was configured, your backend receives rental.departure.completed. It verifies the signature, reads GET /v1/rentals/{rental_id}/report, then fetches the JSON departure report by its report_id. It downloads the PDF when ready. Without a webhook, it checks the API for the result.
5. At return, your backend calls the same inspection endpoint with {"type":"return"} and a new Idempotency-Key, then opens the new launch_url for the operator. The operator validates the comparison in TrakarIA.
6. If a webhook was configured, rental.return.completed tells your backend that the JSON comparison report is ready. The backend reads the report index, archives the report_id and version, then downloads the PDF when ready. Billing decisions remain in your rental system.

Scenario 2: connected rental software without a launch button

An API key is still required. Only the navigation button is omitted; your backend still synchronizes the vehicle and booking.

1. Your backend makes both PUT calls from scenario 1 and calls POST /v1/rentals/{rental_id}/inspections to prepare departure. It may ignore the launch_url.
2. The operator opens the TrakarIA application, selects the correct group and vehicle, then resumes the departure inspection already prepared. They do not create a second rental for the same booking.
3. After validation, the backend fetches the departure report as in scenario 1. For return, it prepares {"type":"return"} through the API; the operator resumes return for the same vehicle in TrakarIA. Webhooks and reports follow scenario 1 if a destination is configured.

This mode suits teams that already work in TrakarIA. Opening the application manually does not replace the synchronization and preparation calls made by your backend.

Scenario 3: everything happens in TrakarIA, without an API integration

Here there is no partner API key and no synchronization with the rental system. The operator uses only their TrakarIA account and group permissions.

1. In the Rental workspace, they select an existing vehicle or create one in the application, then start departure. TrakarIA creates the inspection cycle; the operator enters the rental details needed by the workflow, such as a booking reference if available.
2. They capture evidence and validate departure. Later, they find the same vehicle and cycle, start return and validate the comparison.
3. The team views the results in TrakarIA. No booking was imported automatically from your rental system, and that system does not receive a webhook or report through the public API.

A cycle created only in the application is not automatically linked to a public API /v1/rentals dossier. If you add an integration later, plan explicitly how to match vehicles and rentals; do not assume older cycles will appear in the API.

Scenario 4: booking or report details change

• Before the first inspection: for an API-connected dossier, your backend updates supported fields through PUT .../by-external/{external_id} or PATCH /v1/rentals/{rental_id} with a newer source marker. After a 409, it reads the current dossier before retrying.
• Before departure cancellation: POST /v1/rentals/{rental_id}/cancel cancels both the dossier and its planning entry.
• After inspection starts: vehicle assignment is frozen. After departure validation, planned times and locations are frozen too. A correction allowed by the workflow can create a new immutable version of the departure or comparison report.
• After correction: your backend archives every new report_id and version; it does not silently replace the previous report. The rental.report.corrected webhook can notify it if a destination is configured.

See reports and evidence for current versus historical versions. These routes concern dossiers created and associated with the public API.

Scenario 5: your webhook receiver is offline

This scenario applies only to an API integration with a configured webhook destination. Deliveries can repeat or arrive out of order: verify each signature, deduplicate by webhook-id and fetch the current report. After downtime, call GET /v1/events with your saved cursor or a suitable created_after value; advance the cursor only after processing. Events are retained for 30 days. See webhooks and recovery.

Scenario 6: an inspection link expired

In a connected scenario, read GET /v1/inspections/{inspection_id}. If the inspection is still open, call POST /v1/inspections/{inspection_id}/launch with a new Idempotency-Key, then open the new link. This resumes the same inspection; the operator still needs to sign in and have the required permissions.

What your integration should save

Data	Why
Group + external vehicle and reservation IDs	Reconcile exactly the same records after retries or staff changes
Public Rental and inspection IDs	Open and poll the intended workflow without searching by private Kernel IDs
Planning entry ID	Confirm which calendar occupation represents the synchronized booking
One idempotency key per command	Replay safely if a creation response is lost
Event cursor and processed event IDs	Recover and deduplicate webhook notifications
Report ID, kind, version and content hash	Archive departure and comparison revisions independently

In connected scenarios, keep the API key and webhook secret on your backend. Do not use the launch URL as a durable identifier: renew it when needed. The getting-started guide shows the first requests, and the Rental API reference defines the exact fields.