API e integrazioni con software terzi

Lo schema tecnico è semplice e robusto, puoi collegare i tuoi software allo strato di API della tua installazione e governarla in autonomia.

La struttura API permette di effettuare le operazioni simulando quasi la totalità delle funzioni del pannello di manage che diamo a corredo del KIT. Tutte le chiamate devono essere attivate e provenire da un IP autorizzato.

Di seguito trovi la guida completa a tutte le chiamate disponibili, organizzate per area funzionale. La stessa documentazione è consultabile anche in formato interattivo su Postman: clicca qui!.

NB: è disponibile anche una versione corazzata del servizio di API (API PRO) che permette di avere i log delle chiamate API e di effettuare la chiamata di apertura da remoto — vedi la sezione Api Pro o contattaci per saperne di più.

Per esempi pratici di integrazione con gestionali, PMS, piattaforme di prenotazione e di pagamento, consulta Integrazioni più comuni: come fare per.

Autenticazione

Tutte le chiamate (ad eccezione della verifica di stato) richiedono un token Bearer, ottenuto tramite la chiamata authorize e passato come header nelle richieste successive.

• Il token è valido 1 ora: va rinnovato periodicamente ripetendo la chiamata authorize.
• Non ci sono limiti al numero di chiamate che si possono effettuare.
• Errori possibili sulla chiamata authorize: IP non autorizzato o secret_key errata (invalid_access), credenziali errate (invalid_credentials), errore generico (could not create token).
• Errori possibili sulle altre chiamate: token scaduto, non valido o assente (invalid_token). Eventuali errori specifici sono indicati nel campo messages della risposta JSON.

POST /api/v2/authorize — Ottieni il token

Restituisce il token Bearer da usare per tutte le chiamate successive.

• Parametri obbligatori: email (email dell’operatore), password (password dell’operatore), secret_key (associata all’IP autorizzato, si trova nel pannello nella sezione API / Setup)
• Risposta 200: token
• Risposta 401: invalid_credentials (email o password errate), invalid_credentials2 (IP non autorizzato o secret_key errata), invalid_access1 (secret_key mancante)

GET /api/v2/ — Test di stato

Verifica che il pannello sia attivo e funzionante (stampa Test). Non richiede autenticazione né parametri.

Utenti

PUT /api/v2/adduser — Crea nuovo utente

Crea un nuovo utente sul pannello.

• Parametri obbligatori: name (nome), surname (cognome)
• Parametri opzionali: email, phone, prefix (prefisso nazionale urlencoded, es. +39 → %2b39), tags (array; ogni virgola viene sostituita con un underscore), status (1 = abilitato, 0 = disabilitato), fields (array di campi aggiuntivi personalizzati nel formato fields[id_campo]=valore)

PUT /api/v2/updateuser — Modifica utente

Aggiorna i dati di un utente esistente.

• Parametri obbligatori: user_id, name, surname
• Parametri opzionali: email, phone, prefix, tags, status (1 = abilitato, 0 = disabilitato), fields (array di campi aggiuntivi, stesso formato di AddUser)

DELETE /api/v2/deleteuser — Elimina utente

Elimina un utente dal pannello.

• Parametri obbligatori: user_id
• Risposta 200: utente eliminato con successo
• Risposta 400: utente non trovato

GET /api/v2/getusers — Elenco utenti

Restituisce i dati di tutti gli utenti presenti sul pannello, oppure di uno specifico se viene passato il parametro opzionale.

• Parametri opzionali: user_id, tags (filtra gli utenti per tag), getGrantInfo (se 1, include anche i dettagli degli accessi associati)
• Risposta 404: nessun utente trovato

GET /api/v2/users/getStatus — Stato utente

Restituisce se un utente è abilitato o disabilitato.

• Parametri: user_id

POST /api/v2/users/changeStatus — Cambia stato utente (non ancora disponibile)

