Elementi personalizzati: API

Un'interfaccia API è un modulo i cui valori compilati Skava invia come JSON a un indirizzo da te specificato (il tuo backend). In questo modo puoi collegare Skava in modo sicuro ai tuoi sistemi.

Configura un'interfaccia API

Un'interfaccia è composta da campi di input (che formano il JSON), l'indirizzo di destinazione e l'autenticazione.

1. Crea campi: Ogni campo riceve una chiave JSON. A destra è visibile in tempo reale l'anteprima JSON, che viene inviata al tuo backend esattamente in questo modo.
2. Indirizzo (URL): l'indirizzo https:// del tuo backend. Sono consentiti solo indirizzi HTTPS e accessibili pubblicamente (vedi Sicurezza di seguito).
3. Metodo: POST (predefinito), PUT, PATCH o GET. Con GET i valori vengono aggiunti come parametri di query invece di essere inviati nel corpo della richiesta.
4. Autenticazione: Imposta il nome dell'header (es. Authorization) e il prefisso del valore (es. Bearer ), quindi salva il token. Facoltativamente, imposta una data di scadenza.
5. Campi di risposta (facoltativo): Definisci tramite percorso quali valori dalla risposta del backend devono essere visualizzati: es. order.id o items[0].sku.
6. Verifica con Ping e Test Request, poi Release.

Conserva il token in modo sicuro

Il token è memorizzato cifrato e non viene mai restituito ai clienti: l'app mostra solo se è presente un token e quando scade. All'invio, Skava lo aggiunge lato server nell'header configurato. Se imposti una data di scadenza, Skava rifiuta la chiamata dopo la scadenza e ti chiede di rinnovare il token.

Test: Ping e Richiesta di test

• Ping : un controllo di raggiungibilità leggero. Verifica solo se il tuo indirizzo risponde, senza inviare token o dati del modulo nel processo. Mostra raggiungibilità, stato e tempo di risposta. Ideale come primo passo.
• Richiesta di test : la vera prova generale: invia dati di esempio inclusi token al tuo indirizzo e ti mostra la risposta completa oltre ai campi di risposta estratti.

Come amministratore, puoi eseguire entrambi mentre sei ancora in modalità bozza per verificare l'integrazione prima del rilascio.

Bozza e rilascio

Ogni interfaccia inizia come bozza e può essere modificata liberamente. Quando tutto è pronto, la pubblichi con Rilascia.

Sicurezza

Come il team utilizza un'interfaccia pubblicata

Una volta pubblicata un'interfaccia, tutti i membri dell'azienda possono attivarla direttamente da una chat, senza bisogno di un editor. Non esiste un punto di accesso collettivo né una finestra di dialogo intermedia: ogni elemento pubblicato compare nel menu più con il proprio nome, accompagnato dal logo dell'azienda che lo offre.

1. Nella chat, tocca Plus in basso e seleziona l'elemento desiderato, ad esempio Material order.
2. Compila il modulo e tocca Send.
3. Il risultato appare come una scheda nella chat, visibile a tutti i partecipanti.

Fai costruire un elemento all'AI

Come amministratore aziendale non devi usare tu stesso l'editor. Dì all'assistente Skava nella chat, ad esempio "creami un modulo d'ordine per il mio catalogo con quantità e indirizzo di consegna". Da questo crea una bozza, può modificare i campi uno alla volta in seguito e conosce il catalogo articoli che hai caricato: per gli ordini suggerisce il selettore prodotti anziché un campo di testo per il numero articolo.

Cosa può impostare anche: endpoint e metodo oltre al pubblico ("solo membri aziendali" o "anche esterni nella stessa chat"). Per il pubblico chiede prima invece di impostarlo direttamente, perché decide chi può eseguire qualcosa dall'esterno.

Cosa non tocca esplicitamente: il token di accesso. Non lo chiede mai e non lo accetta mai, perché i messaggi della chat vengono salvati. Lo inserisci tu stesso nell'editor, altrimenti nessuna chiamata viene inviata. E non può pubblicare: l'ultimo passo resta a te, così nulla diventa visibile ai clienti senza verifica.

Chi può eseguirlo

La scheda "Endpoint" indica chi può usare un elemento. Il valore predefinito sono i membri della tua azienda. La seconda impostazione lo apre agli esterni, ma solo in una chat in cui è presente anche qualcuno della tua azienda: esattamente il caso per cui è pensato, il cliente che ordina da te. Quando la tua azienda lascia la chat, il permesso termina da solo.

Prodotti dal tuo catalogo

Una volta caricato il catalogo articoli, il builder offre un blocco selettore prodotti. Non ci sono opzioni da mantenere: la lista è il tuo catalogo. Chi ordina lo cerca, vede immagine, nome e numero articolo, e il tuo backend riceve il numero articolo. Skava rifiuta un numero non presente nel tuo catalogo. Per la quantità, posiziona un normale campo numerico accanto.

Definisci la scheda tu stesso

Il tuo backend decide cosa dice la scheda. Skava controlla solo forma, dimensione e sicurezza, mai il significato: non conosce né gli stati dell'ordine né i nomi dei campi. Per farlo, rispondi con un oggetto card:

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

• v deve essere l'intero 1. Senza di esso la risposta non conta come scheda e si applica la mappatura della risposta configurata nell'elemento.
• state è solo colore e icona: ok, pending, warn o error. Tutto ciò che porta significato va in status_text come testo libero.
• fields è un elenco di etichette e valori, massimo 20 voci. I valori troppo lunghi vengono abbreviati invece di essere rifiutati, così un ordine non fallisce mai per un dettaglio.

Gli input dell'utente appartengono al server: restano intatti indipendentemente da ciò che invia il backend. Sono la traccia nella chat di ciò che è stato effettivamente inviato.

Segnalare lo stato in seguito

Quando l'elemento viene eseguito, Skava invia due valori aggiuntivi: callback_url e callback_token. Segnala lì un nuovo stato in seguito e una nuova scheda appare nella chat, anche sul telefono, mentre qualcuno la sta guardando. La precedente resta, così è leggibile quale stato è stato segnalato. Invia lo stesso oggetto card di cui sopra, tramite POST con l'intestazione Authorization: Bearer <callback_token>. Tre valori opzionali vanno accanto alla scheda:

• seq: il tuo contatore. Un report con un valore minore o uguale viene scartato, quindi due report non possono superarsi a vicenda.
• final: chiude l'interazione. Il token diventa non valido e la card è definitiva.
• notify: impostalo su false per pubblicare la card in silenzio, senza conteggio dei non letti e senza notifica. Per i passaggi intermedi che non devono svegliare nessuno. Senza di esso, la card è un messaggio perfettamente normale.

Un'interazione può pubblicare al massimo 50 card. Lo stesso report inviato due volte non produce una seconda card.

Skava risponde con 200 e un elenco di hints se qualcosa è stato accorciato o scartato, e con 422 se la card era inutilizzabile. Un'interazione accetta report per 90 giorni.

Le carte vengono pubblicate dal mittente di sistema di Skava, non dalla persona che ha eseguito l'elemento e non da un account della tua azienda. Il titolo della carta indica di quale sistema si tratta.

Un esempio completo da copiare si trova nel repository sotto example_order_server/ ed è disponibile su api.skava.io.

Correlati

Vuoi invece creare un modello di documento compilabile? Consulta Custom Elements: Documenti.

Domande frequenti