Choisir un mode d'intégration

L’inspection elle-même est toujours réalisée par une personne autorisée dans l’application TrakarIA. La question est de savoir qui crée le dossier et prépare l’inspection. Une connexion API et un bouton de lancement sont deux choix distincts.

Mode	Rôle de votre système	Rôle du collaborateur	Cas adapté
Application seule	Aucun appel à l’API publique : aucune réservation n’est synchronisée	Choisit ou crée le véhicule, démarre départ et retour, saisit les informations utiles dans TrakarIA	Équipe sans intégration au logiciel de location
API, sans bouton	Synchronise véhicule et dossier ; la réservation apparaît immédiatement au planning, puis le système prépare départ et retour par l’API	Voit la réservation au planning, retrouve l’inspection préparée et la valide	Logiciel connecté ; équipe qui travaille déjà dans TrakarIA
API + bouton	Même synchronisation planning et même préparation, puis affiche le launch_url renvoyé	Ouvre le lien, se connecte et valide dans TrakarIA	Logiciel de location avec un bouton « Ouvrir l’inspection »

Les webhooks et la lecture des rapports par API sont des capacités des deux modes connectés. Une destination webhook doit être configurée pour recevoir les notifications ; elle n’est pas créée par la simple synchronisation. Dans le mode « application seule », votre logiciel ne reçoit rien automatiquement. Les cycles déjà créés uniquement dans l’application ne deviennent pas automatiquement des dossiers /v1/rentals lorsque vous ajoutez l’API plus tard.

Le parcours avec lien

1. Votre serveur envoie le véhicule et le contexte du dossier avec sa clé API de groupe. Le dossier apparaît immédiatement dans le planning. Seul l’identifiant externe du véhicule est obligatoire dans le corps ; le reste du contexte peut être envoyé à l’avance, au moment du handover ou plus tard avec une révision source supérieure. Cet appel se fait côté serveur, jamais depuis le navigateur du client.
2. Votre serveur appelle POST /v1/rentals/{rental_id}/inspections avec type: departure ou return et un Idempotency-Key.
3. La réponse contient un identifiant d’inspection et un launch_url temporaire. Votre application peut afficher un bouton qui ouvre ce lien. Un nouvel onglet ou une navigation classique sont les parcours prévus.
4. Le lien mène au parcours TrakarIA correspondant. Si l’agent n’a pas de session active, il se connecte. TrakarIA vérifie ensuite son accès au groupe et ses droits.
5. Après validation humaine, votre serveur reçoit un événement signé ou consulte GET /v1/events pour rattraper un événement manqué, puis lit le rapport par l’API authentifiée.

Le lien expire ; POST /v1/inspections/{inspection_id}/launch permet de le renouveler. C’est une aide à la navigation, pas un jeton d’accès. Évitez de l’enregistrer dans les journaux, les outils d’analyse ou les pages publiques. L’intégration de l’inspection dans une iframe et un SDK de capture sans interface ne font pas partie du contrat public actuel. Prévoyez une navigation normale pour le moment.

Passer simplement le relais à TrakarIA

Si vos collaborateurs travaillent déjà dans TrakarIA, le bouton n’est pas nécessaire. Votre serveur conserve sa clé API : il synchronise le véhicule et le dossier, ce qui rend immédiatement la réservation visible dans le planning, puis appelle POST /v1/rentals/{rental_id}/inspections avant que le collaborateur ne reprenne l’inspection préparée dans l’application TrakarIA. Cette synchronisation peut avoir lieu à l’avance ou pendant le handover physique. Le bouton sert uniquement à ouvrir directement cette inspection. Consultez les scénarios détaillés pour distinguer ce mode d’un parcours entièrement manuel.

Quand ajouter les notifications

Utilisez les webhooks si votre système doit réagir rapidement à une validation. Ce sont des notifications : vérifiez la signature, dédupliquez par identifiant d’événement et relisez la ressource actuelle. GET /v1/events sert à rattraper une interruption. rental.departure.completed signifie que le JSON de départ est disponible ; rental.return.completed signifie que le JSON de comparaison l’est. Le PDF peut être prêt plus tard et dispose d’un événement distinct.