Se status = 1 l’utente viene abilitato agli accessi, se status = 0 viene disabilitato.

• Parametri: user_id, status (1 = abilitato, 0 = disabilitato)

Gruppi

GET /api/v2/getGroup — Elenco gruppi

Restituisce i dati di tutti i gruppi presenti sul pannello, oppure di uno o più specifici se viene passato il parametro opzionale.

• Parametri opzionali: group_id (può essere un array)
• Risposta 404: nessun gruppo trovato

POST /api/v2/grantAccessGroup — Abilita accesso a un gruppo

Abilita l’accesso di uno o più utenti a uno o più gruppi indicati, creando l’associazione utente-gruppo.

• Parametri obbligatori: user_id (può essere un array), group_id (può essere un array)
• Risposta 200: associazioni create con successo
• Risposta 400: utente non trovato, gruppo non trovato, associazione già esistente

POST /api/v2/dropAccessGroup — Revoca accesso a un gruppo

Revoca i permessi di accesso di un utente appartenente a un gruppo, rimuovendo l’associazione utente-gruppo.

• Parametri obbligatori: user_id (può essere un array), group_id (può essere un array)
• Risposta 200: associazioni rimosse con successo
• Risposta 400: associazione non esistente, gruppo non trovato, utente non trovato

Crediti

GET /api/v2/getcredits — Saldo crediti

Restituisce il saldo crediti disponibile.

GET /api/v2/getprices — Listino prezzi

Restituisce il listino prezzi per la ricarica dei crediti.

POST /api/v2/recharge — Ricarica crediti

Effettua una ricarica di credito.

• Parametri: user_id, amount (es. 10.50)

Chiavi

GET /api/v2/getunusednfc — Chiavi NFC libere

Restituisce l’elenco delle chiavi NFC non associate a nessun utente. Nessun parametro richiesto.

• Risposta 404: nessuna chiave NFC libera trovata

GET /api/v2/getallnfc — Elenco chiavi NFC

Restituisce i dati relativi a tutte le chiavi NFC presenti sul pannello, associate o meno.

• Parametri opzionali (paginazione): limit, offset
• Risposta 400: nessuna chiave trovata, oppure offset usato senza limit

PUT /api/v2/addkey — Inserisci chiave NFC

Inserisce una nuova chiave NFC.

• Parametri obbligatori: nfc_key_code (codice RFID letto con un lettore standard: verrà convertito secondo lo standard LabKey — non usare un codice preso da un log accessi), nfc_key_name (nome da associare alla chiave)
• Parametri opzionali: force_hex (forza la conversione del codice da stringa esadecimale; se omesso, la conversione avviene automaticamente solo se il codice contiene almeno una lettera)

PUT /api/v2/addkey2user — Associa chiave NFC a utente

Associa una chiave NFC a uno specifico utente.

• Parametri obbligatori: user_id, nfc_key_id
• Risposta 400: chiave già assegnata
• Risposta 404: chiave non trovata, utente non trovato

DELETE /api/v2/deletekey — Elimina chiave NFC

Elimina una chiave NFC.

• Parametri obbligatori: nfc_key_code (codice RFID convertito secondo lo standard LabKey, es. 1234567890 → 210215073)
• Risposta 404: chiave non esistente
• Risposta 400: nfc_key_code mancante

GET /api/v2/getnfcdetails — Dettagli chiave NFC

Restituisce i dettagli relativi a una chiave NFC.

• Parametri obbligatori: nfc_key_code (codice convertito secondo lo standard LabKey)
• Risposta 404: nessun utente collegato alla chiave, chiave NFC non trovata
• Risposta 400: parametri mancanti

POST /api/v2/editnfc — Modifica chiave NFC

Modifica i dettagli di una chiave NFC.

• Parametri obbligatori: nfc_key_code, name
• Risposta 404: nfc_key_code non trovato o mancante, name mancante

