Skava Skava / Wiki

Questa pagina è destinata agli sviluppatori che collegano il backend di un'azienda a Skava. La creazione e il rilascio di un elemento API sono trattati nella pagina Custom Elements: interfacce API; qui copriamo tutto ciò che deve accadere all'altro capo della linea.

L'idea in una frase: Skava non conosce il tuo dominio. Conosce esattamente un formato, la card. Decidi tu cosa dice, noi controlliamo solo forma, dimensioni e sicurezza. Un ordine di materiali è un esempio; la prossima azienda raccoglie feedback degli utenti, quella dopo archivia una foto del cantiere nei propri registri.

Il flusso in sintesi

  1. Un amministratore aziendale crea un elemento API in Skava: un modulo più l'indirizzo, il metodo e il token del tuo backend.
  2. Qualcuno nella chat compila il modulo e lo invia.
  3. Skava chiama il tuo backend e invia i valori compilati in formato JSON.
  4. La tua risposta diventa la card nella chat.
  5. Facoltativamente, puoi segnalare nuovi stati in seguito tramite il callback. Ogni segnalazione diventa un'altra card; quella precedente rimane.

Requisiti per il tuo backend

  • HTTPS. Solo https://, nessun http, nessuna credenziale nell'indirizzo, massimo 2000 caratteri.
  • Accessibile pubblicamente. L'host deve risolvere esclusivamente su indirizzi IP pubblici. Localhost, reti private, indirizzi link-local e metadati cloud vengono rifiutati e questo viene verificato ad ogni chiamata.
  • Indirizzo fisso. Skava risolve l'host una sola volta e fissa la connessione a quell'indirizzo IP. Una modifica DNS durante la chiamata non ha effetto.
  • Nessun reindirizzamento. Un reindirizzamento 301 verso l'indirizzo "corretto" viene considerato un errore. Inserisci subito l'indirizzo finale.
  • Tempo di risposta. Il timeout è configurabile per elemento e ha un limite massimo di 30 secondi. Se hai bisogno di più tempo, rispondi immediatamente e comunica il risultato successivamente tramite il callback.
  • Dimensione della risposta. Skava legge al massimo 256 KiB.
  • Content-Type. Il corpo viene analizzato solo con application/json.

La richiesta che ricevi

Il metodo è GET, POST, PUT o PATCH, a seconda dell'elemento. Con POST, PUT e PATCH i valori arrivano come corpo JSON, con GET come parametri di query.

L'autenticazione è un unico header il cui nome e prefisso del valore sono configurati nell'elemento, solitamente Authorization con il prefisso Bearer . Il token è memorizzato in modo crittografato sul nostro lato. Gli header host, content-length, content-type, cookie e accept-encoding non possono essere impostati.

Il corpo è un oggetto piano. Le chiavi sono scelte da chi ha creato l'elemento; la nidificazione appare solo dove è stato aggiunto un tavolo o un selettore di prodotti:

{"artikelnummer": "5100110", "menge": 20, "note": "Please deliver in the morning", "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "project": "Spitalstrasse 11", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/…", "callback_token": "…"}

Tre chiavi provengono sempre da noi, quindi non usarle tu stesso:

  • locale: il codice lingua dell'utente. Rispondi in quella lingua; noi non traduciamo i tuoi testi.
  • callback_url e callback_token: il callback per questa singola interazione, vedi sotto. Sono presenti solo quando la chiamata proviene da una chat.

I campi contestuali come nome, azienda, progetto o subchat sono compilati dal server stesso, derivati dal canale in cui l'elemento è stato eseguito. Un client manomesso non può dichiarare un nome progetto diverso lì.

La risposta: il formato della card

