Această pagină este destinată dezvoltatorilor care conectează backend-ul unei companii la Skava. Modul în care se creează și se lansează un element API este prezentat la Elemente personalizate: interfețe API; aici acoperim tot ce trebuie să se întâmple la celălalt capăt al conexiunii.

Ideea într-o propoziție: Skava nu cunoaște domeniul dumneavoastră. Cunoaște exact un singur format: cardul. Decideți dumneavoastră ce conține, noi verificăm doar forma, dimensiunea și siguranța. O comandă de materiale este un exemplu; următoarea companie colectează feedback-ul utilizatorilor, iar cea de după aceea arhivează o fotografie de șantier în propriile înregistrări.

Fluxul în esență

1. Un administrator de companie creează un element API în Skava: un formular împreună cu adresa, metoda și token-ul backend-ului dumneavoastră.
2. Cineva din chat completează formularul și îl trimite.
3. Skava apelează backend-ul tău și trimite valorile completate sub formă de JSON.
4. Răspunsul tău devine cartea din chat.
5. Opțional, poți raporta mai târziu stări noi prin intermediul callback-ului. Fiecare raport devine o altă carte; cea anterioară rămâne.

Cerințe pentru backend-ul tău

• HTTPS. Doar https://, fără http, fără credențiale în adresă, maximum 2000 de caractere.
• Accesibil public. Gazda trebuie să se rezolve exclusiv la adrese IP publice. Localhost, rețelele private, link-local și metadatele cloud sunt respinse, iar acest lucru este verificat la fiecare apel.
• Adresă fixă. Skava rezolvă gazda o singură dată și fixează conexiunea la acea adresă IP. O modificare DNS în timpul apelului nu are niciun efect.
• Fără redirecționări. O redirecționare 301 către adresa „corectă" este considerată o eroare. Introduceți adresa finală imediat.
• Timp de răspuns. Timpul de așteptare este configurabil pentru fiecare element și are o limită maximă de 30 de secunde. Dacă aveți nevoie de mai mult timp, răspundeți imediat și raportați rezultatul ulterior prin callback.
• Mărimea răspunsului. Skava citește cel mult 256 KiB.
• Content-Type. Corpul este analizat doar cu application/json.

Cerința care ajunge la tine

Metoda este GET, POST, PUT sau PATCH, în funcție de element. La POST, PUT și PATCH, valorile ajung ca un corp JSON, iar la GET ca parametri de interogare.

Autentificarea este un singur antet al cărui nume și prefixul valorii sunt configurate în element, de obicei Authorization cu prefixul Bearer . Tokenul este stocat criptat pe partea noastră. Anteturile host, content-length, content-type, cookie și accept-encoding nu pot fi setate.

Corpul este un obiect plat. Cheile sunt alese de cel care a creat elementul; imbricarea apare doar acolo unde s-a adăugat o tabelă sau un selector de produse:

{"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": "…"}

Trei chei vin întotdeauna de la noi, deci nu le folosiți singuri:

• locale: codul limbii utilizatorului. Răspundeți în acea limbă; nu traducem textele dumneavoastră.
• callback_url și callback_token: callback-ul pentru această interacțiune unică, vezi mai jos. Acestea sunt prezente doar când apelul provine dintr-un chat.

Câmpurile de context, cum ar fi name, company, project sau subchat, sunt completate de server, derivate din canalul în care a fost rulat elementul. Un client modificat nu poate pretinde un alt nume de proiect acolo.

Răspunsul: formatul cardului

Răspundeți cu 2xx și un obiect card. Exact acesta devine cardul din 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 (obligatoriu): numărul întreg 1. Ca text ("1") este respins. Fără el, răspunsul nu este considerat un card și se aplică mapearea răspunsului configurată în element.
• title: titlul cardului.
• state: doar culoarea și tonul iconiței, unul dintre ok, pending, warn, error. O valoare necunoscută revine la ok și primiți un indiciu.
• status_text: text liber pe care nu îl interpretăm. Se află în partea superioară a cardului și este, de asemenea, ceea ce apare în lista de chat și într-o notificare push.
• fields: o listă de label și value. Maxim 20 de intrări, label 80 de caractere, value 200, title și status_text câte 120 fiecare. Valorile prea lungi sunt scurte, nu respinse: o comandă nu trebuie să eșueze din cauza unui detaliu.
• icon: vezi mai jos.

Ce face Skava cu textele tale înainte să ajungă în chat: se elimină liniile noi și caracterele de control (un caracter de la dreapta la stânga ar putea inversa afișarea unei sume), se înlocuiesc cratimele inversate și orice începe cu [SKAVA: este dezactivat. Ultimul aspect previne ca o valoare de card să fie interpretată ca un alt element de chat, de exemplu o cerere de plată.

Linkurile din câmpuri, HTML și imaginile nu pot fi setate. Un chat este un mediu de încredere, iar o adresă clicabilă dintr-un backend extern ar fi o invitație de a reconstrui o pagină de autentificare.

intrările utilizatorului aparțin serverului: ele apar pe primul card și nu le poți suprascrie. În chat, acestea reprezintă înregistrarea a ceea ce a fost efectiv trimis.

Pictograme

Cu icon, cardul primește propria sa marcă în antet. Două modalități:

Un nume din setul inclus: 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.

Sau propriul tău SVG ca șir. Din acesta, Skava preia doar geometria (path, circle, ellipse, rect, line, polyline, polygon cu atributele lor numerice) și construiește propria imagine. Scripturile, stilurile, referințele externe, foreignObject și atributele de evenimente sunt eliminate; un doctype sau o entitate duce la respingere; fișierul poate avea cel mult 8 KiB și poate conține cel mult 16 forme. Culoarea, grosimea conturului și dimensiunea sunt setate de Skava, astfel încât o pictogramă nu se poate masca ca un element de control. Lucrați cu o grilă de 24 x 24.

Fără icon, marca implicită rămâne.

Callback-ul: raportarea stărilor ulterioare

Apelul conține callback_url și callback_token. Folosiți-le pentru a raporta stări noi ulterior:

POST <callback_url> cu Authorization: Bearer <callback_token> și Content-Type: application/json, corpul de maximum 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}