POST /api/v2/edittastierino — Modifica codice tastierino

Cambia il codice di un tastierino (pinpad).

• Parametri obbligatori: old_pinpad_key_code (vecchio codice da sostituire), new_pinpad_key_code (nuovo codice)
• Risposta 200: codice aggiornato correttamente
• Risposta 404: il vecchio codice non esiste
• Risposta 400: il codice deve essere numerico

POST /api/v2/updatepinpad — Aggiorna codice tastierino per utente

Aggiorna il codice tastierino selezionando l’utente.

• Parametri obbligatori: user_id, new_pinpad_key_code
• Risposta 404: utente non esistente
• Risposta 400: il codice deve essere numerico, chiave già esistente

POST /api/v2/getqrcode — Genera QR Code

Genera un QR Code per l’utente selezionato, utilizzabile a partire dalla “messagge string”.

• Parametri obbligatori: user_id
• Parametri opzionali: image (se 1, restituisce l’immagine del QR Code codificata in base64), with_background (richiede image=1; se 1, aggiunge uno sfondo decorativo all’immagine)
• Risposta 404: utente non trovato

POST /api/v2/getfasturl — Genera Fast URL

Genera la Fast URL per l’utente selezionato, utilizzabile a partire dal campo “fast_url”.

• Parametri obbligatori: user_id
• Risposta 404: utente non trovato

GET /api/v2/getallpinpad — Elenco codici tastierino

Restituisce tutti i codici tastierino e i relativi dettagli.

• Parametri opzionali (paginazione): limit, offset
• Risposta 400: impostare sia limit che offset oppure lasciarli entrambi vuoti; limit/offset devono essere interi

Accessi e permessi

POST /api/v2/getGrantInfo — Dettagli di un accesso

Restituisce i dati relativi all’accesso specificato.

• Parametri obbligatori: involved_associations (uno o più ID restituiti dalla chiamata grantaccess)
• Risposta 200: informazioni sull’utente e, per ogni LabKey associata, i dettagli dell’accesso
• Risposta 400: occorre inviare almeno un involved_associations valido
• Risposta 404: riga con quell’involved_associations non trovata

POST /api/v2/automategetGrantInfo — Dettagli accesso semplificato

Chiamata di comodo per semplificare l’uso di getGrantInfo.

• Parametri opzionali: user_id (può essere un array), unique_name (può essere un array — nome della LabKey selezionata)

GET /api/v2/getuservarcodetails — Dettagli varchi utente

Restituisce tutti i dettagli sui varchi associati all’utente selezionato.

• Parametri obbligatori: user_id

POST /api/v2/grantaccess — Abilita accesso

Abilita l’accesso di un utente. Per configurare una combo di più tecnologie (NFC, tastierino, barcode) è possibile richiamare questa API più volte cambiando la key_id.

• Parametri obbligatori: user_id, key_id (ID della chiave d’accesso associata all’utente: usare nfc_key_id per NFC/Pocket, pinpad_key_id per tastierino/barcode), data (stringa JSON con i parametri di ogni varco: intervallo date datei/datef, orari houri/hourf, giorni della settimana mo,tu,we,th,fr,sa,su, giorni festivi tv, command_device_id, id_rele, technology)
• Parametri opzionali: check_overalapping, force_same_idrele_commanddeviceid

POST /api/v2/editaccess — Modifica accesso

Chiamata di comodo che esegue in sequenza dropaccess e grantaccess, restituendo un nuovo involved_associations per l’utente. Non è un’operazione atomica: se dropaccess termina correttamente ma grantaccess fallisce, le associazioni risultano comunque eliminate.

• Parametri obbligatori: involved_associations (può essere un array), user_id, key_id, data (stringa JSON, stesso formato di GrantAccess)

DELETE /api/v2/dropaccess — Revoca accesso

Revoca i permessi di accesso.

• Parametri obbligatori: involved_associations (codice ottenuto dalla risposta di grantaccess)