Rispondi con 2xx e un oggetto card. È esattamente ciò che diventa la card nella chat:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

  • v (obbligatorio): l'intero 1. Come testo ("1") viene rifiutato. Senza di esso la risposta non viene considerata una card e si applica la mappatura della risposta configurata nell'elemento.
  • title: l'intestazione della card.
  • state: solo colore e tonalità dell'icona, uno tra ok, pending, warn, error. Un valore sconosciuto torna a ok e ricevi un suggerimento.
  • status_text: testo libero che non interpretiamo. Si trova in alto nella card ed è anche ciò che appare nell'elenco delle chat e nelle notifiche push.
  • fields: un elenco di label e value. Al massimo 20 voci, label 80 caratteri, value 200, title e status_text 120 ciascuno. I valori troppo lunghi vengono accorciati, non rifiutati: un ordine non deve fallire per un dettaglio.
  • icon: vedi sotto.

Cosa fa Skava ai tuoi testi prima che arrivino alla chat: i ritorni a capo e i caratteri di controllo vengono rimossi (un carattere da destra a sinistra potrebbe altrimenti invertire la visualizzazione di un importo), i backtick vengono sostituiti e tutto ciò che inizia con [SKAVA: viene disattivato. Quest'ultimo impedisce che un valore della carta venga letto come un elemento di chat diverso, ad esempio una richiesta di pagamento.

I link nei campi, l'HTML e le immagini non possono essere impostati. Una chat è un ambiente affidabile e un indirizzo cliccabile da un backend esterno sarebbe un invito a ricreare una pagina di accesso.

Gli input dell'utente appartengono al server: appaiono sulla prima carta e non puoi sovrascriverli. Nella chat costituiscono la registrazione di ciò che è stato effettivamente inviato.

Icone

Con icon la card ottiene il proprio marchio nell'intestazione. Due modalità:

Un nome dal set incluso: package, package-check, package-open, box, boxes, truck, forklift, warehouse, settings, cog, gauge, wrench, hammer, drill, hard-hat, ruler, paint-roller, construction, clipboard-check, receipt, file-text, camera, clock, calendar-clock, circle-check, circle-alert, triangle-alert, send, mail-check, shopping-cart, credit-card, map-pin.

O il tuo SVG come stringa. Da esso Skava estrae solo la geometria (path, circle, ellipse, rect, line, polyline, polygon con i loro attributi numerici) e costruisce la propria immagine. Script, stili, riferimenti esterni, foreignObject e attributi di evento vengono scartati; un doctype o un'entità porta al rifiuto; il file può essere al massimo di 8 KiB e contenere al massimo 16 forme. Colore, spessore del tratto e dimensione sono impostati da Skava, quindi un'icona non può mascherarsi come un controllo. Lavora su una griglia 24 per 24.

Senza icon rimane il marchio predefinito.

Il callback: segnalazione di stati successivi

La chiamata contiene callback_url e callback_token. Usali per segnalare nuovi stati in seguito:

POST <callback_url> con Authorization: Bearer <callback_token> e Content-Type: application/json, corpo al massimo 32 KiB:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

Oltre alla card ci sono tre valori opzionali:

  • seq: il tuo contatore personale. Una segnalazione con un valore inferiore o uguale viene scartata, così due segnalazioni non possono sorpassarsi. Senza seq vince l'ultima arrivata.
  • final: chiude l'interazione. Il token diventa non valido e non vengono mostrate altre card. È consentito anche nella prima risposta, per flussi senza follow-up.
  • notify: impostare su false per pubblicare la card in silenzio, senza conteggio dei non letti e senza notifica. Utile per passaggi intermedi che non devono disturbare nessuno. Senza questa impostazione, la card è un messaggio perfettamente normale.

Ogni rapporto diventa una propria card nella chat, mentre quello precedente rimane. In questo modo è leggibile quale stato è stato segnalato. Ne consegue una raccomandazione: invia solo ciò che è cambiato. Una card che ripete per la quarta volta il numero d'ordine, gli articoli e il totale è solo rumore per il lettore.

Due limiti: lo stesso report inviato due volte non genera una seconda card e un'interazione può pubblicare al massimo 50 card. Un'interazione accetta report per 90 giorni.

Risposte a cui dovresti rispondere

  • 200 con {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Leggi gli indizi: spiegano cosa è stato abbreviato o scartato.
  • 401: token o ID di interazione errati. Non riprovare.
  • 410: interazione chiusa o scaduta. Non riprovare.
  • 422: carta inutilizzabile, con hints come motivo. Correggila prima.
  • 400 JSON non valido, 413 troppo grande, 429 troppe richieste (riprova con un back-off), 500 nostro errore, riprova più tardi.

Esempio 1: un ordine con cronologia degli stati

Passaggio 1, la richiesta al tuo backend:

POST https://api.example.com/v1/orders
Authorization: Bearer <your token>
{"artikelnummer": "5100110", "menge": 20, "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/1111…", "callback_token": "secret"}

Passaggio 2, la tua risposta immediata:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

La chat mostra ora una scheda con un'icona di pacco, lo stato e gli input dell'utente.

Passaggio 3, in seguito durante la preparazione:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Being picked", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

Una seconda scheda silenziosa senza campi: è cambiato solo lo stato.

Passaggio 4, alla spedizione:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}, {"label": "Carrier", "value": "DPD"}]}, "seq": 3}

