Vlastné prvky: API

Rozhranie API je formulár, ktorého vyplnené hodnoty Skava odosiela ako JSON na adresu, ktorú zadáte (váš backend). Týmto spôsobom môžete Skavu bezpečne prepojiť s vlastnými systémami.

Nastavenie rozhrania API

Rozhranie pozostáva zo vstupných polí (tieto tvoria JSON), cieľovej adresy a autentifikácie.

1. Vytvorenie polí: Každé pole dostane kľúč JSON. Vpravo vidíte naživo predhľad JSON, ktorý sa pošle do vášho backendu presne v tomto tvare.
2. Adresa (URL): adresa https:// vášho backendu. Povolené sú len adresy HTTPS a verejne prístupné adresy (pozrite Bezpečnosť nižšie).
3. Metóda: POST (predvolené), PUT, PATCH alebo GET. Pri GET sa hodnoty pripoja ako parametre dopytu namiesto odoslania v tele.
4. Autentifikácia: Nastavte názov hlavičky (napr. Authorization) a predponu hodnoty (napr. Bearer ), potom uložte token. Voliteľne nastavte dátum expirácie.
5. Polia odpovede (voliteľné): Definujte podľa cesty, ktoré hodnoty z odpovedi backendu sa majú zobraziť: napr. order.id alebo items[0].sku.
6. Skontrolujte pomocou Ping a Test Request, potom Release.

Bezpečné uloženie tokenu

Token sa ukladá šifrovaný a nikdy sa nevracia klientom: aplikácia zobrazuje iba či je token nastavený a kedy expiruje. Pri odosielaní ho Skava serverovo pripojí do nastaveného hlavičkového parametra. Ak nastavíte dátum expirácie, Skava po uplynutí lehoty odmietne volanie a požiada vás o obnovenie tokenu.

Testovanie: Ping a Testovacia požiadavka

• Ping: kontrola dostupnosti. Skontroluje iba či vaša adresa reaguje a pri tom neposiela token ani údaje z formulára. Zobrazuje dostupnosť, stav a čas odozvy. Ideálne ako prvý krok.
• Testovacia požiadavka: skutočná skúška: pošle na vašu adresu ukážkové údaje vrátane tokenu a zobrazí vám kompletnú odozvu aj extrahované polia odozvy.

Ako administrátor môžete spustiť obe funkcie ešte v režime konceptu a overiť integráciu pred zverejnením.

Koncept a zverejnenie

Každé rozhranie začína ako koncept a dá sa voľne upravovať. Keď je všetko pripravené, zverejníte ho pomocou tlačidla Zverejniť.

Bezpečnosť

Ako tím používa zverejnené rozhranie

Akonáhle je rozhranie zverejnené, všetci členovia firmy ho môžu spustiť priamo z chatu, bez potreby editora. Neexistuje kolektívny vstup ani medzistupňové okno: každý zverejnený prvok sa nachádza v plus menu pod vlastným názvom, s logom firmy, ktorá ho ponúka.

1. V chate klepnite na Plus v dolnej časti a potom na prvok, ktorý chcete, napríklad Objednávka materiálu.
2. Vyplňte formulár a klepnite na Odoslať.
3. Výsledok sa zobrazí ako karta v chate, viditeľná pre všetkých v chate.

Nechajte AI vytvoriť prvok

Ak ste administrátorom firmy, nemusíte editor používať sami. Povedzte asistentovi Skava v čate napríklad „vyrob mi objednávkový formulár pre môj katalóg s množstvom a doručovacou adresou“. Na základe toho vytvorí koncept, neskôr môže meniť polia jedno po druhom a pozná váš nahraný katalóg článkov: pri objednávkach odporučí výber produktu namiesto textového poľa pre číslo článku.

Môže tiež nastaviť: konečný bod a metódu ako aj cielenú skupinu („len členovia firmy“ alebo „aj vonkajší v rovnakej čate“). Pri cielenom skupine sa najprv spýta, namiesto toho, aby ju len nastavil, pretože určuje, kto môže spustiť niečo zvonku.

