Sincronizzazione ed errori

Mantieni gli aggiornamenti in ordine

Gli upsert di veicoli e dossier Rental sono circoscritti alla tua organizzazione e al tuo external_id. Alla creazione invia tutto il contesto disponibile. Per gli aggiornamenti successivi che modificano i dati, invia source_revision oppure source_updated_at. Preferisci una revisione intera del sistema sorgente e incrementala rigorosamente. Dopo aver memorizzato una revisione, un timestamp non può sostituirla. Le proprietà omesse conservano il valore corrente; null esplicito cancella soltanto i campi nullable. Le proprietà sconosciute sono rifiutate.

Continuano a valere le regole del ciclo Rental: l’assegnazione del veicolo si blocca all’avvio della prima ispezione; dopo la consegna alcuni dati pianificati non sono più modificabili; dopo il completamento restano possibili soltanto le correzioni di report previste. Un aggiornamento in conflitto o più vecchio restituisce un errore strutturato. Leggi la risorsa corrente prima di riprovare con una nuova revisione.

Rendi sicuri i nuovi tentativi dei comandi POST

Ogni scrittura POST richiede l’header Idempotency-Key. Genera un valore univoco per ciascuna operazione voluta, mantienilo invariato nei tentativi dovuti alla rete e non riutilizzarlo mai con un corpo diverso. La chiave è circoscritta all’organizzazione e conservata per sette giorni. Ripetere lo stesso comando completato restituisce la risposta di successo originale; un riutilizzo in conflitto fallisce.

Il PUT per identificativo esterno è deterministico, ma i marcatori di versione restano necessari per gli aggiornamenti modificati. Non creare un nuovo identificativo esterno per ritentare lo stesso veicolo o la stessa prenotazione.

Gestisci gli errori

Gli errori API usano application/problem+json con code stabile, status HTTP, detail leggibile, request_id, retryable ed eventuali errors riferiti ai campi. Quando contatti l’assistenza, registra il request_id, senza mai registrare segreti o byte di documenti privati.

L’URL type identifica una pagina pubblica dell’errore. Per esempio, INVALID_API_KEY spiega la causa e l’azione successiva. Ogni codice emesso dal middleware dispone di una pagina in tutte le lingue supportate.

Risposta	Azione
401	Verifica se la chiave è valida, scaduta o revocata.
403	Verifica le autorizzazioni della chiave e l’accesso commerciale dell’organizzazione.
409	Esamina la risorsa corrente o il conflitto di idempotenza prima di modificare la richiesta.
422	Correggi i campi indicati; non ripetere lo stesso corpo non valido.
429	Rispetta Retry-After e gli header del limite di frequenza.
503	Riprova secondo retryable e l’eventuale header Retry-After.

GET /v1/capabilities restituisce quote, limiti dei file e valori di conservazione effettivi per la chiave. Il riferimento API è la fonte autorevole per le possibili risposte di ogni route.