Report e prove

I risultati di consegna e rientro sono separati intenzionalmente in versioni immutabili dei report, PDF ufficiali e prove originali protette. Segui i passaggi senza dipendere dai tempi del webhook.

Passaggio 1 — Individua ciò che è pronto

GET /v1/rentals/{rental_id}/report è l’indice corrente. Può mostrare un report departure pronto mentre comparison non è ancora disponibile.

Convalida umana	Fase dell’ispezione	Tipo ufficiale di report
Consegna completata	departure	departure
Rientro completato	return	comparison

Non esiste un tipo ufficiale return: il rientro produce il confronto tra consegna e restituzione. I webhook accelerano la riconciliazione, ma non sono la fonte di verità. Dopo un evento o un recupero, rileggi l’indice.

Passaggio 2 — Archivia il JSON immutabile

1. Chiama GET /v1/rentals/{rental_id}/reports per elencare tutte le versioni disponibili.
2. Chiama GET /v1/reports/{report_id} per la versione da archiviare.
3. Salva ID pubblico, versione e hash del contenuto insieme al record Rental.

Una correzione supportata crea una nuova versione immutabile con nuovo ID e hash; il precedente ID continua a identificare la versione precedente. Non sovrascrivere la cronologia usando soltanto il Rental ID.

Passaggio 3 — Scarica il PDF ufficiale

Chiama GET /v1/reports/{report_id}/pdf.

• 200 restituisce i byte PDF.
• 202 indica che generazione o riparazione è in corso. Rispetta Retry-After, quindi interroga GET /v1/jobs/{job_id} oppure riprova la route PDF.

L’API trasmette il PDF autorizzato e non espone URL permanenti dello storage.

Passaggio 4 — Elenca le prove originali

Chiama GET /v1/inspections/{inspection_id}/evidence separatamente per consegna e rientro. Ogni elemento indica phase, kind, view, zone, l’eventuale danno associato e il content_path pubblico.

GET /v1/evidence/{evidence_id}/content trasmette un’immagine originale autorizzata. Per record storici senza MIME type nello storage, il tipo viene rilevato dall’oggetto invece di produrre un falso errore d’integrità.

Il contratto non espone URL di storage, contorni, maschere, coordinate o render annotati. is_fresh_for_record è una provenienza operativa per l’integrazione autenticata e non appare in report condivisi, PDF o webhook.

Passaggio 5 — Scarica le prove in batch

Ambito	Endpoint	Contenuto
Una ispezione	GET /v1/inspections/{inspection_id}/evidence/archive	Immagini originali della consegna o del rientro
Intero Rental	GET /v1/rentals/{rental_id}/evidence/archive	Ultime prove di consegna e rientro in cartelle separate

Ogni ZIP include manifest.json con metadati pubblici puliti: fase, vista, zona, tipo e gravità del danno, parti interessate, integrità e percorso relativo dell’immagine. Le immagini sono i byte originali senza annotazioni. L’archivio non contiene mai contorni, maschere, livelli di annotazione o URL privati. Il limite effettivo è limits.max_evidence_archive_bytes in GET /v1/capabilities.

Passaggio 6 — Mantieni separati gli allegati

Gli allegati Rental sono documenti privati forniti dal tuo software, non prove ufficiali. Caricali ed elencali tramite /v1/rentals/{rental_id}/attachments. Nel flusso TrakarIA appaiono automaticamente in Documenti aggiuntivi, tramite link autorizzato temporaneo e senza doppio caricamento. Restano contesto in sola lettura e non entrano negli archivi di prove né nel report ufficiale.

La gestione delle immagini resta semplice

La tua integrazione non classifica le immagini né assegna le viste del veicolo. L’operatore acquisisce o carica le immagini in TrakarIA; TrakarIA rileva la vista, raggruppa panoramiche e primi piani e accetta automaticamente le viste rilevate utilizzabili. L’operatore può sempre correggerle.

In caso di correzione manuale, l’interfaccia guida attraverso ogni immagine della vista e salva una decisione coerente per l’intero insieme. Un’elaborazione conclusa più tardi non può rendere silenziosamente incompleta una vista già convalidata. Una vera aggiunta, rimozione o riassegnazione può richiedere una verifica mirata e l’interfaccia torna direttamente alla vista interessata. Questa revisione interna non complica né blocca il contratto API.