Scénarios Rental : application, API et webhooks

Avant les scénarios : qui crée quoi ?

Vous pouvez exécuter le scénario 1 de bout en bout dans le TrakarIA Integration Lab. Commencez en simulation ou utilisez une clé API de groupe pour envoyer des données de test vers l’environnement sélectionné par le Lab déployé. L’interface du Lab est en anglais.

Votre logiciel de location reste responsable de la réservation, des prix, des paiements et des décisions commerciales. TrakarIA gère l’inspection physique du véhicule : départ, retour, preuves, comparaison et rapports. Un véhicule peut servir à plusieurs locations successives.

Deux accès différents interviennent si vous reliez les logiciels :

Accès	Qui l’utilise ?	À quoi sert-il ?
Clé API du groupe	Le serveur de votre logiciel de location	Synchroniser véhicule et dossier, ouvrir les inspections, lire les résultats. Elle ne va jamais dans le navigateur de l’agent.
Compte TrakarIA	Le collaborateur qui réalise l’inspection	Se connecter à l’application, prendre les photos et valider. Une clé API ne remplace pas ce compte.

La synchronisation est une action précise : votre serveur envoie PUT /v1/vehicles/by-external/{external_id} pour le véhicule et PUT /v1/rentals/by-external/{external_id} pour le dossier lié à sa réservation. Le dossier apparaît immédiatement dans le planning TrakarIA. Seuls l’identifiant externe de la route et vehicle_external_id sont nécessaires à la création ; dates, références, lieux, contact et conducteurs peuvent être renseignés à l’avance, au moment du handover physique ou plus tard avec une révision source supérieure. Sans date de départ, l’heure de création est utilisée ; sans date de retour, l’entrée planning reste ouverte. TrakarIA renvoie les identifiants publics du dossier et de l’entrée planning. Réutilisez les mêmes identifiants externes pour mettre à jour les mêmes ressources. Sans ces appels, aucune réservation ne se synchronise toute seule.

Pour qu’un dossier synchronisé soit associé à une inspection utilisable par l’API publique, votre serveur appelle aussi POST /v1/rentals/{rental_id}/inspections pour le départ, puis pour le retour. Le launch_url renvoyé sert seulement à ouvrir le bon parcours dans TrakarIA. L’agent peut retrouver le parcours dans l’application sans cliquer sur ce lien, mais la création du dossier et l’association de l’inspection restent des étapes API.

Une fois l’inspection validée, deux rapports officiels peuvent exister : departure après le départ, puis comparison après le retour. Chacun est disponible en JSON et en PDF ; le PDF peut être prêt après le JSON. Il n’existe pas de troisième type de rapport return. GET /v1/rentals/{rental_id}/report donne les identifiants des rapports disponibles ; GET /v1/reports/{report_id} lit un JSON et GET /v1/reports/{report_id}/pdf télécharge son PDF.

Les webhooks sont optionnels. Si vous voulez que votre serveur soit averti automatiquement, configurez sur sa clé API une destination HTTP ou HTTPS dans Organisation → Intégrations → Clés API → Gérer les webhooks. Sélectionnez rental.departure.completed, rental.return.completed et éventuellement rental.report.pdf_ready. TrakarIA envoie un POST signé à cette URL ; votre serveur vérifie la signature et lit le rapport par l’API. Le webhook ne contient pas le rapport complet. Sans destination webhook, votre serveur peut consulter GET /v1/events et les routes de rapport. Sans intégration API, votre logiciel ne reçoit ni ces événements ni les rapports par l’API. Voir Webhooks et reprise.

Scénario 1 : logiciel connecté, bouton « Ouvrir l’inspection »

Prérequis : un administrateur a créé une clé API et votre serveur la conserve. Pour les notifications automatiques, il a aussi configuré une destination webhook. Exemple : le véhicule FLEET-42 est réservé sous RES-1042 dans votre logiciel.

1. Votre serveur envoie PUT /v1/vehicles/by-external/FLEET-42, puis PUT /v1/rentals/by-external/RES-1042 avec vehicle_external_id: FLEET-42. La réservation apparaît immédiatement dans le planning. Il conserve l’id public du dossier Rental et planning.entry_id. Lors d’une modification ultérieure, il envoie un source_revision strictement plus récent ; l’affectation du véhicule est figée dès le début de l’inspection.
2. Au départ, votre serveur appelle POST /v1/rentals/{rental_id}/inspections avec {"type":"departure"} et un Idempotency-Key. Il conserve l’identifiant d’inspection et affiche un bouton ouvrant le launch_url reçu.
3. Le collaborateur ouvre ce lien, se connecte à son compte TrakarIA, vérifie le véhicule, prend les photos et valide le départ. Le lien n’autorise pas l’inspection à lui seul : TrakarIA vérifie ses droits.
4. Si le webhook a été configuré, votre serveur reçoit rental.departure.completed. Il vérifie la signature, lit GET /v1/rentals/{rental_id}/report, puis le JSON du rapport departure par son report_id. Il récupère le PDF lorsqu’il est prêt. Sans webhook, il consulte l’API pour connaître le résultat.
5. Au retour, votre serveur appelle la même route d’inspection avec {"type":"return"} et un nouvel Idempotency-Key, puis ouvre le nouveau launch_url pour le collaborateur. Celui-ci valide la comparaison dans TrakarIA.
6. Si le webhook a été configuré, rental.return.completed avertit votre serveur que le JSON du rapport comparison est prêt. Votre serveur lit l’index des rapports, archive le report_id et la version, puis télécharge le PDF lorsqu’il est prêt. Les décisions de facturation restent dans votre logiciel.