Pe lângă card, există trei valori opționale:

• seq: contorul propriu. Un raport cu o valoare mai mică sau egală este ignorat, astfel încât două rapoarte nu se pot depăși reciproc. Fără seq, câștigă ultimul raport primit.
• final: încheie interacțiunea. Tokenul devine invalid și nu mai apar alte carduri. Este permis și în răspunsul first, pentru fluxuri fără continuări.
• notify: setat la false pentru a publica cardul discret, fără număr de citit și fără notificare. Pentru pași intermediari care nu trebuie să trezească pe nimeni. Fără acesta, cardul este un mesaj perfect normal.

Fiecare raport devine propria sa card în chat, cel anterior rămânând. Astfel, este clar ce stare a fost raportată. De aici rezultă o recomandare: trimiteți doar ce s-a schimbat. Un card care repetă numărul comenzii, articolele și totalul pentru a patra oară este doar zgomot pentru cititor.

Două limite: același raport de două ori nu generează o a doua card, iar o interacțiune poate posta cel mult 50 de carduri. O interacțiune acceptă rapoarte timp de 90 de zile.

Răspunsuri la care ar trebui să reacționați

• 200 cu {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Citiți indiciile: acestea spun ce a fost scurtat sau eliminat.
• 401: token greșit sau id de interacțiune. Nu reîncercați.
• 410: interacțiune închisă sau expirată. Nu reîncercați.
• 422: card inutilizabil, cu hints ca motiv. Reparați-l mai întâi.
• 400 JSON defect, 413 prea mare, 429 prea multe cereri (reîncercați cu o pauză progresivă), 500 vina noastră, reîncercați mai târziu.

Exemplul 1: o comandă cu istoric de status

Pașul 1, cererea către backend-ul tău:

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

Pașul 2, răspunsul tău imediat:

{"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"}]}}

Chatul afișează acum o card cu o pictogramă de colet, statusul și intrările utilizatorului.

Pașul 3, mai târziu, în timpul preluării:

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

O a doua card liniștit, fără câmpuri: s-a schimbat doar starea.

Pașul 4, la expediere:

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}

Acest card ar putea trezi pe cineva, de aceea nu se folosește notify: false.

Pașul 5, la livrare:

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

Cu final interacțiunea se încheie și token-ul nu mai funcționează.

Exemplul 2: o acțiune fără urmări

Nu fiecare flux are un istoric. Un element cu un singur câmp care transmite ceva sistemului tău are nevoie doar de un răspuns:

{"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 contează aici: altfel, interacțiunea ar rămâne deschisă timp de 90 de zile cu un token valid, chiar dacă nu vei mai raporta nimic.

Selector de produse din catalog

Odată ce compania a încărcat catalogul de articole, elementul poate conține blocul selector de produse. Utilizatorul compune un coș din acesta, iar tu îl primești ca o listă sub cheia aleasă de cineva care a construit elementul:

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

Deoarece cheia este liberă, căutați prima listă care are această formă, nu un nume fix. Înainte de trimitere, Skava verifică dacă fiecare număr există cu adevărat în catalogul acelei companii, maxim 50 de articole. În card, articolele apar ca o listă cu imaginea produsului, numele și cantitatea.

Testare

• Ping în editorul de elemente trimite un HEAD gol, fără token și fără date. Răspundeți cu orice; orice răspuns HTTP este considerat accesibil.
• Testare solicitare declanșează o apelare reală cu valori de probă, chiar dacă elementul este încă în stadiu de schiță, și afișează solicitarea, răspunsul și mesajele validatorului de card.
• Previzualizare în fila de lângă ea: lipiți JSON-ul răspunsului, verificați și veți vedea cardul finalizat plus indicațiile. Este verificat pe server cu același cod ca în producție.
• Exemplu de server: un furnizor complet funcțional rulează la api.skava.io și folosește tot ce a fost descris mai sus. Sursa sa se află în repository, în example_order_server/, aproximativ 600 de linii de cod din biblioteca standard, gata de copiat.

Ce altceva ar trebui să știți

• Cardul este un mesaj de chat perfect normal. Apare în căutare, poate fi citat și rămâne în istoric.
• Este trimis de către expeditorul sistemului, nu de un cont al companiei dumneavoastră. Totuși, apare în partea celui care a executat elementul, iar sistemul care scrie este menționat în titlu.
• Cine poate executa elementul este setat pe acesta: doar membrii companiei sau și persoanele din afara care împărtășesc un chat cu ea. Când compania dumneavoastră părăsește chatul, permisiunea se anulează automat.
• Un element API cu un token expirat este inactiv și nu apare nici măcar în meniul până când un administrator salvează unul nou.

Conex

Creare și lansare: Elemente personalizate: interfețe API. Documente completabile în loc de interfețe: Elemente personalizate: documente.