Autorizzazioni delle chiavi API

Le autorizzazioni limitano ciò che una singola integrazione software può fare nel gruppo associato alla chiave. Non identificano una persona, non consentono l’accesso a un altro gruppo e non sostituiscono l’abbonamento Rental dell’organizzazione. Le azioni umane aperte tramite un launch_url richiedono comunque un utente TrakarIA autenticato con i permessi appropriati nel gruppo.

Usa una chiave distinta per ogni sistema e concedi soltanto le operazioni effettivamente necessarie. Potrai così ruotare o revocare un’integrazione senza interrompere le altre e ridurre l’impatto di un’eventuale esposizione della credenziale.

Riferimento delle autorizzazioni

Ogni operazione dell’API pubblica verifica un’autorizzazione precisa. Un’autorizzazione di lettura non concede mai la scrittura. In API e integrazioni, selezionare la scrittura seleziona anche la lettura corrispondente, quando esiste; selezionare l’estrazione degli allegati seleziona anche la lettura degli allegati. È una comodità dell’interfaccia di creazione, non una relazione implicita tra le autorizzazioni API.

Autorizzazione	Cosa consente	Operazioni pubbliche
vehicles:read	Riconciliare e leggere i veicoli del gruppo della chiave.	GET /v1/vehicles, GET /v1/vehicles/{vehicle_id}
vehicles:write	Creare o sincronizzare un veicolo tramite l’identificativo esterno del tuo sistema.	PUT /v1/vehicles/by-external/{external_id}
rentals:read	Riconciliare e leggere i dossier Rental e le relative ispezioni preparate.	GET /v1/rentals, GET /v1/rentals/{rental_id}, GET /v1/inspections/{inspection_id}
rentals:write	Creare, sincronizzare, aggiornare o annullare un dossier Rental.	PUT /v1/rentals/by-external/{external_id}, PATCH /v1/rentals/{rental_id}, POST /v1/rentals/{rental_id}/cancel
inspections:write	Preparare o riprendere un’ispezione di consegna/rientro e rinnovarne il link temporaneo. Non permette all’API di convalidare l’ispezione umana.	POST /v1/rentals/{rental_id}/inspections, POST /v1/inspections/{inspection_id}/launch
evidence:read	Elencare e scaricare le prove fotografiche originali autorizzate, singolarmente o in archivio ZIP.	GET /v1/inspections/{inspection_id}/evidence, GET /v1/evidence/{evidence_id}/content, GET /v1/inspections/{inspection_id}/evidence/archive, GET /v1/rentals/{rental_id}/evidence/archive
attachments:read	Elencare e scaricare i documenti privati forniti dal tuo software.	GET /v1/rentals/{rental_id}/attachments, GET /v1/attachments/{attachment_id}/content
attachments:write	Caricare un documento privato in un dossier Rental.	POST /v1/rentals/{rental_id}/attachments
attachments:extract	Avviare l’estrazione a pagamento di una patente già caricata. I dati estratti devono comunque essere verificati.	POST /v1/attachments/{attachment_id}/extract
reports:read	Individuare, leggere e scaricare report di consegna/confronto e relativi PDF.	GET /v1/rentals/{rental_id}/report, GET /v1/rentals/{rental_id}/reports, GET /v1/reports/{report_id}, GET /v1/reports/{report_id}/pdf
events:read	Recuperare gli eventi del ciclo di vita persi durante un’interruzione dei webhook.	GET /v1/events
jobs:read	Verificare stato e risultato sicuro di un’operazione asincrona, inclusa l’estrazione documentale.	GET /v1/jobs/{job_id}

GET /v1/capabilities richiede una chiave attiva valida, ma nessuna autorizzazione operativa aggiuntiva. Restituisce funzionalità e limiti effettivi del prodotto, non l’elenco completo delle autorizzazioni della chiave.

Le destinazioni webhook sono gestite separatamente da un amministratore del gruppo autenticato in API e integrazioni. events:read controlla soltanto GET /v1/events: non crea una destinazione, non concede accesso all’amministrazione e non sostituisce la verifica della firma.

Set di autorizzazioni comuni

Esigenza dell’integrazione	Minimo consigliato
Verificare connettività e funzionalità commerciali	Una chiave valida; nessun’altra autorizzazione operativa
Sincronizzare flotta e prenotazioni	vehicles:read, vehicles:write, rentals:read, rentals:write
Preparare le ispezioni di consegna e rientro	Aggiungi inspections:write
Consumare foto d’ispezione e report finali	Aggiungi evidence:read, reports:read
Caricare documenti ed estrarre una patente	Aggiungi attachments:read, attachments:write, attachments:extract, jobs:read
Recuperare eventi dopo un’interruzione dei webhook	Aggiungi events:read
Implementare l’intero ciclo Rental	Seleziona tutte le autorizzazioni usate dagli scenari scelti; ometti quelle di estrazione o allegati se tali funzioni non sono utilizzate

Sono suggerimenti orientati al flusso. Il requisito esatto di ogni operazione è indicato come Required permission nel riferimento API.

Diagnosticare un 403

Se una chiave valida non possiede l’autorizzazione richiesta, l’API restituisce 403 con codice INSUFFICIENT_SCOPE. La risposta indica l’autorizzazione mancante in errors[0].meta.required. Aggiungila a una chiave sostitutiva solo se l’integrazione necessita davvero di quell’operazione.

Un 403 può anche indicare che la risorsa non appartiene al gruppo della chiave, che l’organizzazione o la funzionalità non è disponibile, oppure che il piano commerciale non include l’operazione. Concedere tutte le autorizzazioni non aggira questi controlli. Consulta autenticazione e accesso e sincronizzazione ed errori.