POST /api/v2/isAccessible — Verifica accessibilità varco

Verifica se un varco è accessibile in un determinato intervallo di tempo.

• Parametri obbligatori: unique_name, from_date (timestamp), to_date (timestamp), id_rele

Gestione contatori (antipassback)

GET /api/v2/antipassback/ — Dettagli contatore

Restituisce i dettagli sulla gestione contatori per l’utente e il varco indicati. La risposta è un array con il dettaglio per ogni relè.

• Parametri: user_id, unique_name
• Campi della risposta: is_active (1/0, contatore attivo o meno), has_total/number_total (limite totale accessi), has_day/number_day (limite giornaliero), has_week/number_week (limite settimanale), has_month/number_month (limite mensile)

POST /api/v2/antipassback/update_or_create — Imposta contatore

Crea o aggiorna la configurazione del contatore per uno o più relè.

• Parametri: user_id, data (stringa JSON con, per ogni LabKey e relè, i campi is_active, has_total/number_total, has_day/number_day, has_week/number_week, has_month/number_month)
• Nota: se is_active è impostato, si può attivare solo uno tra has_total, has_day, has_week o has_month — non è possibile attivarli contemporaneamente.

Generale

GET /api/v2/getlabkeys — Elenco LabKey

Restituisce i dettagli delle centraline/LabKey.

• Parametri opzionali: unique_name, labkey_id, key_tipe
• Risposta 400: nessuna LabKey trovata

GET /api/v2/getbuildings — Elenco strutture

Restituisce le informazioni sulle strutture associate al pannello.

• Parametri opzionali: structure_id, structure_name, referent

GET /api/v2/getlogs — Log accessi

Restituisce i log degli accessi.

• Parametri opzionali: from (data inizio), to (data fine), unique_name (nome della LabKey), labkey_id, user_id, limit (paginazione), offset (paginazione)

POST /api/v2/sendemail — Invia email

Invia una email a un cliente, ad esempio con i dettagli di accesso.

• Parametri obbligatori: user_id (destinatario), operator_email (mittente)
• Parametri opzionali: message (messaggio personalizzato; se omesso viene inviato un messaggio predefinito), cc_emails (array di indirizzi in copia), show_sender_name, send_permissions_list, send_fast_url, send_qr_code

WebHooks

Alerts — Notifiche in tempo reale

Permette di ricevere notifiche automatiche verso un proprio endpoint ogni volta che si verifica un evento (es. un accesso). Il webhook si configura dal pannello di Manage, nella sezione Alert → Alert Standard.

• Parametri inviati in query string al proprio endpoint: user_id, full_name, id_log, key_code, result_boolean (accesso consentito o meno), timestamp, is_log_offline, unique_name, labkey_id, tags, event_type

Campi aggiuntivi

Gestione dei campi personalizzati che si possono associare all’anagrafica utente (vedi anche Inserimento nuovo utente).

GET /api/v2/customfields — Elenco campi

Restituisce l’elenco dei campi aggiuntivi con i relativi attributi.

• Parametri opzionali (paginazione): limit, offset

GET /api/v2/customfields/{id_field} — Dettaglio campo

Restituisce i dettagli di uno specifico campo aggiuntivo.

GET /api/v2/customfields/count — Conteggio campi

Restituisce il numero di campi aggiuntivi salvati.

POST /api/v2/customfields/create — Crea campo

Crea un nuovo campo aggiuntivo.

• Parametri obbligatori: type_field (text o date), name_field (max 255 caratteri)
• Parametri opzionali: order (numerico), is_required (1 = obbligatorio in fase di compilazione utente), can_disable_user (1 = sì; utilizzabile solo con type_field=date — il sistema disabilita automaticamente l’utente a mezzanotte se la data inserita è passata)

POST /api/v2/customfields/{id_field}/update — Modifica campo

