Elemente personalizate: API

O interfață API este un formular ale cărui valori completate Skava le trimite sub formă de JSON la o adresă pe care o specificați (backend-ul dvs.). Astfel puteți conecta Skava în mod securizat cu propriile sisteme.

Configurați o interfață API

O interfață este compusă din câmpuri de intrare (care formează JSON-ul), adresa țintă și autentificarea.

1. Creezi câmpuri: Fiecare câmp primește o cheie JSON. În dreapta vedeți în timp real previzualizarea JSON, care este trimisă către backendul dvs. exact în acest format.
2. Adresă (URL): adresa https:// a backendului dvs. Sunt permise doar adrese HTTPS și accesibile public (a se vedea Securitatea de mai jos).
3. Metodă: POST (implicit), PUT, PATCH sau GET. În cazul GET, valorile sunt adăugate ca parametri de interogare în loc să fie trimise în corpul cererii.
4. Autentificare: Setează numele antetului (de ex. Authorization) și prefixul valorii (de ex. Bearer ), apoi salvează jetonul. Opțional, setează o dată de expirare.
5. Câmpuri de răspuns (opțional): Definește prin cale ce valori din răspunsul backendului trebuie afișate: de ex. order.id sau items[0].sku.
6. Verifică cu Ping și Test Request, apoi Release.

Stocați tokenul în mod securizat

Tokenul este stocat criptat și nu este niciodată returnat clienților: aplicația afișează doar dacă este setat un token și când expiră. La trimitere, Skava îl adaugă pe partea de server în antetul configurat. Dacă setați o dată de expirare, Skava refuză apelul după expirare și vă solicită să reînnoiți tokenul.

Testare: Ping și Cerere de test

• Ping : o verificare simplă de accesibilitate. Verifică doar dacă adresa ta răspunde, fără a trimite jeton sau date de formular în acest proces. Afișează accesibilitatea, starea și timpul de răspuns. Ideal ca prim pas.
• Test Request : rula reală de probă: trimite date de exemplu, inclusiv jetonul, către adresa ta și îți afișează răspunsul complet, precum și câmpurile de răspuns extrase.

Ca administrator, poți rula ambele în modul de schiță pentru a verifica integrarea înainte de lansare.

Schiță și publicare

Fiecare interfață începe ca schiță și poate fi editată liber. Odată ce totul este gata, o publici cu Publicare.

Securitate

Cum folosește echipa o interfață publicată

Odată ce o interfață este publicată, toți membrii companiei o pot declanșa direct din chat, fără editor. Nu există un punct de intrare colectiv și niciun dialog intermediar: fiecare element publicat apare în meniul plus sub numele său, împreună cu logo-ul companiei care îl oferă.

1. În chat, atingeți Plus de jos și selectați elementul dorit, de exemplu Comandă materiale.
2. Completați formularul și apăsați Trimite.
3. Rezultatul apare ca o card în chat, vizibil pentru toți participanții la conversație.

Lăsați AI-ul să construiască un element

Ca administrator de companie, nu trebuie să folosiți editorul personal. Spuneți asistentului Skava în chat, de exemplu „construiește-mi un formular de comandă pentru catalogul meu, cu cantitate și adresă de livrare”. Acesta creează un ciornă pe baza cererii, poate modifica câmpurile unul câte unul ulterior și cunoaște catalogul de articole încărcat: pentru comenzi, sugerează selectorul de produse în loc de un câmp de text pentru numărul de articol.

Ce poate configura și acesta: punctul de acces și metoda, precum și publicul țintă („doar membrii companiei” sau „și persoanele externe din același chat”). Pentru publicul țintă, întreabă mai întâi în loc să seteze direct, deoarece acesta decide cine poate executa o acțiune din exterior.

Ce nu atinge explicit: tokenul de acces. Nu îl solicită niciodată și nu îl acceptă niciodată, deoarece mesajele din chat sunt stocate. Îl introduceți dumneavoastră în editor, altfel nu se trimite nicio solicitare. Și nu poate publica: pasul final rămâne în responsabilitatea dumneavoastră, astfel încât nimic nu devine vizibil pentru clienți fără verificare.

Cine îl poate executa

Fila „Punct de acces” indică cine poate utiliza un element. Setarea implicită este membrii companiei dumneavoastră. A doua setare îl deschide pentru persoanele externe, dar doar într-un chat în care este prezent și cineva din compania dumneavoastră: exact cazul pentru care este conceput, clientul care comandă de la dumneavoastră. Când compania dumneavoastră părăsește chatul, permisiunea se încheie automat.

Produse din catalogul propriu

După ce ai încărcat catalogul de articole, constructorul oferă un bloc selector de produse. Nu există opțiuni de întreținut: lista este catalogul tău. Persoana care comandă caută în ea, vede imaginea, numele și numărul de articol, iar backend-ul tău primește numărul de articol. Skava respinge un număr care nu se află în catalogul tău. Pentru cantitate, așază un câmp numeric obișnuit lângă el.

Definește cardul singur

Backend-ul tău decide ce scrie pe card. Skava verifică doar structura, dimensiunea și siguranța, niciodată sensul: nu cunoaște stările comenzii, nici numele câmpurilor. Pentru a face acest lucru, răspunde cu un obiect card:

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

• v trebuie să fie numărul întreg 1. Fără el, răspunsul nu este considerat un card și se aplică maparea răspunsului configurată în element.
• state conține doar culoarea și pictograma: ok, pending, warn sau error. Tot ce transmite sens se introduce în status_text ca text liber.
• fields este o listă de etichete și valori, cu maximum 20 de intrări. Valorile prea lungi sunt scurtate, nu respinse, astfel încât o comandă nu eșuează din cauza unui detaliu.

Datele introduse de utilizator aparțin serverului: rămân neschimbate, indiferent ce trimite backend-ul. Ele reprezintă înregistrarea din chat a ceea ce a fost efectiv trimis.

Raportarea ulterioară a stării

Când elementul rulează, Skava trimite două valori suplimentare: callback_url și callback_token. Raportați o stare nouă acolo ulterior și o card nouă apare în chat, inclusiv pe telefon, în timp ce cineva o privește. Anteriorul rămâne, astfel încât se poate citi care stare a fost raportată. Trimiteți același obiect card ca mai sus, prin POST cu antetul Authorization: Bearer <callback_token>. Trei valori opționale se află lângă card:

• seq: contorul propriu. Un raport cu o valoare mai mică sau egală este eliminat, astfel încât două rapoarte nu se pot depăși reciproc.
• final: închide interacțiunea. Tokenul devine invalid și cardul devine final.
• notify: setat la false pentru a publica cardul discret, fără număr de necitite și fără notificare. Pentru pași intermediari care nu ar trebui să trezească pe nimeni. Fără acest parametru, cardul este un mesaj perfect normal.

O interacțiune poate publica cel mult 50 de carduri. Același raport de două ori nu produce un al doilea card.

Skava răspunde cu 200 și o listă de hints dacă ceva a fost scurtat sau eliminat, și cu 422 dacă cardul a fost inutilizabil. O interacțiune acceptă rapoarte timp de 90 de zile.

Cardurile sunt publicate de sistemul de trimitere al Skava, nu de persoana care a executat elementul și nici de un cont al propriei companii. Sistemul care scrie este menționat în titlul cardului.

Un exemplu complet de copiat se găsește în depozit, sub example_order_server/, și rulează pe api.skava.io.

Conexe

Doriți în schimb să construiți un șablon de document completabil? Consultați Elemente personalizate: Documente.

Întrebări frecvente