WELOCK OpenAPI

1. Connessione e dispositivi

Verifica le credenziali e carica gli elenchi WELOCK. L'elenco dispositivi compila automaticamente i campi usati nei comandi.

Cliente / soggetto (IdSoggetto) necessario Serve al server per recuperare AppID e Secret dal database. AppID, Secret e token non vengono inseriti manualmente.

Opzioni elenco - normalmente lasciare i valori proposti

Pagina risultati Lasciare 1 salvo paginazione indicata da WELOCK. Risultati per pagina Numero massimo di record richiesti in una chiamata.

Dispositivi assegnati -

Elenco Device Library assegnato da WELOCK all'account.

Dispositivi abilitati API -

Dispositivi registrati nell'account API e utilizzabili dal progetto.

Gateway associati -

Gateway restituiti dall'API. Quando l'elenco non espone il numero, si usa il codice WiFi-Box mostrato nell'app WELOCK.

Seleziona un dispositivo caricato La scelta riporta automaticamente DeviceNumber e il Bluetooth principale nei campi sottostanti. Seleziona un gateway caricato Quando WELOCK restituisce i dati, compila numero e tipo gateway.

2. Abilita un dispositivo alle API

Da usare soltanto quando il dispositivo appare nella Device Library ma non nell'elenco dei dispositivi API.

Il dispositivo è già assegnato al cliente da WELOCK, ma deve essere registrato nell'account OpenAPI prima di poter essere comandato.

Numero dispositivo necessario JSON: Result.Data[n].deviceNumber. Alias del dispositivo Nome descrittivo scelto nella nostra applicazione. Riferimento utente Riferimento interno facoltativo per DeviceCreate.

3. Associa un gateway all'account API

Registra il gateway nell'account OpenAPI del soggetto. L'associazione deve essere completata prima di usare apertura, batteria e comandi PIN tramite gateway.

L'endpoint /API/Gateway/Add associa il GatewayNumber all'account WELOCK autenticato. Non configura la rete Wi-Fi del gateway: quella configurazione deve essere già stata eseguita tramite app WELOCK o con la funzione Bluetooth dedicata.

Campo Obbligatorio Istruzioni

GatewayType sì 3 per Bluetooth Gateway WELOCK; 4 per FeiBit Gateway.

GatewayNumber sì Codice del gateway, normalmente visibile nell'app WELOCK sotto l'icona WiFi-Box.

GatewayPassword dipende dal tipo Lasciare vuoto per il tipo 3. Per il tipo 4 è necessario alla prima associazione del gateway.

AppID e token automatici Il backend li recupera da IdSoggetto e gestisce automaticamente il Bearer token.

Tipo gateway necessario Usare 3 per il normale WiFi-Box Bluetooth WELOCK. Numero gateway necessario Inserire il codice esatto mostrato nell'app o stampato sul gateway. Password gateway solo tipo 4 Per il tipo 3 lasciare vuoto. Per il tipo 4 inserirla alla prima associazione.

1. Verifica l'accesso Prima eseguire “Verifica accesso WELOCK” nella sezione 1.

2. Associa il gateway Inserire tipo e numero, quindi inviare la richiesta. Il codice WELOCK atteso è 0.

3. Controlla l'elenco Dopo il successo premere “Mostra gateway associati” per verificare che il gateway sia presente.

Per un FeiBit Gateway di tipo 4, la chiamata può avviare la modalità di aggiunta dispositivo: dopo la risposta occorre operare fisicamente la serratura/dispositivo affinché entri nel gateway. Per il Bluetooth Gateway di tipo 3 questa operazione non è richiesta.

4. Comandi remoti tramite gateway

Il gateway collega Internet alla serratura Bluetooth. Per apertura e batteria servono tutti e quattro i dati operativi indicati qui sotto.

Campo Serve per aprire? Come si reperisce

GatewayType sì Dall'elenco gateway. Per il Bluetooth Gateway WELOCK usato qui è 3.

GatewayNumber sì Da Gateway/list, oppure dal codice WiFi-Box mostrato nell'app, ad esempio WLE02715.

DeviceNumber sì DeviceLibrary → data[n].deviceNumber, ad esempio 24049561.

