Per iniziare

L’API pubblica supporta attualmente Rental. Consente al tuo sistema di sincronizzare veicoli e pratiche di noleggio, preparare ispezioni e recuperare risultati validati. Il riferimento API è il contratto esatto di richieste e risposte.

1. Creare una chiave

Un amministratore dell’organizzazione apre API e integrazioni nell’applicazione TrakarIA e crea una chiave API. L’accesso dipende dal piano Rental dell’organizzazione. Usa una chiave distinta per ogni integrazione; il segreto completo appare una sola volta. Consulta Autenticazione.

L’URL di base è https://api.trakaria.com. Le richieste effettuate con la chiave modificano i dati reali dell’account.

2. Verificare accesso e limiti effettivi

Imposta la chiave nel terminale senza inserirla nel controllo versione ed effettua prima una richiesta in sola lettura:

export TRAKARIA_API_KEY='your-api-key'
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  https://api.trakaria.com/v1/capabilities

La risposta indica funzioni e limiti Rental attivi per l’organizzazione. 401 segnala una credenziale non valida o scaduta; 403 può indicare che l’operazione o il piano non è disponibile. Consulta Sincronizzazione ed errori.

3. Sincronizzare un veicolo e una pratica Rental

Per una prova usa identificativi esterni univoci e riconoscibili, senza dati reali dei clienti. Le chiamate seguenti creano record nell’account. Sostituisci i valori di esempio; riutilizza lo stesso identificativo esterno per aggiornare la stessa risorsa. Conserva gli id pubblici restituiti.

curl --fail-with-body --silent --show-error \
  -X PUT 'https://api.trakaria.com/v1/vehicles/by-external/demo-vehicle-001' \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"plate":"AA-123-AA","name":"Airport car","photo_url":"https://cdn.example.com/fleet/demo-vehicle-001.jpg","make":"Example","model":"Car","trim":"Business","year":2025,"registration_date":"2025-03-20","vehicle_type":"hatchback","energy":"petrol","gearbox":"automatic","transmission":"fwd","color":"Blue","mileage":12000,"source_revision":1}'

curl --fail-with-body --silent --show-error \
  -X PUT 'https://api.trakaria.com/v1/rentals/by-external/demo-reservation-001' \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"vehicle_external_id":"demo-vehicle-001","source_revision":1}'

La seconda richiesta crea immediatamente una voce visibile nella pianificazione. La risposta contiene sia l’id Rental sia planning.entry_id. Nel corpo è obbligatorio soltanto vehicle_external_id; date pianificate, riferimenti, luoghi, contatto e conducenti sono facoltativi. Puoi inviarli in anticipo, alla consegna fisica o successivamente. Senza orario di partenza, TrakarIA usa l’ora di creazione; senza data di rientro, la pianificazione resta aperta.

Per aggiornamenti successivi che modificano il contenuto usa un source_revision strettamente crescente. I campi omessi conservano il valore corrente e viene aggiornata la stessa voce di pianificazione, senza duplicarla. Consulta le regole di sincronizzazione.

Un upsert riuscito assegna inoltre il veicolo all’organizzazione della chiave, rendendolo visibile agli utenti autorizzati del gruppo. Ripetere un upsert invariato riconcilia in sicurezza un’eventuale assegnazione mancante.

Dopo la prova, controlla i record in TrakarIA e ripuliscili con le azioni disponibili al gruppo. L’API può annullare una pratica prima della partenza con POST /v1/rentals/{rental_id}/cancel, annullando anche la voce di pianificazione. Non esiste una rotta generale DELETE per veicoli o pratiche e l’annullamento non cancella la cronologia.

4. Proseguire con l’ispezione

Usa l’id Rental pubblico restituito dalla seconda richiesta, non l’identificativo esterno né quello di pianificazione, per preparare l’ispezione di partenza. La partenza prevista può essere futura.

export RENTAL_ID='rental_...'
export DEPARTURE_IDEMPOTENCY_KEY="departure-${RENTAL_ID}"

curl --fail-with-body --silent --show-error \
  -X POST "https://api.trakaria.com/v1/rentals/${RENTAL_ID}/inspections" \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${DEPARTURE_IDEMPOTENCY_KEY}" \
  -d '{"type":"departure"}'

La chiamata prepara o riprende la stessa ispezione: 201 indica la creazione, 200 che esisteva già. Dopo timeout, perdita di connessione, 503 o REQUEST_ALREADY_PROCESSING, ripeti stesso metodo, percorso e corpo con lo stesso Idempotency-Key. Non creare un’altra pratica o un altro identificativo esterno. Non inviare identificativi di ciclo Kernel, revisioni, ETag, If-Match o expectedRevision: TrakarIA gestisce questi dettagli privati di concorrenza.

Un utente TrakarIA deve autenticarsi per aprire la launch_url e validare le condizioni del veicolo. La chiamata API non esegue questa validazione umana. Dopo la validazione recupera il rapporto di partenza; al rientro prepara un’ispezione return e recupera il rapporto di confronto. Segui il percorso Rental e il riferimento API. Puoi inoltre ricevere webhook firmati e recuperare eventi con GET /v1/events.