Versione: 1.05
Versione: 1.05
Questa pagina descrive come una società di integrazione (nel seguito Integration Company) usa l'API cloud di IpDoor per gestire i codici di accesso degli appartamenti. È il caso tipico dei gestionali per hotel, B&B e affitti brevi: quando nasce una prenotazione, il codice arriva ai dispositivi con le date e gli orari corretti.
Per la panoramica delle altre forme di integrazione vedi Integrazioni via API.
Prima di scrivere codice servono tre cose.
L'accesso all'API richiede due token in sequenza: prima un token per l'account dell'Integration Company, poi un secondo token limitato all'impianto su cui si vuole operare. Entrambi viaggiano nell'header Authorization.
L'API usa OAuth2 con token JWT. Il token si ottiene autenticandosi con le credenziali dell'account admin dell'Integration Company:
curl -X POST \
-H 'Accept: application/json' \
'https://<client_id>:<client_secret>@api.ipdoor.com/oauth/token' \
-d 'grant_type=password&username=<email_admin>&password=<pass_admin>'
La risposta contiene il token da usare nelle chiamate successive:
{
"access_token": "eyJhbG...",
"token_type": "bearer",
"refresh_token": "eyJhbG...",
"scope": "read write",
"type": "USER",
"user_id": "<id_admin>",
"username": "<email_admin>"
}
Il valore di access_token va passato in ogni chiamata nell'header Authorization, preceduto da Bearer:
curl -X GET \
-H 'Accept: application/json' \
-H 'Authorization: Bearer eyJhbG...' \
'https://api.ipdoor.com/api/v2/users/me'
Il token ha una validità di 24 ore: scaduto, va rifatto il login (oppure usato il
refresh_token).GET /api/v2/users/meè anche il modo più rapido per leggere l'id dell'utente admin, che serve in alcune chiamate.
Molte operazioni richiedono un token limitato a un impianto (scoped sul dominio). Si ottiene con:
curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer eyJhbG...' \
'https://api.ipdoor.com/api/v2/auth/<id_impianto>'
La risposta ha la stessa forma del login iniziale, con in più il campo domain_id. Anche questo token si usa nell'header Authorization.
Queste due chiamate servono a scoprire su cosa si può operare: quali impianti sono collegati all'account dell'integratore e quali appartamenti contiene ciascun impianto.
GET /api/v2/users/<id_admin>/domains
Restituisce l'elenco dei domini gestibili, ciascuno con id, name, label, status e connectionMode.
Serve prima il login nell'impianto, poi:
GET /api/v2/users/virtual?ownerId=<id_owner>&domainId=<id_impianto>
<id_owner> è l'utente proprietario degli appartamenti: a seconda di come è stato configurato l'impianto può essere lo stesso account admin dell'Integration Company, oppure un altro utente dell'impianto (in quel caso l'id va richiesto a chi ha creato l'impianto).
Ogni appartamento restituito ha type: "VIRTUAL" e il proprio id, che identifica l'appartamento nelle chiamate sui codici.
Prima di creare un codice conviene controllare lo stato dell'impianto:
GET /api/v2/domains/<id_impianto>
Nel campo status si legge ONLINE se tutti i dispositivi dell'impianto sono online, OFFLINE se almeno uno non lo è.
Con il token dell'impianto:
POST /api/v2/accesscredentials/users/<id_appartamento>
Payload per un PIN numerico:
{
"type": "PINCODE",
"startTime": 1593605974000,
"endTime": 1606825174000,
"name": "Mario Rossi"
}
Payload per un QR code:
{
"type": "QRCODE",
"startTime": 1593605974000,
"endTime": 1606825174000,
"name": "Mario Rossi"
}
startTime e endTime sono timestamp in millisecondi e definiscono la finestra di validità.
| Campo | Effetto |
|---|---|
generateForOfflineMode: true | genera un codice intelligente, utilizzabile dal dispositivo anche quando è offline (solo per i PIN numerici) |
payload: "<codice_pin>" | imposta un valore scelto invece di lasciarlo generare al sistema |
length: <lunghezza> | lunghezza del PIN generato automaticamente |
maxUsages: <numero> | numero massimo di utilizzi complessivi del codice |
name deve essere univoco per l'appartamento.La risposta conferma il codice creato, con il suo id, il credentialType e il value effettivo.
Opzionalmente si può generare un link associato al codice, che permette di aprire da pagina web invece di digitare il codice sul dispositivo. È utile quando la postazione non ha tastierino né lettore QR:
POST /api/v2/accesscredentials/users/<id_appartamento>/links/<id_codice>
La risposta contiene il campo link, che è l'indirizzo da condividere con l'ospite.
Elenco dei codici di un appartamento:
GET /api/v2/accesscredentials/users/<id_appartamento>
Cancellazione, distinta per tipo di codice:
DELETE /api/v2/accesscredentials/users/<id_appartamento>/PINCODE/<id_codice>
DELETE /api/v2/accesscredentials/users/<id_appartamento>/QRCODE/<id_codice>
Dopo l'aggiunta o la cancellazione di un codice i dispositivi interessati vengono notificati via internet dalla piattaforma. Se serve un aggiornamento immediato, l'integratore che si trova sulla stessa rete del dispositivo può notificarlo anche in locale:
curl -X POST 'http://<indirizzo_ip>:8001/credential-changed/<id_appartamento>'
È un passaggio opzionale: serve solo ad anticipare la sincronizzazione già prevista dalla piattaforma.
Gli eventi di accesso si interrogano con una singola chiamata, filtrando per codice o per appartamento:
POST /api/v2/events/query
Ricerca per codice:
{
"types": ["ACCESS"],
"startDate": 1594112151000,
"endDate": 1594976151000,
"credentialIds": ["<id_codice>"],
"page": 0,
"pageSize": 10,
"sortBy": "timestamp",
"sortDir": "asc"
}
Ricerca per appartamento: identica, sostituendo credentialIds con userIds: ["<id_appartamento>"]. I campi startDate e endDate sono opzionali.
La risposta è paginata secondo i parametri inviati. Ogni evento riporta il dispositivo, il timestamp e, nel payload, il codice usato con il suo tipo e nome, l'appartamento e le uscite attivate; in eventMedia compaiono le eventuali immagini catturate al momento dell'accesso.
api.ipdoor.com, con esportazione JSON dello schema.Questa voce raccoglie più sotto-sezioni: scegline una per approfondire.