Elemente personalizate: API

O interfață API este un formular ale cărui valori completate Skava le trimite sub formă de JSON către o adresă specificată de dumneavoastră (backend-ul propriu). Astfel puteți conecta Skava în siguranță cu sistemele dumneavoastră.

Configurarea unei interfețe API

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

1. Creează câmpuri: Fiecare câmp primește un cheie JSON. În dreapta vezi în timp real previzualizarea JSON, care este trimisă către backend-ul tău exact în acest mod.
2. Adresă (URL): adresa https:// a backend-ului tău. Sunt permise doar adrese HTTPS și accesibile public (vezi Secțiunea de mai jos).
3. Metodă: POST (implicit), PUT, PATCH sau GET. Cu 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ă token-ul. Opțional, setează o dată de expirare.
5. Câmpuri de răspuns (opțional): Definește prin cale valorile din răspunsul backend-ului care trebuie afișate: de ex. order.id sau items[0].sku.
6. Verificați cu Ping și Test Request, apoi Release.

Stocare securizată a token-ului

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

Testare: Ping și Testare Cerere

• Ping : o verificare ușoară a accesibilității. Verifică doar dacă adresa dumneavoastră răspunde și nu trimite token sau date de formular în acest proces. Afișează accesibilitatea, starea și timpul de răspuns. Ideal ca prim pas.
• Cerință de testare : simularea reală: trimite date de probă, inclusiv token, către adresa dumneavoastră și vă arată răspunsul complet, precum și câmpurile de răspuns extrase.

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

Schiță și lansare

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

Securitate

Cum folosește echipa o interfață lansată

Odată ce o interfață este lansată, toți membrii companiei o pot declanșa direct din chat: nu este necesar un editor. Fluxul este același ca și pentru șabloanele de documente: selectați, completați, trimiteți.

1. În chat, atingeți Plus în partea de jos și alegeți Element personalizat.
2. Selectați șablonul sau interfața dorită din listă.
3. Completați formularul și Trimiteți.
4. Rezultatul apare sub formă de card în chat: vizibil pentru toți participanții la conversație.

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

Ca administrator al companiei, 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 proiect din asta, 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 mai poate seta: punctul final și metoda, precum și publicul țintă („doar membrii companiei" sau „și persoanele din afara companiei din același chat"). Pentru publicul țintă, întreabă mai întâi în loc să îl seteze direct, deoarece decide cine poate executa ceva din exterior.

Ce nu atinge explicit: token-ul de acces. Nu cere niciodată unul și nu acceptă niciodată unul, deoarece mesajele din chat sunt stocate. Îl introduceți singur în editor, altfel nu se face nicio apelare. Și nu poate publica: pasul final rămâne la dumneavoastră, astfel încât nimic nu devine vizibil clienților fără verificare.

Cine îl poate executa

Pesta „Punct final" indică cine poate folosi un element. Implicit, sunt membrii companiei dumneavoastră. A doua setare îl deschide pentru persoanele din afara companiei, dar doar într-un chat unde 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 chat-ul, permisiunea se încheie automat.

Produse din catalogul propriu

După ce ați încărcat catalogul de articole, constructorul oferă un bloc de selecție a produselor. Nu există opțiuni de configurare: lista este catalogul dumneavoastră. Persoana care comandă îl caută, vede imaginea, numele și numărul de articol, iar backend-ul dumneavoastră primește numărul de articol. Skava respinge un număr care nu se află în catalogul dumneavoastră. Pentru cantitate, adăugați un câmp numeric obișnuit lângă el.

Definiți cardul singur

Backend-ul dumneavoastră decide ce scrie cardul. Skava verifică doar forma, dimensiunea și siguranța, niciodată sensul: nu cunoaște nici stările comenzilor, nici numele câmpurilor. Pentru a face acest lucru, răspundeți 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ă acesta, răspunsul nu este considerat un card și se aplică mapearea răspunsului configurată în element.
• state este doar culoarea și iconița: ok, pending, warn sau error. Tot ce are semnificație 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 se taie în loc să fie respinse, astfel încât o comandă nu eșuează din cauza unui detaliu.

Intrările utilizatorului 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 stării ulterior

Când elementul se execută, Skava trimite două valori suplimentare: callback_url și callback_token. Raportați o nouă stare acolo ulterior și o nouă card va apărea în chat, chiar și pe telefon, în timp ce cineva privește. Cel anterior rămâne, astfel încât să fie clar 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 adaugă lângă card:

• 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.
• final: închide interacțiunea. Tokenul devine invalid și cardul este final.
• notify: setați la false pentru a posta cardul discret, fără număr de mesaje necitite și fără notificare. Pentru pași intermediari care nu trebuie să trezească pe nimeni. Fără această opțiune, cardul este un mesaj perfect normal.

O interacțiune poate posta cel mult 50 de carduri. Același raport de două ori nu generează 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 nu a fost utilizabil. O interacțiune acceptă rapoarte timp de 90 de zile.

Cardurile sunt publicate de sistemul de expediere al Skava, nu de persoana care a executat elementul și nu de un cont al propriei companii. Titlul cardului indică sistemul care a generat mesajul.

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

Conex

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

Întrebări frecvente