FAQ API
Le risposte alle domande più frequenti su utenti, chiavi e accessi. Tutto quello che serve per configurare la tua integrazione con Passy.
27 domande · 7 argomenti
Ambienti e autenticazione
L’URL delle API di produzione è https://api.passy.it/api.
Per l’ambiente di test utilizzate l’URL comunicato da Passy per la vostra integrazione. L’ambiente di test utilizzato negli esempi di integrazione è https://smartkeysws.azurewebsites.net/api.
I parametri di configurazione devono corrispondere all’ambiente utilizzato.
Link alla rispostaSì. Il parametro TenantIdAD è obbligatorio nella richiesta POST /registry/{companyId}/User.
Utilizzate il valore fornito da Passy per lo specifico ambiente. Il valore dell’ambiente di test è diverso da quello di produzione.
Link alla rispostaSono possibili entrambe le configurazioni: credenziali condivise dall’integrazione oppure credenziali dedicate a ciascuna struttura.
Consigliamo credenziali separate per ogni hotel, così che ciascuna possa operare esclusivamente sulla struttura di competenza. La configurazione di credenziali e companyId viene concordata con Passy.
Utenti e scadenza delle chiavi
Se ExpireKey è NULL, viene applicata la durata predefinita configurata. In assenza di una configurazione diversa, la durata è di 365 giorni dalla creazione.
Passy può impostare una durata predefinita concordata con il cliente. Dopo questa configurazione iniziale, la durata scelta verrà applicata anche alle nuove richieste che passano NULL.
Sì. In fase di creazione potete specificare nel campo ExpireKey la data di scadenza desiderata. È inoltre disponibile un’API per aggiornare la scadenza della chiave, anche se non ancora descritta nello Swagger condiviso: richiedete a Passy i dettagli dell’operazione.
Non è quindi necessario prevedere la cancellazione e la ricreazione periodica degli utenti per gestire la scadenza. Una data futura definisce comunque una scadenza: non equivale a una chiave senza termine.
Link alla rispostaSono consentite lettere da A a Z, maiuscole e minuscole, cifre da 0 a 9 e i seguenti caratteri speciali:
' . - _ ! # ^ ~
Non sono ammessi caratteri accentati. Lo Username identifica l’utente, compare nella reportistica e viene utilizzato per l’accesso tramite smartphone. È quindi consigliabile un formato semplice e riconoscibile, ad esempio <struttura>.nome.cognome, assicurandone l’univocità.
Per approfondire, consultate i criteri Microsoft per i nomi utente.
Link alla rispostaL’eliminazione di un utente comporta automaticamente:
- La cancellazione dei suoi permessi.
- La rimozione di tutte le appartenenze ai gruppi di utenti.
- La rimozione delle associazioni tra l’utente e i suoi badge.
Non serve una chiamata aggiuntiva per rimuovere l’utente dai gruppi o cancellarne i permessi.
Link alla rispostaNo. Eliminando l’utente, i badge vengono scollegati e rimangono disponibili per essere riassegnati ad altri utenti.
La rimozione dell’associazione badge–utente è quindi distinta dalla cancellazione del badge stesso.
Link alla rispostaBadge, PIN e targhe
Il valore del PIN deve essere compreso tra 1000 e 999999. La lunghezza effettivamente utilizzabile dipende dal lettore installato e dalla sua configurazione: sono previste configurazioni a 4, 5 o 6 cifre.
Prima di generare i PIN, verificate quindi la configurazione dei lettori della struttura. Un PIN di 6 cifre è utilizzabile solo con lettori compatibili.
Link alla rispostaL’unicità del PIN è verificata all’interno della company, non sulla singola porta.
Se la creazione viene rifiutata perché il PIN è già in uso, generate un nuovo PIN compatibile con i lettori e riprovate. Verificate la causa nel payload dell’errore, senza basarvi esclusivamente sul numero del codice.
Link alla rispostaIl codice del badge o la targa possono essere comunicati in anticipo e associati all’utente tramite API. In alternativa, l’assegnazione può essere effettuata direttamente dal portale Passy.
Per un badge fisico è anche possibile leggere il codice in struttura e associarlo successivamente tramite API.
Link alla rispostaImpostando inheritAccess a true durante l’assegnazione di un nuovo badge a un utente, il nuovo badge eredita tutti i permessi già assegnati agli altri badge dello stesso utente.
Questa opzione consente di assegnare un nuovo badge anche dopo la configurazione degli accessi dell’utente.
Link alla rispostatypeBadge identifica il tipo di badge o credenziale. Per i casi descritti:
| Campo | Valore | Significato |
|---|---|---|
typeBadge |
0 |
Badge fisico |
typeBadge |
1 |
PIN |
typeBadge |
4 |
Targa |
Il campo keysTypeKeys del permesso identifica invece la categoria di chiave abilitata:
| Campo | Valore | Significato |
|---|---|---|
keysTypeKeys |
1 |
Smartphone |
keysTypeKeys |
2 |
Badge, PIN e targhe |
I valori dei due campi hanno significati diversi e non devono essere scambiati.
Link alla rispostaGruppi di utenti
Utilizzate la stessa API impiegata per assegnare i permessi a un utente, valorizzando il campo UserId con il nome del gruppo.
L’operazione può quindi essere gestita direttamente dall’integrazione.
Link alla rispostaSì. Sono disponibili API per la gestione delle relazioni tra gruppi e utenti, inclusa un’operazione di associazione massiva che aiuta a ridurre il numero di chiamate.
Consultate la sezione Gruppi della documentazione API per il contratto delle singole operazioni.
Link alla rispostaNo. La cancellazione dell’utente rimuove automaticamente tutte le sue appartenenze ai gruppi. Non è necessaria una seconda chiamata per questa pulizia.
Link alla rispostaPermessi e validità temporale
Sì. Impostando checkIn e checkOut e senza valorizzare recurrenceRule, il permesso è utilizzabile per l’intero intervallo indicato, comprese le ore notturne, senza una fascia oraria giornaliera aggiuntiva.
Ad esempio, un permesso valido dall’arrivo alle 14:00 fino alla partenza alle 10:00 resta utilizzabile anche nelle notti comprese tra le due date.
Link alla rispostaSe counterAssigned non viene valorizzato, il numero di accessi è illimitato.
La validità temporale stabilita da checkIn e checkOut continua comunque ad applicarsi.
Gli orari inviati in UTC vengono rispettati come istanti temporali, senza reinterpretarli come orari locali. La corrispondenza con l’ora del luogo tiene conto dell’ora legale e dell’ora solare.
Per un luogo in Italia con timezone W. Europe Standard Time:
| Istante inviato in UTC | Ora locale italiana |
|---|---|
2026-10-17T12:00:00Z |
17 ottobre 2026, ore 14:00 — ora legale |
2026-11-23T04:00:00Z |
23 novembre 2026, ore 05:00 — ora solare |
La Z finale indica che l’orario è espresso in UTC.
Per gli ospiti di una struttura alberghiera consigliamo typeAccesso 10 (Proximity).
Le modalità si distinguono così:
- Proximity: consente l’apertura in prossimità del varco. La prossimità è garantita da un Room Controller vicino al punto di accesso, da un tag NFC non clonabile oppure dall’utilizzo di un lettore di targhe, PIN o badge.
- RemoteProximity (
1000): si utilizza con tag NFC standard o beacon, per i quali la prossimità non è garantita allo stesso modo. - Remoto: consente all’utente di aprire da qualsiasi posizione.
La modalità deve essere coerente con i dispositivi installati nella struttura.
Link alla rispostaLuoghi, gerarchie e percorsi
Sì. L’ereditarietà dei permessi nella gerarchia dei luoghi opera dall’alto verso il basso.
Assegnando un permesso al luogo “Piano 2”, l’accesso viene esteso alle porte contenute in quel livello della gerarchia.
Link alla rispostaNon per la sola presenza della camera nella gerarchia. Il permesso su un luogo figlio non risale automaticamente ai luoghi padre.
Per abilitare anche i varchi necessari a raggiungere la camera, occorre configurare appositi gruppi di luoghi che associno la destinazione agli accessi comuni necessari.
Ad esempio, per la camera 201 si possono configurare il cancello, l’ingresso dell’ala destra e il varco del secondo piano. Dopo questa configurazione, assegnare il permesso alla camera 201 abilita anche i varchi associati.
Link alla rispostaNo. In base alla configurazione della struttura e agli accessi da abilitare, può essere necessario assegnare permessi anche a livelli superiori della gerarchia.
Un permesso assegnato a un livello superiore si estende automaticamente ai luoghi sottostanti. La scelta del livello deve quindi riflettere l’insieme di accessi che si intende autorizzare.
Link alla rispostaNo. I gruppi di utenti raccolgono persone alle quali assegnare permessi. I gruppi di luoghi consentono di configurare l’associazione tra una destinazione e i varchi necessari per raggiungerla.
Questi due concetti vanno inoltre distinti dalla gerarchia dei luoghi, nella quale i permessi vengono ereditati dall’alto verso il basso.
Link alla rispostaLimiti delle chiamate ed errori
Il limite predefinito è di 50 chiamate al minuto per ogni applicazione client. Se più hotel utilizzano la stessa applicazione client, condividono quindi il limite previsto per quell’applicazione.
Una richiesta oltre il limite viene rifiutata con HTTP 429. Il conteggio si azzera ogni minuto.
Sì. Il limite è personalizzabile e può essere concordato con Passy in base ai volumi dell’integrazione e alla configurazione delle credenziali.
Nel dimensionamento considerate sia le chiamate di creazione e cancellazione sia quelle necessarie per modificare date, camere e permessi. Dove disponibili, le operazioni massive aiutano a ridurre il numero di richieste.
Link alla rispostaIl codice di stato HTTP e il campo ErrorCode del payload sono informazioni distinte.
| Stato HTTP | Significato |
|---|---|
401 / 403 |
Errori di autenticazione o autorizzazione |
429 |
Superamento del limite delle chiamate |
481 |
Errori applicativi previsti, descritti nel payload CustomExceptionModel |
500 |
Errori imprevisti di infrastruttura, database o timeout non riconducibili alla logica applicativa |
Per gli errori applicativi, esaminate ErrorCode, Category e gli altri dettagli del payload. Il numero 480, ad esempio, può comparire come valore di ErrorCode: non va confuso con lo stato HTTP della risposta.
Le combinazioni previste per ogni operazione sono descritte nella documentazione e nell’estensione OpenAPI x-error-cases.