Vlastné prvky: rozhranie API

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

Nastavenie rozhrania API

Rozhranie pozostáva z poľov na vstup (tvoria JSON), cieľovej adresy a overenia totožnosti.

1. Vytvorte polia: Každé pole dostane kľúč JSON. Vpravo vidíte živý náhľad JSON, ktorý sa presne takto odošle na váš backend.
2. Adresa (URL): adresa https:// vášho backendu. Povolené sú iba adresy HTTPS a verejne prístupné (pozri Bezpečnosť nižšie).
3. Metóda: POST (predvolená), PUT, PATCH alebo GET. Pri metóde GET sa hodnoty pripoja ako parametre dotazu namiesto odoslania v tele správy.
4. Overenie totožnosti: Nastavte názov hlavičky (napr. Authorization) a predponu hodnoty (napr. Bearer ), potom uložte token. Voliteľne nastavte dátum exspirácie.
5. Polia odpovede (voliteľné): Definujte podľa cesty, ktoré hodnoty z odpovede backendu sa majú zobraziť: napr. order.id alebo items[0].sku.
6. Skontrolujte pomocou Ping a Test Request, potom Release.

Bezpečné ukladanie tokenu

Token sa ukladá zašifrovaný a nikdy sa nevracia klientom: aplikácia zobrazuje len či je token nastavený a kedy vyprší. Pri odosielaní ho aplikácia Skava pridáva na strane servera do nastaveného hlavičky. Ak nastavíte dátum exspirácie, aplikácia Skava po uplynutí odmietne volanie a požiada vás o obnovenie tokenu.

Testovanie: Ping a Testovacie žiadosti

• Ping : ľahká kontrola dostupnosti. Skontroluje len či na vašu adresu reaguje a pri tom neposieľa token ani údaje formulára. Zobrazuje dostupnosť, stav a čas odozvy. Ideálne ako prvý krok.
• Testovacia požiadavka : skutočná skúšobná jazda: posiela ukážkové údaje vrátane tokenu na vašu adresu a zobrazuje vám kompletnú odpoveď aj extrahované polia odpovede.

Ako administrátor môžete spustiť obe akcie ešte v režime konceptu, aby ste overili integráciu pred uvoľnením.

Návrh a uvoľnenie

Každé rozhranie začína ako návrh a môže byť voľne upravované. Keď je všetko hotové, uvoľníte ho pomocou Uvoľniť.

Bezpečnosť

Ako tím používa uvoľnené rozhranie

Akonáhle je rozhranie uvoľnené, všetci členovia firmy ho môžu spustiť priamo z chatu: nie je potrebný žiadny editor. Príbeh je rovnaký ako pri šablónach dokumentov: vybrať, vyplniť, odoslať.

1. V chate klepnite na Plus v spodnej časti a vyberte Vlastný prvok.
2. Vyberte požadovanú šablónu alebo rozhranie zo zoznamu.
3. Vyplňte formulár a Odoslať.
4. Výsledok sa zobrazí ako karta v čate: viditeľná pre všetkých v čate.

Nechajte AI vytvoriť prvok

Ako administrátor firmy nemusíte editor používať sami. Povedzte asistentovi Skava v čate napríklad „vytvor mi objednávkový formulár pre môj katalóg s množstvom a doručovacou adresou". Vytvorí z toho koncept, neskôr môžete po jednom meniť polia a pozná váš nahraný katalóg tovaru: pri objednávkach navrhne výber tovaru namiesto textového poľa pre číslo položky.

Čo môže tiež nastaviť: koncový bod a metódu ako aj cieľovú skupinu („len členovia firmy" alebo „tiež cudzí v rovnakej čate"). Pre cieľovú skupinu sa najprv opýta, namiesto toho, aby ju len nastavila, pretože rozhoduje o tom, kto môže spustiť niečo zvonku.

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

Kto ho môže spustiť

Karta „Koncový bod" uvádza, kto môže prvok používať. Predvolená hodnota sú členovia vašej firmy. Druhé nastavenie ho otvára cudzím, ale len v čate, kde je prítomný niekto z vašej firmy: presne ten prípad, na ktorý je určený, keď zákazník od vás objednáva. Keď vaša firma opustí chat, oprávnenie samo o sebe končí.

Produkty z vlastného katalógu

Po nahraní katalógu tovaru vám konštruktér ponúkne blok výberu produktu. Žiadne možnosti údržby nie sú potrebné: zoznam je váš katalóg. Objednávateľ ho vyhľadá, uvidí obrázok, názov a číslo tovaru a váš backend dostane číslo tovaru. Skava odmietne číslo, ktoré nie je vo vašom katalógu. Pre množstvo umiestnite vedľa neho bežné poľo pre číslo.

Kartu si definujte sami

Váš backend rozhoduje, čo bude na karte napísané. Skava kontroluje iba tvar, veľkosť a bezpečnosť, nikdy nie význam: nezná ani stavy objednávky, ani názvy polí. Aby ste to dosiahli, 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ď nepovažuje za kartu a použije sa mapovanie odpovede nakonfigurované v prvku.
• state je iba farba a ikona: ok, pending, warn alebo error. Všetko, čo nesie význam, sa umiestni do status_text ako voľný text.
• fields je zoznam označení a hodnôt, maximálne 20 položiek. Príliš dlhé hodnoty sa skrácia namiesto zamietnutia, takže objednávka nikdy zlyhá kvôli detailu.

Vstupy používateľa patria serveru: zostanú nezmenené bez ohľadu na to, čo váš backend pošle. Sú záznamom v čate o tom, čo bolo skutočne odoslané.

Následné hlásenie stavu

Keď sa prvok spustí, Skava odošle dve ďalšie hodnoty: callback_url a callback_token. Neskôr tam nahlašte nový stav a v čate sa objaví nová karta, aj na telefóne, zatiaľ čo ju niekto sleduje. Predchádzajúca zostane, takže je čitateľné, ktorý stav bol nahlásený. Odošlite rovnaký objekt card ako vyššie prostredníctvom POST s hlavičkou Authorization: Bearer <callback_token>. Ďalej vedľa karty idú tri voliteľné hodnoty:

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

Interakcia môže odoslať najviac 50 kariet. Dvakrát rovnaká správa nevytvorí druhú kartu.

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

Karty sú odoslané systémovým odosielateľom Skava, nie osobou, ktorá spustila prvok, ani účtom vašej vlastnej firmy. Ktorý systém písal, je uvedené v nadpise karty.

Úplný príklad na kopírovanie sa nachádza v repozitári v priečinku example_order_server/ a spúšťa sa na adrese api.skava.io.

Súvisiace

Chceli ste skôr vytvoriť vyplniteľnú šablónu dokumentu? Pozrite si Vlastné prvky: Dokumenty.

Často kladené otázky