Aggiorna un campo aggiuntivo esistente. Stessi parametri di create.

Campi aggiuntivi utente

GET /api/v2/customfieldsuser/{id_user}/ — Elenco campi per utente

Restituisce tutti i campi aggiuntivi valorizzati per un utente.

• Parametri opzionali (paginazione): limit, offset

GET /api/v2/customfieldsuser/{id_user}/{id_field} — Valore campo per utente

Restituisce il valore di uno specifico campo aggiuntivo per l’utente indicato.

POST /api/v2/customfieldsuser/{id_user}/{id_field}/create — Imposta valore campo

Crea il valore di un campo aggiuntivo per l’utente.

• Parametri obbligatori: value (max 255 caratteri)
• Parametri opzionali: can_disable_user (0 = no, 1 = sì)

POST /api/v2/customfieldsuser/{id_user}/{id_field}/update — Aggiorna valore campo

Aggiorna il valore di un campo aggiuntivo per l’utente. Stessi parametri di create.

Template

Gestione dei modelli predefiniti per gli accessi ricorrenti (vedi anche Template).

GET /api/v2/templates/count — Conteggio template

Restituisce il numero di template salvati.

GET /api/v2/templates/ — Elenco template

Restituisce l’elenco dei template.

• Parametri opzionali (paginazione): limit, offset

GET /api/v2/templates/detail — Dettaglio template

Restituisce il dettaglio di un template specifico.

• Parametri: template_id

POST /api/v2/templates/addAccessUser — Applica template a utente

Applica un template di accesso a un utente. Si può usare in due modi: indicando sia timestamp_start che timestamp_end (il sistema imposta inizio e fine accesso su questi valori), oppure indicando solo timestamp_start e lasciando che il sistema calcoli automaticamente la fine in base alle impostazioni del template.

• Parametri obbligatori: user_id, template_id
• Parametri opzionali: timestamp_start (default: adesso), timestamp_end

Festività

Gestione delle festività (vedi anche Festività): durante gli intervalli configurati, i varchi selezionati aprono solo agli utenti ammessi.

GET /api/v2/festivita — Elenco festività

Restituisce tutte le festività, oppure una specifica se viene passato l’ID.

• Parametri opzionali: id
• Risposta 404: festività non trovata

GET /api/v2/festivita/count — Conteggio festività

Restituisce il numero di festività configurate.

• Parametri opzionali: id
• Risposta 400: parametri non validi o mancanti

GET /api/v2/festivita/is_holiday — Verifica festività

Verifica se una data/ora specifica ricade in un periodo festivo.

• Parametri obbligatori: datetime (formato YYYY-MM-DD HH:MM:SS)
• Parametri opzionali: unique_name, labkey_id, rele (array), user_id
• Risposta 200: is_holiday (booleano)
• Risposta 400: parametri non validi o mancanti

POST /api/v2/festivita/create — Crea festività

Crea una nuova festività.

• Parametri obbligatori: title, start_datetime (formato YYYY-MM-DD HH:MM:SS), end_datetime (formato YYYY-MM-DD HH:MM:SS)
• Parametri opzionali: description, recurring (1 = ricorrente ogni anno), notification_email, monday…sunday (1 = attiva in quel giorno), varcos (array JSON di labkey_id/rele coinvolti), user_ids (array di utenti coinvolti)

POST /api/v2/festivita/update — Modifica festività

Aggiorna una festività esistente. Stessi parametri opzionali di create.

• Parametri obbligatori: id
• Parametri opzionali: title, start_datetime, end_datetime, recurring, active (1 = abilitata, 0 = disabilitata), notification_email, monday…sunday, varcos, user_ids

DELETE /api/v2/festivita/delete — Elimina festività

Elimina una festività.

• Parametri obbligatori: id
• Risposta 200: festività eliminata con successo
• Risposta 400: parametri non validi o mancanti
• Risposta 404: festività non trovata