API reference
Documentazione Passy
Le informazioni essenziali per iniziare la tua integrazione: autenticazione, risposte API e gestione degli errori.
Autenticazione
Per ottenere un token è necessario avere i seguenti parametri:
Authorization: Bearer <access_token>tenantId- Identificativo del tenant Microsoft Entra.
scope- Ambito di accesso richiesto per il token.
clientId- Identificativo dell’applicazione client.
clientSecret- Segreto dell’applicazione client.
Errori e limiti delle chiamate
- 401 / 403
- Autenticazione e autorizzazione
- 429
- Limite delle chiamate
- 481
- Errore applicativo previsto
- 500
- Errore imprevisto
Gli errori applicativi previsti vengono restituiti con codice HTTP 481 e utilizzano il payload comune
CustomExceptionModel. Rientrano in questa categoria le violazioni delle regole di business o di coerenza e
i conflitti sulle risorse gestiti a livello applicativo. CoherenceViolation viene associato a
ErrorCode.Inconsistency, mentre ResourceContention viene associato a
ErrorCode.Conflict. I campi Category/CategoryStr identificano
l'area funzionale interessata (ad esempio User, Badge, Location, Access, Scheduler, Oggetto o Action).
Per ogni operazione documentata, la risposta HTTP 481 specifica le combinazioni
ErrorCode/Category che possono essere restituite dall'endpoint,
insieme alle condizioni che determinano ciascun errore. Le stesse informazioni sono disponibili anche nel
file OpenAPI tramite l'estensione x-error-cases. Un codice non esplicitamente indicato per una
determinata operazione non deve essere considerato parte del relativo contratto degli errori applicativi.
Gli errori di autenticazione e autorizzazione mantengono i codici di stato HTTP standard (401/403); il superamento dei limiti di frequenza delle richieste (rate limiting) continua a essere restituito con 429, mentre gli errori imprevisti relativi all'infrastruttura, al database e i timeout non riconducibili alla logica applicativa continuano a essere restituiti con 500.
Le API hanno un limite di chiamate: di default 50 chiamate al minuto per ogni applicazione client, personalizzabile per ogni cliente. Una chiamata oltre il limite viene rifiutata subito con 429; il conteggio si azzera ogni minuto.
Domande frequenti
FAQ API
Le risposte alle domande più frequenti su utenti, chiavi e accessi. Tutto quello che serve per configurare la tua integrazione con Passy.