Scegliere un modello d'integrazione

L’ispezione viene sempre completata da una persona autorizzata nell’applicazione TrakarIA. La prima decisione è chi crea il dossier e prepara l’ispezione. La connessione API e il pulsante di apertura sono scelte indipendenti.

Modello	Cosa fa il tuo sistema	Cosa fa l’operatore	Adatto a
Solo applicazione	Nessuna chiamata API e nessuna prenotazione sincronizzata	Seleziona o crea il veicolo, avvia consegna e rientro e inserisce i dati in TrakarIA	Team senza integrazione con il gestionale
API, senza pulsante	Sincronizza veicolo e dossier, visibile subito nel planning, quindi prepara consegna e rientro	Trova l’ispezione preparata nel planning e la convalida	Software collegato; team già operativo in TrakarIA
API con apertura diretta	Esegue le stesse chiamate e mostra il launch_url temporaneo	Apre direttamente il flusso corretto, accede e lo convalida	Esperienza integrata nel gestionale

I cicli creati soltanto nell’applicazione non diventano automaticamente dossier /v1/rentals se l’API viene collegata in seguito.

Percorso collegato

1. Il backend invia il contesto del veicolo e del dossier usando la chiave del gruppo. Il Rental appare subito nel planning. Nel corpo è obbligatorio soltanto l’identificativo esterno del veicolo; il resto può arrivare in anticipo, alla consegna o con una revisione successiva. Non eseguire queste chiamate dal browser del cliente.
2. Il backend chiama POST /v1/rentals/{rental_id}/inspections con type: departure o return e un Idempotency-Key.
3. La risposta contiene ID ispezione e launch_url temporaneo. La tua applicazione può mostrare un pulsante che apre quel link, in una nuova scheda o con una normale navigazione.
4. Il link conduce al flusso TrakarIA appropriato. Se non ha una sessione attiva, l’operatore accede. TrakarIA verifica appartenenza al gruppo e permessi personali.
5. Dopo la convalida umana, il backend riceve un evento firmato oppure recupera gli eventi da GET /v1/events, quindi legge il report autenticato.

Il link scade e può essere rinnovato con POST /v1/inspections/{inspection_id}/launch. È un aiuto alla navigazione, non un token di accesso: non inserirlo in log, analytics o pagine pubbliche. Una nuova scheda o la navigazione principale resta sempre disponibile. TrakarIA può anche essere incorporata nella tua applicazione; contatta l’assistenza per far verificare e autorizzare il dominio. Le applicazioni non approvate restano bloccate.

Il passaggio può fermarsi alla presa in carico

Se il personale lavora già in TrakarIA, non serve un pulsante. Il backend necessita comunque della chiave API per sincronizzare veicolo e dossier e preparare l’ispezione. L’operatore la riprende dall’applicazione TrakarIA. Può anche aprire una prenotazione sincronizzata o pianificata manualmente e avviare il Checkout dal planning. Se il Checkout parte senza selezione esplicita, TrakarIA propone le prenotazioni disponibili del veicolo e consente anche un Checkout indipendente per un cliente senza prenotazione. L’associazione porta il contesto, ma non blocca mai la consegna fisica.

Quando aggiungere callback

Usa i webhook se il sistema deve reagire subito alla convalida. Trattali come notifiche: verifica la firma, deduplica per ID e rileggi la risorsa corrente. Usa GET /v1/events per il recupero. rental.departure.completed indica che il JSON iniziale è pronto; rental.return.completed indica che il confronto è pronto. Il PDF può diventare disponibile più tardi e dispone di un proprio evento.