Questa scheda potrebbe svegliare qualcuno, quindi non c'è notify: false.

Passaggio 5, alla consegna:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "ok", "status_text": "Delivered", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

Con final l'interazione è chiusa e il token non funziona più.

Esempio 2: un'azione senza follow-up

Non ogni flusso ha una cronologia. Un elemento con un singolo campo che invia qualcosa al tuo sistema ha bisogno di una sola risposta:

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

final: true è importante qui: altrimenti l'interazione rimarrebbe aperta per 90 giorni con un token valido, anche se non invierai più alcun report.

Selettore prodotti dal catalogo

Una volta che l'azienda ha caricato il proprio catalogo articoli, l'elemento può contenere il blocco selettore prodotti. L'utente compila un carrello e tu lo ricevi come elenco sotto la chiave scelta da chi ha creato l'elemento:

{"items": [{"artikelnummer": "5100110", "menge": 20}, {"artikelnummer": "5100111", "menge": 2}], "note": "…"}

Poiché la chiave è libera, cerca la prima lista con questa struttura invece di un nome fisso. Prima dell'invio, Skava verifica che ogni numero esista realmente nel catalogo di quell'azienda, per un massimo di 50 elementi. Nella card gli elementi appaiono come una lista con immagine del prodotto, nome e quantità.

Test

  • Ping nell'editor degli elementi invia una richiesta HEAD senza token e senza dati. Rispondi con qualsiasi contenuto; qualsiasi risposta HTTP conta come raggiungibile.
  • Test richiesta esegue una chiamata reale con valori di esempio, anche se l'elemento è ancora una bozza, e mostra la richiesta, la risposta e i messaggi del validatore della card.
  • Anteprima nella scheda accanto: incolla il tuo JSON di risposta, controlla e vedrai la card finita insieme alle indicazioni. Viene verificato sul server con lo stesso codice usato in produzione.
  • Esempio di server: un esempio completo di fornitore è attivo su api.skava.io e utilizza tutto quanto descritto sopra. Il codice sorgente si trova nel repository nella cartella example_order_server/, circa 600 righe di libreria standard pura, pronte per essere copiate.

Cosa altro dovresti sapere

  • La card è un messaggio di chat perfettamente normale. Appare nella ricerca, può essere citata e rimane nella cronologia.
  • Viene inviata dal mittente di sistema, non da un account della tua azienda. Appare comunque sul lato di chi ha eseguito l'elemento e il sistema che lo ha scritto è indicato nel titolo.
  • Chi può eseguirlo è definito sull'elemento: solo i membri dell'azienda o anche esterni che condividono una chat con essa. Quando la tua azienda lascia la chat, il permesso termina automaticamente.
  • Un elemento API con un token scaduto è inattivo e non appare nemmeno nel menu finché un amministratore non ne salva uno nuovo.

Correlati

Creazione e rilascio: Elementi personalizzati: interfacce API. Documenti compilabili invece di interfacce: Elementi personalizzati: documenti.