Čomu sa explicitne vyhýba: prístupový token. Nikdy sa po ňom nepýta a nikdy ho neprijme, pretože správy v čate sa ukladajú. Zadáte si ho sami v editore, inak nevyjde žiadne volanie. A nemôže zverejniť: posledný krok zostáva na vás, takže nič neviditeľné pre zákazníkov bez kontroly.

Kto ho môže spustiť

Záložka „Konečný bod“ hovorí, kto môže prvok používať. Predvolenou hodnotou sú členovia vašej firmy. Druhé nastavenie ho otvorí pre vonkajších, ale len v čate, kde je prítomný niekto z vašej firmy: presne ten prípad, pre ktorý je určený, zákazník, ktorý od vás objednáva. Keď vaša firma opustí chat, oprávnenie skončí samo od seba.

Produkty z vášho vlastného katalógu

Akonce nahrajete katalóg položiek, ponúkne stavebník blok výberu produktu. Nie sú tu žiadne možnosti na údržbu: zoznamom je váš katalóg. Osoba, ktorá objednáva, ho prehľadá, vidí obrázok, názov a číslo položky a váš backend prijme číslo položky. Skava odmieta číslo, ktoré nie je vo vašom katalógu. Pre množstvo umiestnite vedľa neho bežné poľo na číslo.

Kartu si definujte sami

Váš backend rozhoduje, čo karta obsahuje. Skava kontroluje len tvar, veľkosť a bezpečnosť, nikdy význam: nezná stavy objednávok ani názvy polí. Na to odpovedajte objektom card:

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

• v musí byť celé číslo 1. Bez neho sa odpoveď nepočíta ako karta a aplikuje sa mapovanie odpovede nastavené v prvku.
• state obsahuje iba farbu a ikonu: ok, pending, warn alebo error. Všetko, čo nesie význam, patrí do status_text ako voľný text.
• fields je zoznam párov označenia a hodnoty, maximálne 20 položiek. Príliš dlhé hodnoty sa skrácia namiesto zamietnutia, takže objednávka nikdy nezlyhá kvôli detailu.

Vstupy používateľa patria serveru: zostanú nedotknuté bez ohľadu na to, čo pošle vaše backendové riešenie. Sú záznamom v čate o tom, čo sa skutočne odoslalo.

Následné hlásenie stavu

Keď sa prvok spustí, Skava pošle dve ďalšie hodnoty: callback_url a callback_token. Neskôr tam nahlaste nový stav a v čate sa objaví nová karta, aj na telefóne, kým na ňu niekto pozerá. Predchádzajúca karta zostane, takže je čitateľné, ktorý stav bol nahlásený. Pošlite rovnaký objekt card ako vyššie, cez POST s hlavičkou Authorization: Bearer <callback_token>. Tri voliteľné hodnoty idú vedľa karty:

• seq: vlastný počítadlo. Správa s menšou alebo rovnakou hodnotou sa zahodí, takže dve správy sa nemôžu predbiehať.
• final: ukončí interakciu. Token sa stane neplatným a karta je finálna.
• notify: nastavte na false, aby sa karta odoslala ticho, bez počtu neprečítaných správ a bez notifikácie. Pre medzistupne, ktoré by nemali nikoho budiť. Bez tohto parametra je karta úplne bežnou správou.

Interakcia môže odoslať najviac 50 kariet. Dvojnásobné odoslanie rovnakej správy nevytvorí druhú kartu.

Skava odpovie kódom 200 a zoznamom hints, ak sa niečo skrátilo alebo zahodilo, a kódom 422, ak bola karta nepoužiteľná. Interakcia prijíma správy po dobu 90 dní.

Karty zasiela systémový odosielateľ Skavy, nie osoba, ktorá element spustila, ani účet vašej firmy. Ktorý systém píše, je uvedené v názve karty.

Úplný príklad na skopírovanie nájdete v repozitáriu pod example_order_server/ a beží na api.skava.io.

Súvisiace

Chcete namiesto toho vytvoriť vyplnitešablónu dokumentu? Pozrite si Custom Elements: Dokumenty.

Časté otázky