DeviceName sì data[n].bluetooth: scegliere l'elemento con spare = false, ad esempio WeLock319BN.

InstructionID no, è restituito Non si invia per iniziare l'apertura. WELOCK lo restituisce e serve dopo per controllare l'esito.

AppID e token automatici Il backend li recupera dal soggetto e gestisce il Bearer token senza mostrarli nella pagina.

Esempio pratico: come leggere DeviceNumber e DeviceName dal JSON

{
  "deviceNumber": "24049561",
  "bluetooth": [
    { "spare": true,  "deviceName": "WeLockC8VJ8" },
    { "spare": false, "deviceName": "WeLock319BN" }
  ]
}

Numero dispositivo: 24049561

Nome Bluetooth principale: WeLock319BN

Il valore WeLockC8VJ8 non va usato perché appartiene all'elemento con spare = true.

Nota: GatewayNumber non è contenuto nella Device Library; proviene dall'elenco gateway o dall'app WELOCK.

Tipo gateway necessario Per il WiFi-Box mostrato nell'app usare normalmente 3. Numero gateway necessario GatewayNumber o codice visualizzato sotto l'icona WiFi-Box nell'app. Numero dispositivo necessario JSON: Result.Data[n].deviceNumber. Nome Bluetooth principale necessario JSON: elemento Bluetooth con spare = false. ID istruzione automatico Compilato dopo apertura, batteria o comando PIN via gateway.

Controlla gateway Richiede soltanto il numero gateway e ne verifica lo stato.

Leggi batteria Richiede tipo gateway, numero gateway, DeviceNumber e DeviceName.

Apri e controlla esito Invia l'apertura e salva automaticamente l'InstructionID restituito.

5. Gestione PIN della serratura

Due famiglie distinte: PIN personalizzato scritto nella serratura tramite gateway e PIN temporaneo generato dal server WELOCK.

I dati di gateway e serratura non vengono duplicati: le funzioni PIN personalizzato usano i campi della sezione 4. Nei futuri endpoint cliente questi valori saranno recuperati dal database a partire da IdSoggetto e IdDispositivo.

A

PIN personalizzato via gateway

gateway necessario

PIN numerico di 6 cifre, con periodo di validità, numero massimo di utilizzi e indice da 1 a 256. Il comando viene inviato alla serratura attraverso il gateway.

WELOCK richiede esattamente: startTimestamp, endTimestamp, times, password e index. Le date inserite qui vengono convertite automaticamente in timestamp Unix di 10 cifre. Un eventuale riferimento utente appartiene al nostro database e non viene inviato a questo endpoint.

Tipo prova La selezione monouso imposta automaticamente il numero utilizzi a 1. PIN personalizzato necessario Numero di 6 cifre; viene inviato a WELOCK ma oscurato nei log tecnici. Indice / slot PIN necessario Password ID previsto da WELOCK: valore da 1 a 256. Va conservato per modificare o eliminare il PIN. Valido dal necessario Valido fino al necessario Numero massimo utilizzi necessario Parametro WELOCK times: da 1 a 65535. Impostare 1 per un PIN monouso.

B

PIN temporaneo generato da WELOCK

gateway non necessario

WELOCK genera il codice temporaneo. Non serve il gateway, ma sono necessari sia DeviceNumber sia il nome Bluetooth principale (deviceBleName). Dopo la generazione questo tipo di PIN non può essere eliminato anticipatamente.

Modalità temporanea DeviceNumber usato È lo stesso numero dispositivo della sezione 3 e viene aggiornato automaticamente. Nome Bluetooth usato È il Bluetooth con spare = false della sezione 3. Periodo dal necessario WELOCK accetta solo minuti 00, 15, 30 o 45 e anni non superiori al 2039. Periodo fino al necessario Anche la scadenza deve cadere su un quarto d'ora: 00, 15, 30 o 45.

Ultimo PIN temporaneo restituito Non ancora generato

Il PIN temporaneo non viene salvato nel file di log della risposta. Resta visibile nella pagina per poterlo copiare. La cancellazione singola non è prevista: il codice termina alla scadenza impostata.

Risposta tecnica

Nessuna richiesta eseguita.

Pronto.