Skava Skava / Wiki

Collegamento di elementi personalizzati per sviluppatori

Questa pagina è destinata agli sviluppatori che collegano il backend di un'azienda a Skava. La creazione e la pubblicazione di un elemento API sono illustrate in Elementi personalizzati: interfacce API; qui copriamo tutto ciò che deve accadere dall'altra parte della linea.

L'idea in una frase: Skava non conosce il tuo dominio. Conosce esattamente un solo formato, la card. Tu decidi cosa contiene, noi verifichiamo solo forma, dimensione e sicurezza. Un ordine di materiali è un esempio; la prossima azienda raccoglie feedback degli utenti, quella successiva 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 resta.

Requisiti per il tuo backend

  • HTTPS. Solo https://, niente http, nessuna credenziale nell'indirizzo, al massimo 2000 caratteri.
  • Accessibile pubblicamente. L'host deve risolvere esclusivamente in IP pubblici. Localhost, reti private, link-local e metadati cloud vengono rifiutati, e questo viene verificato a ogni chiamata.
  • Indirizzo fisso. Skava risolve l'host una sola volta e fissa la connessione a quell'IP. Una modifica DNS durante la chiamata non ha effetto.
  • Nessun redirect. Un 301 verso l'indirizzo "corretto" conta come fallimento. Inserisci subito l'indirizzo finale.
  • Tempo di risposta. Il timeout è configurabile per elemento e limitato a 30 secondi. Se ne serve di più, rispondi subito e riporta il risultato in seguito 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, di solito Authorization con il prefisso Bearer . Il token è memorizzato in modo cifrato da parte nostra. 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 è stata aggiunta una tabella o un selettore di prodotto:

{"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; 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 di contesto come nome, azienda, progetto o subchat vengono compilati dal server stesso, derivati dal canale in cui l'elemento è stato eseguito. Un client manomesso non può dichiarare un nome di progetto diverso lì.

La risposta: il formato 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 essa la risposta non viene conteggiata come card e si applica la mappatura della risposta configurata nell'elemento.
  • title: l'intestazione della card.
  • state: solo colore e tono 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 sulla scheda e viene visualizzato anche 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 troncati, non rifiutati: un ordine non deve fallire per un dettaglio.
  • icon: vedi sotto.

Cosa fa Skava ai tuoi testi prima che arrivino nella chat: a capo e 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 neutralizzato. L'ultima regola impedisce che un valore della scheda venga letto come un altro elemento di chat, ad esempio una richiesta di pagamento.

Nei campi, nell'HTML e nelle immagini non possono essere impostati link. Una chat è un ambiente fidato e un indirizzo cliccabile da un backend esterno sarebbe un invito a ricostruire una pagina di accesso.

Gli input dell'utente appartengono al server: compaiono sulla prima card e non puoi sovrascriverli. Nella chat rappresentano il record di ciò che è stato effettivamente inviato.

Icone

Con icon la card riceve il proprio marchio nell'intestazione. Due modi:

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 questo Skava prende 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; una doctype o un'entità porta al rifiuto; il file può essere al massimo 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 con una griglia di 24 per 24.

Senza icon viene mantenuto il simbolo predefinito.

La callback: segnalazione di stati successivi

La chiamata include callback_url e callback_token. Utilizzali per segnalare nuovi stati in seguito:

POST <callback_url> con Authorization: Bearer <callback_token> e Content-Type: application/json, corpo massimo di 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, sono disponibili tre valori opzionali:

  • seq: il tuo contatore. Un report con un valore minore o uguale viene scartato, così due report non possono sorpassarsi. Senza seq, vince l'ultimo arrivato.
  • final: chiude l'interazione. Il token diventa non valido e non compaiono altre card. È consentito anche nella prima risposta, per flussi senza follow-up.
  • notify: impostalo su false per pubblicare la card in silenzio, senza contatore di non letti e senza notifica. Utile per passaggi intermedi che non devono svegliare nessuno. Senza di esso, la card è un messaggio perfettamente normale.

Ogni report diventa una card propria nella chat, la precedente resta. Così è leggibile quale stato è stato riportato. Da qui una raccomandazione: invia solo ciò che è cambiato. Una card che ripete per la quarta volta numero d'ordine, articoli e totale è solo rumore per chi legge.

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

Risposte a cui devi reagire

  • 200 con {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Leggi gli hint: indicano cosa è stato abbreviato o rimosso.
  • 401: token o interaction id errati. Non ritentare.
  • 410: interaction chiusa o scaduta. Non ritentare.
  • 422: card non utilizzabile, con hints come motivo. Correggi prima.
  • 400 JSON non valido, 413 dimensione eccessiva, 429 troppe richieste (ripetere con back-off), 500 errore nostro, riprovare più tardi.

Esempio 1: un ordine con storico degli stati

Passo 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"}

Passo 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.

Passo 3, in seguito durante la selezione:

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: solo lo stato è cambiato.

Passo 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 niente notify: false.

Passo 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 viene chiusa e il token non è più valido.

Esempio 2: un'azione senza seguiti

Non tutti i flussi hanno una cronologia. Un elemento con un singolo campo che passa dati al tuo sistema richiede solo una 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 resterebbe aperta per 90 giorni con un token valido, anche se non invierai più aggiornamenti.

Selettore di prodotti dal catalogo

Una volta che l'azienda ha caricato il catalogo articoli, l'elemento può contenere il blocco selettore prodotti. L'utente compone un carrello da questo, 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 il primo elenco con questa struttura anziché un nome fisso. Prima dell'invio, Skava verifica che ogni numero esista realmente nel catalogo di quell'azienda, per un massimo di 50 articoli. Nella card gli articoli appaiono come elenco con immagine prodotto, nome e quantità.

Test

  • Ping nell'editor dell'elemento invia un HEAD nudo, senza token e senza dati. Rispondi con qualsiasi cosa; qualsiasi risposta HTTP conta come raggiungibile.
  • Richiesta di test esegue una chiamata reale con valori di esempio, anche se l'elemento è ancora in bozza, e mostra la richiesta, la risposta e i messaggi del validatore della card.
  • Anteprima nella scheda accanto: incolla la tua risposta JSON, verifica e vedrai la card finita insieme alle indicazioni. Viene controllata sul server con lo stesso codice usato in produzione.
  • Server di esempio: un fornitore di esempio completo è attivo su api.skava.io e utilizza tutto quanto descritto sopra. Il suo codice sorgente si trova nel repository sotto example_order_server/, circa 600 righe di libreria standard pura, pensato per essere copiato.

Cosa altro dovresti sapere

  • La card è un messaggio di chat perfettamente normale. Compare nella ricerca, può essere citato e resta nella cronologia.
  • Viene inviata dal mittente di sistema, non da un account della tua azienda. Compare comunque sul lato di chi ha eseguito l'elemento e il titolo indica quale sistema sta scrivendo.
  • Chi può eseguirlo è definito sull'elemento: solo i membri dell'azienda o anche esterni che condividono una chat con esso. Quando la tua azienda lascia la chat, il permesso termina automaticamente.
  • Un elemento API con token scaduto è inattivo: le app attuali lo nascondono nel menu e una chiamata inviata comunque viene rifiutata lato server. Un amministratore salva un nuovo token per esso, il che funziona anche su un'interfaccia rilasciata.

Correlati

Creazione e rilascio: Elementi personalizzati: interfacce API. Documenti compilabili al posto delle interfacce: Elementi personalizzati: documenti.