Integrare la tua API con OptiSigns ha molti utilizzi e consente di visualizzare facilmente dati auto-aggiornanti sui tuoi schermi. In questa guida, ti illustreremo come connettere la tua API - non è richiesta alcuna esperienza in ingegneria del software.
- Cosa può fare l'integrazione API
- Di cosa avrai bisogno per iniziare
-
Come configurare una richiesta API
- Come mappare i dati API in Designer
- Ulteriori informazioni sui casi d'uso di OptiSync
|
NOTA: L'integrazione API è disponibile solo con un piano Pro Plus o superiore. |
Cosa può fare l'integrazione API
OptiSigns consente una facile integrazione con le API degli utenti. Questo permette di mostrare i dati dalla API di un utente su qualsiasi dei tuoi schermi digitali. Ciò consente aggiornamenti dinamici per:
- Menu digitali - Integra con i tuoi sistemi POS e ottieni il menu digitale aggiornato automaticamente, e modifica il formato del tuo menu digitale usando l'app designer quando necessario.
- Aggiornamenti HR automatizzati - Usa l'API dai tuoi sistemi HR per visualizzare automaticamente compleanni o anniversari di lavoro sugli schermi.
- Tracciamento dell'inventario di magazzino - Usa l'API del tuo magazzino per visualizzare i livelli di inventario con aggiornamenti automatici in tutta la tua organizzazione
- Qualsiasi altro caso d'uso di visualizzazione delle informazioni che richieda di consumare dati API e visualizzare i dati sugli schermi.
Questa integrazione API può essere realizzata in OptiSigns con poca o nessuna programmazione, rendendola accessibile a chi non ha esperienza in ingegneria del software. In questa guida, ti illustreremo come configurarla con l'esempio seguente utilizzando un'API dal sistema POS Clover.
Di cosa avrai bisogno per iniziare
Avrai bisogno di:
- URL dell'endpoint API
- Token di autorizzazione API
Questi sono necessari affinché OptiSigns si connetta con l'API desiderata. Assicurati di averli in un luogo facilmente accessibile prima di provare a configurare la tua richiesta API nel portale web di OptiSigns. Dovresti essere in grado di ottenerli da un professionista IT nella tua organizzazione, o tramite l'amministratore del tuo sistema POS.
Come configurare una richiesta API
Il gateway API è uno strumento potente che consente agli utenti di gestire centralmente le API, oltre a configurare e testare le API.
Ora che hai tutto ciò di cui hai bisogno, iniziamo a configurare una richiesta API. Con una richiesta API, puoi:
- Utilizzare il Keystore API di OptiSigns per archiviare e utilizzare in modo sicuro le chiavi API da altri sistemi.
- Testare gli endpoint API, con la possibilità di modificare header e parametri.
- Utilizzare parametri di sostituzione e regole di pre-elaborazione e post-elaborazione per gestire integrazioni complesse. Le regole di pre-elaborazione possono aiutarti a gestire quelle situazioni di integrazione API che richiedono una chiamata aggiuntiva per ottenere un token di autenticazione prima di effettuare la chiamata API. La post-elaborazione ti permetterà di elaborare i dati restituiti e adattarli meglio al tuo utilizzo.
Per iniziare, apri il tuo portale web OptiSigns.
Una volta lì, naviga nell'angolo in alto a destra dello schermo e passa il mouse sul nome del tuo account.
Passa il mouse su Altro → DataSource
Vedrai la schermata seguente.
Ora sei pronto per iniziare.
Passaggio 1: Memorizza il tuo token di autorizzazione API nel Keystore API di OptiSigns
Il primo passaggio è prendere il tuo token di autorizzazione API e memorizzarlo nel Keystore API di OptiSigns.
Questo passaggio è tecnicamente opzionale: puoi inserire il tuo token di autorizzazione API in una richiesta API individuale. Tuttavia, il Keystore ha alcuni vantaggi principali:
- Consente di inviare il tuo token di autorizzazione API a più richieste API, senza la necessità di inserirlo manualmente ogni volta
- Fornisce una sicurezza superiore per il tuo token di autorizzazione API, rendendo molto più difficile per attori esterni scoprirlo
Pertanto, consigliamo vivamente questo passaggio.
Per accedere al Keystore, trova l'icona del lucchetto e clicca su di essa.
Questo aprirà il Keystore API.
Clicca su Aggiungi chiave.
Ci sono due campi qui.
- Primo campo - Inserisci il nome della chiave qui. Consigliamo qualcosa che ti aiuti a ricordarla. La userai per configurare una richiesta API.
- Secondo campo - Il codice univoco effettivo per le tue comunicazioni API.
Una volta inserito il tuo token di autorizzazione API, premi Salva. Quando vorrai eseguire una richiesta utilizzando questa chiave API, userai il termine: {{apiKeystore.<<key>>}} dove "<<key>>" viene sostituito dal nome che hai inserito prima. In questo esempio, chiameremo la nostra richiesta "clover".
Ora siamo pronti per configurare la tua richiesta API.
Passaggio 2: Configura e testa la richiesta API
Prima di procedere in OptiSigns, consigliamo di testare la tua API utilizzando uno strumento gratuito, come Postman. Questo offre diversi vantaggi, tra cui:
- Controllare la formattazione dei dati
- Assicurarsi che vengano forniti i dati corretti
- Verificare l'autenticazione
- Identificare problemi di integrazione o errori di connessione
I parametri di test, gli endpoint e gli autenticatori possono quindi essere utilizzati in OptiSigns per configurare la tua richiesta API. Ecco come farlo.
Clicca sul pulsante Aggiungi richiesta, si aprirà la finestra per configurare e testare la richiesta API.
- Nome visualizzato - Questo verrà mostrato nell'elenco del gateway API, principalmente per aiutare gli utenti a identificare la richiesta API.
- Nome - Questo viene utilizzato come riferimento alla richiesta API, è un nome tecnico che verrà utilizzato successivamente nel percorso per fare riferimento ai dati della richiesta API.
- URL - Questo è l'endpoint API, puoi utilizzare il metodo GET o POST a seconda della richiesta API, ad esempio, se stai utilizzando GraphQL, tutte le richieste utilizzeranno POST.
- Parametri - Ti consente di definire i parametri nella tua richiesta API. Potresti vedere parametri nel tuo URL endpoint API, questi saranno preceduti da un segno "?". Questi possono essere utilizzati nel codice di richiesta pre e post elaborazione per automatizzare ulteriormente la tua richiesta API.
- Header - L'header (o gli header) della richiesta API. Qui vorrai inserire il tuo token di autenticazione API.
- Pre-richiesta - Un pezzo di codice opzionale che prepara il contesto prima della richiesta API. Ad esempio, potresti dover chiamare un'altra API per ottenere un token di autenticazione a breve durata prima di chiamare l'API, o devi calcolare alcune variabili da utilizzare nella richiesta API.
- Post-richiesta - Un pezzo di codice opzionale che modifica i dati ricevuti dalla richiesta. Ad esempio, se i dati che ricevi non sono esattamente come vuoi che vengano visualizzati, puoi scrivere un po' di codice per modificarli secondo le tue esigenze di visualizzazione digitale.
- Abilita Webhook - Genera un link webhook e un token associato. Questo webhook può essere utilizzato per notificarci un cambiamento nei dati, che aggiornerà la richiesta API e aggiornerà automaticamente i tuoi schermi.
- Abilita questa richiesta - Imposta lo stato della richiesta API.
Per testare la richiesta, dovremo configurare l'header. Qui entra in gioco il Keystore. Nella seconda casella, digita Bearer {{apiKeystore.<<key>>}}, dove Bearer è il tipo di token e {{apiKeystore.<<key>>}} preleva il token memorizzato nel Keystore. In questo esempio, useremo il nome "clover" come indicato sopra.
Una volta fatto, clicca su "Esegui test". Se il codice di risposta è 200, l'API ha restituito i dati con successo. Se c'è qualsiasi altro codice, c'è un problema nella richiesta API.
Come utilizzare i parametri
I parametri sono presenti in URL di tutti i tipi. Ci sono due elementi in un parametro:
- Devono seguire un segno '?' nell'URL;
- Hanno un valore associato a loro
La scheda Parametri ti consente di specificare i parametri il cui valore vuoi modificare.
Di solito, la scheda Parametri viene utilizzata insieme alle schede Pre-richiesta e Post-richiesta per creare valori che si aggiornano automaticamente.
Come utilizzare l'elaborazione Pre- e Post-richiesta
Per utilizzare l'elaborazione pre- e post-richiesta, è necessaria una certa conoscenza di Javascript.
| Qual è la differenza tra i due? |
| Pre-richiesta: Questo è uno snippet di codice normalmente impostato per il contesto prima della richiesta API. Questo può essere il recupero di un token di autenticazione da un'altra API, o la modifica dei parametri per consentire una maggiore automazione. |
| Post-richiesta: Un pezzo di codice da applicare ai dati ricevuti dalla richiesta API. Questo codice può essere utilizzato per modificare i dati ricevuti per cambiare il modo in cui vengono visualizzati sui tuoi schermi. |
La scheda Pre-richiesta è dove inserirai il codice per l'elaborazione pre-richiesta.
Esempio: Per i sistemi che richiedono un token di autenticazione generato dinamicamente come Toast, questo può essere utilizzato per chiamare un'altra API per recuperare il token di autenticazione e impostarlo nel contesto dell'API.
Per ulteriori informazioni su questo esempio, consulta questo articolo su come connettere la tua API Toast.
La scheda Post-richiesta è dove inserirai il codice per l'elaborazione post-richiesta.
Esempio: Stai ricevendo dati dall'API del tuo software point-of-sale (POS), ma alcuni pezzi di dati non vengono visualizzati come vorresti.
I prezzi potrebbero essere visualizzati come numeri interi (es. 1299) invece che come prezzo corretto (es. $12,99). Per questo, avremmo bisogno di un pezzo di codice per convertire il numero intero in un prezzo, e che quel codice sia estensibile a qualsiasi errore di visualizzazione simile (es. 1899 invece di $18,99).
Per questo esempio comune, questo pezzo di codice JavaScript dovrebbe risolvere il tuo problema. Possiamo anche configurare la possibilità di mappare la disponibilità del prodotto allo stesso tempo.
Questo risolverà i dati restituiti, permettendo loro di essere visualizzati correttamente:
Questo può essere utilizzato anche per far apparire i dati come "ESAURITO", per barrare un articolo se non è disponibile, o per visualizzare avvisi in un sistema di gestione dell'inventario. Per ulteriori informazioni su questo esempio, consulta il nostro articolo su Menu digitali.
Passaggio 3 (Opzionale): Utilizza i parametri di sostituzione dagli attributi del dispositivo.
Molti sistemi point-of-sale (POS) sono concessi in licenza per negozio/posizione. È possibile configurare una singola richiesta API con OptiSync e farla funzionare con posizioni diverse utilizzando parametri di sostituzione. Inserendo questi parametri permetti al tuo schermo di comunicare le informazioni di identificazione del negozio o della posizione. Ciò significa che una singola richiesta API può comunicare dati diversi a negozi o posizioni diverse, anziché dover effettuare richieste API individuali per schermo.
Per iniziare, trova lo schermo che desideri modificare.
Clicca su Avanzate → Altro → Attributi aggiuntivi del dispositivo.
Appariranno due campi, Chiave e Valore.
- Chiave - Un parametro che verrà utilizzato durante la chiamata API per sostituire il valore del tuo negozio. Questo sostituirà parte del tuo URL endpoint API.
- Valore - Rappresenta il codice univoco associato al negozio o alla posizione che desideri passare alla tua API.
In questo esempio, stiamo mantenendo il merchantID di Clover qui. Il valore inserito dovrà essere ottenuto da te poiché sarà univoco.
Ora, torna alla pagina di configurazione della richiesta API. Sostituisci il merchantID nell'endpoint API con il nome della chiave che hai definito in precedenza.
Quando la chiamata API viene attivata sul dispositivo, prenderà il valore dal dispositivo e lo sostituirà in runtime. Per ogni schermo, vorrai eseguire questi stessi passaggi, mantenendo lo stesso nome della chiave mentre cambi il valore. Questo ti permetterà di inviare dati diversi a schermi diversi.
Come mappare i dati API in Designer
Per inviare dati dalla tua API a uno schermo, dovrà essere registrato come DataSource. Ciò consente di aggiungere elementi di dati all'app Designer di OptiSigns, dove può essere formattato e incorporato in qualsiasi design visivo che desideri visualizzare.
L'app Designer e i modelli possono essere utilizzati per fare la formattazione, e la fonte dati API gestirà la mappatura dei dati. Qualsiasi casella di testo o elemento immagine può essere mappato in Designer. Quando mappi un elemento immagine, l'URL dell'immagine verrà sostituito in runtime.
Passaggio 1: Creare un DataSource API
Per iniziare, trova il tuo design o creane uno nuovo nella scheda File/Risorse.
Con il design aperto, clicca su "DataSource" nella colonna di sinistra. Quindi, clicca su "Aggiungi DataSource" per aggiungere una fonte dati API al design.
Scorri verso il basso fino a dove dice "Gateway API" e cliccaci sopra.
Dovresti vedere questa schermata:
Seleziona la richiesta API creata sopra. Vedrai una schermata come quella qui sotto:
Qui puoi scegliere quali dati specificamente vuoi aggiungere al design. Se vuoi tutte le opzioni, premi "Continua". Apparirà questa schermata.
Nome DataSource è come questo DataSource apparirà in Designer. Chiamalo come preferisci per identificarlo.
Sincronizzazione ti consente di scegliere quanto spesso sincronizzare con la tua API. Importa solo una volta ha senso per promozioni una tantum e simili. Se questo è per una risorsa a lungo termine, scegli Accesso diretto periodico o Sincronizzazione periodica in background a seconda se hai bisogno di utilizzare i dati da un dispositivo specifico per impostare il contesto.
Premi Fatto, e il DataSource è creato.
Dovrebbe apparire nella colonna di sinistra sotto "Utilizzato in questo design". Apparirà sicuramente nella sezione "Altri DataSource". Potrebbe essere necessario aggiornare la pagina per farlo apparire.
Ora passiamo al passaggio 2.
Passaggio 2: Mantenere la mappatura degli elementi
Una volta creato il DataSource API, sei pronto per mappare i dati.
In Designer, apri il tuo DataSource.
Cliccaci sopra e apparirà una schermata simile a questa:
Aprendo uno qualsiasi di questi mostrerà i dati estratti dalla tua API:
Cliccando su qualsiasi pezzo di questi dati e trascinandolo sullo schermo, i dati appariranno. Avrai l'opzione di usare i dati come Ripetitore o da soli.
In questo caso, vogliamo usarlo da solo. Per i menu, un Ripetitore ha più senso.
Per controllare il binding dei dati, puoi cliccare su qualsiasi elemento mappato, quindi cliccare su Impostazioni. Vedrai il Nome elemento risorsa lì.
Abbiamo il nome dell'articolo e il prezzo dall'API mappati al design. Quando pubblicato sullo schermo, il valore verrà automaticamente sostituito con il valore dall'API. Se vengono apportate modifiche nel sistema POS Clover, il cambiamento sarà riflesso automaticamente sullo schermo.
Ripeti questo passaggio per tutti gli elementi che vuoi mappare alla fonte dati API e salva il design. Il tuo design è pronto all'uso.
Altri casi d'uso di OptiSync
Se desideri maggiori dettagli sui casi d'uso dell'integrazione API, abbiamo diversi articoli aggiuntivi. Consulta:
- Sistemi Point-of-Sale per costruire menu digitali
- Visualizzare programmi eventi
- Integrare sistemi API Toast
- Feed RSS personalizzati
- Mappatura dati dinamica
È tutto!
Questo è come integrare i dati API e pubblicarli sul tuo schermo. Soprattutto, senza programmazione!
Se hai domande aggiuntive, dubbi o feedback su OptiSigns, non esitare a contattare il nostro team di supporto all'indirizzo support@optisigns.com