SCALEWEBLINK · v1.5 · REST / JSON
ScaleWebLink – manuale utente e REST API
Manuale HTML ScaleWebLink v1.5: configurazione del protocollo, POST JSON, MID e PIN, dati di peso, ERR01–ERR10, API test e simulatore.
Manuale in sloveno ↗← Tutti i manuali dei prodotti
1. Scopo e funzionamento
ScaleWebLink comunica con una bilancia tramite servizi web REST crittografati con SSL. La bilancia si collega al cloud tramite CloudScaleLink. Un sistema esterno invia un’azione e riceve una risposta JSON.
Ogni modulo CloudScaleLink ha un MID (Module ID) e un PIN (Module PIN) univoci. Insieme autorizzano l’accesso alla bilancia. Per CloudScaleLink virtuale, MID e PIN vengono forniti via email.
Servono un account Scale Monitor, una bilancia connessa con protocollo adatto o un simulatore e l’accesso al servizio. I comandi supportati e i campi disponibili dipendono da bilancia e protocollo.
2. Avvio rapido
- Registrati tramite il collegamento del tuo partner o register.scale-monitor.com e accedi a Scale Monitor.
- Aggiungi la bilancia e verifica il suo collegamento CloudScaleLink.
- Apri Menu → Protocol → ScaleWebLink.
- Scegli Protocol e Protocol version.
- Assegna a
Get_Weightun comando di lettura del peso adatto. - Apri API test, scegli l’azione e inviala.
- Verifica la risposta, quindi integra la richiesta POST nella tua applicazione.
3. Protocollo, azioni e comandi
In Menu → Protocol → ScaleWebLink scegli protocollo e versione per la bilancia collegata. Il manuale originale utilizza Mettler Toledo MT SICS come esempio.
La tabella delle impostazioni ha due colonne: Action è il nome dell’azione richiamata dalla tua applicazione; Command è il comando inviato alla bilancia.
Il nome dell’azione preimpostata Get_Weight non può essere modificato, ma si può scegliere il comando assegnato. Fai clic su Add per creare una riga, inserisci il nome dell’azione personalizzata e scegli il comando.
| Campo / codice | Significato e utilizzo |
|---|---|
Get_Weight → SIX1 | Esempio di richiesta del peso con MT SICS, versione MT SICS_1. |
Tare → T | Esempio di tara MT SICS: l’azione Tare invia il comando T. |
Gli esempi MT SICS non sono comandi universali per altre bilance. Verifica le funzioni disponibili nel protocollo del dispositivo collegato.
4. Richiesta POST e autorizzazione
Invia con POST un oggetto JSON con tre campi. I nomi dei campi sono minuscoli.
| Campo / codice | Significato e utilizzo |
|---|---|
mid | ID del modulo CloudScaleLink. |
pin | PIN del modulo CloudScaleLink. |
action | Get_Weight o il nome di un’azione personalizzata salvata. |
Per un modulo fisico, MID e PIN si trovano sull’etichetta. Per un modulo virtuale utilizza le credenziali fornite via email.
Indirizzo API: utilizza l’URL del servizio assegnato al tuo collegamento. Il PDF v1.5 non specifica un URL concreto dell’endpoint; contatta il supporto se non ne disponi. L’esempio seguente utilizza un segnaposto esplicitamente indicato, non un endpoint funzionante.
{
"mid": "yourMID",
"pin": "yourCSLPIN",
"action": "Get_Weight"
}cURL
# Sostituisci l’URL segnaposto e le credenziali del modulo.
curl --request POST 'https://YOUR-SCALEWEBLINK-ENDPOINT' --header 'Content-Type: application/json' --data '{"mid":"yourMID","pin":"yourCSLPIN","action":"Get_Weight"}'5. Risposta JSON
ScaleWebLink restituisce un oggetto JSON. L’esempio mantiene la risposta del manuale v1.5; disponibilità e contenuto dei dati seguono il protocollo della bilancia.
| Campo / codice | Significato e utilizzo |
|---|---|
error | 0 = nessun errore; 1 = si è verificato un errore. |
errorCode | Codice di errore; vedi il capitolo 7. |
errorMsg | Breve descrizione dell’errore. |
scaleResponse | Stringa grezza ricevuta dalla bilancia in risposta al comando. |
dateTime | Data e ora UTC in cui è stata eseguita l’azione. |
weightData | Oggetto contenente i dati di peso disponibili. |
Il manuale v1.5 mostra dateTime come data UTC testuale. Il sito originale mostra anche un timestamp numerico e pesi come stringhe. Verifica la risposta effettiva del servizio e del protocollo scelto e converti i tipi di conseguenza; non presumere un formato unico.
{
"error": 0,
"errorCode": null,
"errorMsg": "",
"scaleResponse": "SIX1 S 0 N R R 0 0 0 1 P 0.068 0.000 0.068 kg",
"dateTime": "Wed, 04 Sep 2024 11:07:51 GMT",
"weightData": {
"net": 0,
"gross": 0.068,
"tare": 0.068,
"unit": "kg",
"stability": 1,
"expectedResponseStatus": null,
"expectedResponseMsg": null
}
}6. Campi weightData
| Campo / codice | Significato e utilizzo |
|---|---|
net | Peso netto; null se non ricevuto. |
gross | Peso lordo; null se non ricevuto. |
tare | Valore della tara; null se non ricevuto. |
unit | Unità di peso; null se non ricevuta. |
stability | null = nessun dato; 0 = bilancia instabile; 1 = bilancia stabile. |
expectedResponseStatus | null = non configurato; 0 = risposta non OK; 1 = risposta OK. |
expectedResponseMsg | Messaggio configurato per il comando corrispondente nelle impostazioni del protocollo. |
null non è peso zero. Prima di utilizzare una misurazione verifica errori, campi richiesti, unità e stabilità. I valori di esempio non sono misurazioni di riferimento; verifica l’analisi dei dati con la bilancia reale.
7. Codici di errore e risoluzione dei problemi
Se un’azione non riesce, la risposta contiene un codice di errore. Verifica prima JSON e configurazione dell’azione, quindi connettività e risposta della bilancia.
| Campo / codice | Significato e utilizzo |
|---|---|
ERR01 | Mancano dati POST obbligatori o il JSON non è valido. Verifica corpo della richiesta e sintassi JSON. |
ERR02 | Manca l’ID del modulo (MID). Includi mid. |
ERR03 | Manca il PIN del modulo. Includi pin. |
ERR04 | Manca l’azione. Includi action. |
ERR05 | L’azione non è stata trovata tra quelle salvate. Verifica nome e configurazione. |
ERR06 | Non è stato trovato alcun Scale Monitor collegato al topic ricevuto. Verifica topic e collegamento. |
ERR07 | Non sono stati trovati i dati del comando. Scegli un comando valido per l’azione. |
ERR08 | Manca la stringa del comando. Verifica la proprietà command nel protocollo scelto. |
ERR09 | Il servizio è occupato: un altro client sta comunicando con la bilancia utilizzando gli stessi MID e PIN. Invia le richieste in sequenza e riprova più tardi. |
ERR10 | Timeout: non è stata ricevuta una risposta entro il tempo previsto. Verifica connettività e protocollo della bilancia. |
8. API test
- Apri Protocol → ScaleWebLink.
- Fai clic su API test in fondo alla pagina.
- Scegli un’azione salvata nella nuova finestra.
- Invia l’azione ed esamina la risposta visualizzata.
Esempio del manuale: Protocol: MT SICS, Version: MT SICS_1, Action: Get_Weight, comando assegnato SIX1. Se il test non riesce, utilizza la tabella degli errori e verifica il comando scelto.
9. Simulatore senza bilancia fisica
- Apri Scale simulation dal menu in alto a sinistra.
- Fai clic sull’icona più nella scheda Presets.
- Inserisci i dati desiderati per il simulatore.
- Imposta Connection type su Scale link e fai clic su Save.
- MID e PIN generati appaiono in alto dopo il salvataggio.
- Fai clic sul simulatore salvato in Presets per collegarlo al cloud.
- Utilizza MID e PIN del simulatore nelle richieste ScaleWebLink.
Il simulatore supporta sviluppo e test API. Prima di utilizzare l’integrazione nel tuo processo verifica bilancia reale, protocollo e azioni richieste.
10. Raccomandazioni per l’integrazione e supporto
- Mantieni MID e PIN sul lato server; non esporli nel codice web pubblico o nei registri.
- Invia in sequenza le richieste alla stessa bilancia. ERR09 indica che la comunicazione è occupata.
- Per ERR10 verifica connettività e risposta della bilancia. Non ripetere alla cieca le azioni che modificano lo stato: senza una risposta non puoi sapere se l’azione è stata eseguita.
- Tratta i campi non disponibili come dati mancanti, non come 0.
- Prima di memorizzare un risultato o continuare un processo verifica successo, unità e stabilità richiesta.
Per ulteriori informazioni e supporto tecnico: support@scale-monitor.com.
Questa documentazione si basa su ScaleWebLink v1.5. Gli esempi spiegano l’interfaccia e devono essere adattati alla tua configurazione.
Domande frequenti su ScaleWebLink
Che cos’è ScaleWebLink?
ScaleWebLink è un servizio web che comunica con una bilancia tramite CloudScaleLink utilizzando richieste REST e risposte JSON.
Posso utilizzare una bilancia esistente?
Sì, se può collegarsi tramite CloudScaleLink e il suo protocollo di comunicazione è configurabile. Prima dell’integrazione verifichiamo produttore, modello, connettore e comandi richiesti.
Posso eseguire la tara della bilancia dalla mia applicazione?
Sì, se bilancia e protocollo supportano la tara. Definisci un’azione e il relativo comando in Scale Monitor, quindi richiama l’azione tramite ScaleWebLink.
È necessaria una connessione Internet?
Sì. Il collegamento documentato utilizza un servizio cloud e una bilancia connessa o un simulatore.
Posso effettuare prove senza una bilancia fisica?
Sì. Il simulatore Scale Monitor genera MID e PIN per le prove. API test verifica le azioni e visualizza le risposte.
Tutti i campi di peso sono sempre disponibili?
No. net, gross, tare, unit e stability dipendono dalla risposta della bilancia e dal protocollo. null significa che i dati non sono stati ricevuti.
ScaleWebLink · v1.5 · PRECIZ / Scale Monitor
Avete bisogno di aiuto?
Vi serve aiuto con il software, la connettività o l’utilizzo di una soluzione? Descrivete il problema, così potremo aiutarvi a individuare il passo successivo.