Scenari Rental: applicazione, API e webhook

Prima degli scenari: chi crea cosa?

Il tuo gestionale gestisce prenotazione, prezzi, pagamenti e decisioni commerciali. TrakarIA gestisce l’ispezione fisica: consegna, rientro, prove, confronto e report. Lo stesso veicolo può partecipare a molti noleggi successivi.

Accesso	Chi lo usa?	A cosa serve?
Chiave API del gruppo	Il backend del gestionale	Sincronizzare veicoli e dossier, aprire ispezioni e leggere risultati. Non inserirla mai nel browser dell’operatore.
Account TrakarIA	La persona che svolge l’ispezione	Accedere all’applicazione, scattare foto e convalidare. La chiave API non sostituisce questo account.

Scegli lo scenario in base all’intento operativo

Scenario	Quando usarlo	Comportamento API richiesto
Prenotazione anticipata	La prenotazione è nota prima del ritiro	Sincronizza planning e contesto cliente facoltativo prima della consegna fisica
Consegna senza prenotazione completa	Il cliente arriva prima che tutti i dati siano disponibili	Crea il Rental con identificativi stabili, poi arricchiscilo con una revisione più recente
Rientro con variazione	Vuoi percorrere l’intero ciclo	Conserva la baseline di consegna, convalida il rientro e recupera il confronto
Annullamento	La prenotazione è annullata prima dell’ispezione	Annulla il Rental e libera il planning senza eliminare la traccia di audit

La sincronizzazione è un’azione esplicita: il backend invia il veicolo con PUT /v1/vehicles/by-external/{external_id} e il dossier con PUT /v1/rentals/by-external/{external_id}. Il Rental appare subito nel planning. Per crearlo bastano l’ID esterno nella route e vehicle_external_id; date, riferimenti, luoghi, contatto e conducenti possono arrivare prima, durante la consegna o in seguito con una revisione più recente. Senza partenza pianificata si usa l’ora di creazione; senza rientro il planning resta aperto. Riutilizza gli stessi ID esterni per aggiornare le stesse risorse. Senza queste chiamate, nessuna prenotazione viene sincronizzata automaticamente.

Il backend prepara poi l’ispezione con POST /v1/rentals/{rental_id}/inspections, prima per departure e poi per return. Il launch_url apre soltanto il flusso corretto: l’operatore resta autenticato con il proprio account.

Dopo la convalida esistono al massimo due tipi ufficiali: departure e comparison. Entrambi sono disponibili in JSON e PDF; il PDF può arrivare dopo il JSON. GET /v1/rentals/{rental_id}/report elenca gli ID correnti, GET /v1/reports/{report_id} legge il JSON e la route /pdf scarica il documento.

I webhook sono facoltativi. Configura una destinazione sulla chiave e sottoscrivi rental.departure.completed, rental.return.completed ed eventualmente rental.report.pdf_ready. Il backend verifica la firma e recupera il report dall’API; il webhook non contiene il report completo. In assenza di una destinazione usa GET /v1/events e le route dei report. Non confondere i comandi API in uscita con gli eventi inviati al ricevitore.

Dopo una convalida il backend segue questa sequenza:

1. l’ispezione pubblica diventa completed;
2. arriva il webhook firmato oppure l’evento viene recuperato da GET /v1/events;
3. il backend rilegge l’indice e archivia il JSON immutabile;
4. richiede il PDF; 202 significa che deve rispettare Retry-After o seguire il job.

Scenario 1: gestionale collegato con pulsante “Apri ispezione”

1. Il backend invia i due PUT per FLEET-42 e RES-1042, conserva Rental id e planning.entry_id e usa revisioni sorgente strettamente crescenti per le modifiche.
2. Alla consegna chiama l’endpoint delle ispezioni con {"type":"departure"} e un Idempotency-Key, salva l’ID e mostra un pulsante verso il launch_url.
3. L’operatore apre il link, accede con il proprio account, fotografa il veicolo e convalida. Il link non sostituisce i permessi personali.
4. Dopo rental.departure.completed, oppure tramite polling, il backend legge l’indice, archivia il report departure e scarica il PDF quando pronto.
5. Al rientro usa lo stesso endpoint con {"type":"return"} e una nuova chiave d’idempotenza. L’operatore convalida il confronto.
6. rental.return.completed segnala il report comparison. Le decisioni di fatturazione restano nel gestionale.

Scenario 2: gestionale collegato senza pulsante

La chiave API è comunque necessaria. Il backend sincronizza veicolo e prenotazione e prepara le ispezioni, ma può ignorare il launch_url. L’operatore apre l’applicazione TrakarIA, seleziona gruppo e veicolo e riprende l’ispezione già preparata, senza creare un secondo noleggio. Report e webhook funzionano come nello scenario 1.

Scenario 3: tutto in TrakarIA, senza integrazione API

Non esistono chiave né sincronizzazione. L’operatore usa il proprio account, seleziona o crea il veicolo, completa consegna e rientro sullo stesso ciclo e consulta i risultati nell’applicazione. Il gestionale esterno non riceve automaticamente prenotazioni, webhook o report. Un ciclo creato soltanto nell’app non viene automaticamente collegato a un futuro dossier /v1/rentals.

Scenario 4: cambia una prenotazione o un report

• Prima della prima ispezione: aggiorna i campi supportati tramite PUT .../by-external/{external_id} o PATCH /v1/rentals/{rental_id} con un marcatore sorgente più recente. Dopo 409, leggi il dossier corrente.
• Annullamento prima della consegna: POST /v1/rentals/{rental_id}/cancel annulla dossier e voce di planning.
• Dopo l’avvio: il veicolo è bloccato; dopo la consegna si bloccano anche date e luoghi previsti. Una correzione consentita crea una nuova versione immutabile.
• Dopo la correzione: archivia ogni nuovo report_id e versione. rental.report.corrected può notificare il cambiamento.

Scenario 5: il ricevitore webhook è offline

Verifica ogni firma, deduplica per webhook-id e recupera la risorsa corrente. Dopo l’interruzione chiama GET /v1/events con il cursore salvato o created_after; avanza il cursore soltanto dopo l’elaborazione. Gli eventi restano disponibili per 30 giorni.

Scenario 6: il link dell’ispezione è scaduto

Leggi GET /v1/inspections/{inspection_id}. Se l’ispezione è ancora aperta, chiama POST /v1/inspections/{inspection_id}/launch con un nuovo Idempotency-Key e apri il nuovo link. Riprende la stessa ispezione; l’operatore deve comunque autenticarsi.

Dati da conservare

Dato	Perché
Gruppo e ID esterni del veicolo e della prenotazione	Riconciliare esattamente gli stessi record dopo tentativi o cambi di personale
ID pubblici Rental e ispezione	Aprire e interrogare il flusso previsto senza ID privati del Kernel
ID della voce di planning	Confermare quale occupazione rappresenta la prenotazione sincronizzata
Una chiave d’idempotenza per comando	Ripetere in sicurezza un comando se la risposta è persa
Cursore eventi e ID già elaborati	Recuperare e deduplicare le notifiche
ID, tipo, versione e hash del report	Archiviare separatamente le revisioni di consegna e confronto

Mantieni chiave API e segreto webhook esclusivamente nel backend. Non usare il launch_url come identificativo durevole: rinnovalo quando necessario. La guida introduttiva mostra le prime richieste; il riferimento API Rental definisce i campi esatti.