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 connettere Skava in modo sicuro con i 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 ha una chiave JSON. A destra vedi in anteprima la visualizzazione 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 pubblicamente accessibili (vedi Sicurezza sotto).
3. Metodo: POST (predefinito), PUT, PATCH o GET. Con GET i valori vengono aggiunti come parametri di query invece di essere inviati nel corpo.
4. Autenticazione: Imposta il nome dell'intestazione (ad esempio Authorization) e il prefisso del valore (ad esempio Bearer ), quindi salva il token. Facoltativamente imposta una data di scadenza.
5. Campi di risposta (opzionali): Definisci tramite percorso quali valori dalla risposta del backend devono essere visualizzati: ad esempio order.id o items[0].sku.
6. Verifica con Ping e Richiesta di prova, poi Rilascia.

Memorizza il token in modo sicuro

Il token viene memorizzato crittografato e non viene mai restituito ai client: l'app mostra solo se un token è impostato e quando scade. Durante l'invio, l'app lo aggiunge lato server all'intestazione configurata. 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 prova

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

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

Bozza e Pubblicazione

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

Sicurezza

Come il team utilizza un'interfaccia rilasciata

Una volta che un'interfaccia è rilasciata, tutti i membri dell'azienda possono attivarla direttamente da una chat: non è necessario l'editor. Il flusso è lo stesso dei modelli di documento: seleziona, compila, invia.

1. Nella chat, tocca Più in basso e scegli Elemento personalizzato.
2. Scegli il modello o l'interfaccia desiderata dall'elenco.
3. Compila il modulo e Invia.
4. Il risultato appare come una card nella chat: visibile a tutti nella chat.

Lascia che l'IA crei un elemento

Come amministratore aziendale, non devi usare l'editor direttamente. Comunica all'assistente Skava nella chat, ad esempio "creami un modulo d'ordine per il mio catalogo con quantità e indirizzo di consegna". Esso crea una bozza, puoi modificare i campi uno alla volta in seguito, e conosce il tuo catalogo articoli caricato: per gli ordini suggerisce il selettore prodotti invece di un campo di testo per il numero di articolo.

Cosa potrebbe anche impostare: endpoint e metodo così come il pubblico ("solo membri dell'azienda" 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 sono archiviati. Lo inserisci tu nell'editor, altrimenti non vengono inviate chiamate. E non può pubblicare: l'ultimo passaggio resta a te, così nulla diventa visibile ai clienti senza verifica.

Chi può eseguirlo

La scheda "Endpoint" indica chi può usare un elemento. L'impostazione predefinita 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 è destinato, il cliente che ordina da te. Quando la tua azienda lascia la chat, l'autorizzazione termina automaticamente.

Prodotti dal tuo catalogo

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

Definisci la scheda da solo

Il tuo backend decide cosa dice la scheda. Skava controlla solo forma, dimensione e sicurezza, mai il significato: non conosce né stati dell'ordine né 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 una scheda e la mappatura della risposta configurata nell'elemento si applica.
• state è solo colore e icona: ok, pending, warn o error. Qualsiasi cosa abbia significato va in status_text come testo libero.
• fields è una lista di etichetta e valore, al massimo 20 voci. I valori troppo lunghi vengono abbreviati invece di essere rifiutati, quindi un ordine non fallisce per un dettaglio.

Gli input dell'utente appartengono al server: rimangono intatti, a prescindere da ciò che invia il tuo backend. Sono la registrazione nella chat di ciò che è stato effettivamente inviato.

Segnalazione dello stato in un secondo momento

Quando l'elemento viene eseguito, Skava invia due valori extra: callback_url e callback_token. Segnala un nuovo stato lì in seguito e appare una nuova card nella chat, anche sul telefono, mentre qualcuno sta guardando. Quella precedente rimane, quindi è leggibile quando è stato segnalato uno stato. Invia lo stesso oggetto card come sopra, tramite POST con l'intestazione Authorization: Bearer <callback_token>. Tre valori opzionali seguono la card:

• seq: il tuo contatore. Un report con un valore inferiore 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: impostato su false per pubblicare la card in silenzio, senza numero di messaggi non letti e senza notifica. Per passaggi intermedi che non devono disturbare nessuno. In sua assenza, la card è un messaggio perfettamente normale.

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

Skava risponde con 200 e una lista di hints se qualcosa è stato abbreviato o eliminato, e con 422 se la card non era utilizzabile. Un'interazione accetta report per 90 giorni.

Le schede vengono pubblicate dal sistema mittente di Skava, non dalla persona che ha eseguito l'elemento né da un account della tua azienda. Nel titolo della scheda è indicato il sistema che sta scrivendo.

Un esempio completo da copiare si trova nel repository in example_order_server/ ed è accessibile a api.skava.io.

Correlato

Preferisci invece creare un modello di documento compilabile? Consulta Elementi personalizzati: Documenti.

Domande frequenti