Scénario 2 : logiciel connecté, mais aucun bouton de lancement

La clé API reste nécessaire. Seul le bouton de navigation disparaît ; votre serveur synchronise toujours le véhicule et la réservation.

1. Votre serveur effectue les deux PUT du scénario 1 et appelle POST /v1/rentals/{rental_id}/inspections pour préparer le départ. Il peut ignorer le launch_url.
2. Le collaborateur ouvre lui-même l’application TrakarIA, sélectionne le bon groupe et le bon véhicule, puis reprend l’inspection de départ déjà préparée. Il ne crée pas une seconde location pour cette réservation.
3. Après validation, le serveur récupère le rapport de départ comme dans le scénario 1. Pour le retour, il prépare {"type":"return"} par l’API ; le collaborateur reprend le retour du même véhicule dans TrakarIA. Les webhooks et rapports suivent le même parcours que dans le scénario 1, si la destination est configurée.

Ce mode convient aux équipes qui travaillent déjà dans TrakarIA. Ouvrir l’application à la main ne remplace pas les appels de synchronisation et de préparation effectués par votre serveur.

Scénario 3 : tout se fait dans TrakarIA, sans intégration API

Ici, il n’y a ni clé API partenaire ni synchronisation avec le logiciel de location. Le collaborateur utilise uniquement son compte TrakarIA et les droits de son groupe.

1. Dans l’espace Rental, il choisit un véhicule existant ou le crée dans l’application, puis démarre le départ. TrakarIA crée le cycle d’inspection ; le collaborateur renseigne dans le parcours les informations de location nécessaires, par exemple une référence de réservation s’il en possède une.
2. Il capture les preuves et valide le départ. Plus tard, il retrouve ce même véhicule et ce même cycle, démarre le retour et valide la comparaison.
3. L’équipe consulte les résultats dans TrakarIA. Aucune réservation de votre logiciel n’a été importée automatiquement, et ce logiciel ne reçoit pas de webhook ou de rapport par l’API publique.

Un cycle créé uniquement dans l’application n’est pas automatiquement lié à un dossier /v1/rentals de l’API publique. Si vous ajoutez une intégration plus tard, prévoyez explicitement le rapprochement des véhicules et des locations ; ne supposez pas que les anciens cycles apparaîtront dans l’API.

Scénario 4 : la réservation ou le rapport change

• Avant la première inspection : pour un dossier connecté à l’API, votre serveur actualise les champs autorisés par PUT .../by-external/{external_id} ou PATCH /v1/rentals/{rental_id} avec un marqueur de source plus récent. Après un 409, il lit le dossier actuel avant de réessayer.
• Annulation avant le départ : POST /v1/rentals/{rental_id}/cancel annule à la fois le dossier et son entrée planning.
• Après le début de l’inspection : l’affectation du véhicule est figée. Après validation du départ, les dates et lieux prévus sont également figés. Une correction permise par le parcours peut créer une nouvelle version immuable du rapport de départ ou de comparaison.
• Après correction : votre serveur archive chaque nouveau report_id et sa version ; il ne remplace pas silencieusement le rapport précédent. Le webhook rental.report.corrected peut l’en avertir si une destination est configurée.

Consultez Rapports et preuves pour distinguer version actuelle et historique. Ces routes concernent les dossiers créés et associés à l’API publique.

Scénario 5 : votre récepteur webhook est indisponible

Ce scénario concerne uniquement une intégration API ayant configuré une destination webhook. Les envois peuvent être répétés ou arriver dans le désordre : vérifiez chaque signature, dédupliquez par webhook-id et relisez le rapport actuel. Après une interruption, appelez GET /v1/events avec le curseur conservé ou un created_after adapté ; n’avancez le curseur qu’après traitement. Les événements restent disponibles 30 jours. Consultez Webhooks et reprise.

Scénario 6 : un lien d’inspection a expiré

Dans les scénarios connectés, lisez GET /v1/inspections/{inspection_id}. Si l’inspection est toujours ouverte, appelez POST /v1/inspections/{inspection_id}/launch avec un nouvel Idempotency-Key, puis ouvrez le nouveau lien. Vous reprenez la même inspection ; l’agent doit toujours se connecter et disposer des droits nécessaires.

Données à conserver côté intégration

Donnée	Utilité
Groupe et identifiants externes du véhicule et de la réservation	Retrouver exactement les mêmes dossiers après une reprise ou un changement d’agent
Identifiants publics Rental et inspection	Ouvrir et suivre le bon parcours sans utiliser d’identifiant Kernel privé
Identifiant d’entrée planning	Confirmer quelle occupation du calendrier représente la réservation synchronisée
Une clé d’idempotence par commande	Rejouer un appel si sa réponse a été perdue
Curseur d’événements et identifiants déjà traités	Rattraper et dédupliquer les notifications webhook
Identifiant, type, version et empreinte du rapport	Archiver séparément les versions de départ et de comparaison

Dans les scénarios connectés, conservez la clé API et le secret webhook sur votre serveur. Ne conservez pas le lien de lancement comme identifiant durable : renouvelez-le si besoin. Le guide de démarrage montre les premières requêtes et la référence API Rental définit les champs exacts.