Vlastní prvky: rozhraní API

Rozhraní API je formulář, jehož vyplněné hodnoty Skava odešle ve formátu JSON na adresu, kterou určíte (vaše backendové systémy). Tímto způsobem můžete Skava bezpečně propojit s vlastními systémy.

Nastavení rozhraní API

Rozhraní se skládá z vstupních polí (která tvoří JSON), cílové adresy a ověření.

1. Vytvoření polí: Každé pole má klíč JSON. Vpravo vidíte živý náhled JSON, který je odeslán na váš backend právě takto.
2. Adresa (URL): adresa https:// vašeho backendu. Povoleny jsou pouze adresy HTTPS a veřejně přístupné (viz Bezpečnost níže).
3. Metoda: POST (výchozí), PUT, PATCH nebo GET. U GET se hodnoty připojují jako parametry dotazu místo odeslání v těle požadavku.
4. Ověření: Nastavte název hlavičky (např. Authorization) a předponu hodnoty (např. Bearer ), poté uložte token. Volitelně nastavte datum expirace.
5. Pole odpovědi (volitelné): Definujte cestou, které hodnoty z odpovědi backendu se mají zobrazit: např. order.id nebo items[0].sku.
6. Ověřte pomocí Ping a Test Request, poté Release.

Bezpečné ukládání tokenu

Token je uložen šifrovaný a nikdy se nevrací klientům: aplikace pouze zobrazuje, zda je token nastaven a kdy vyprší. Při odesílání Skava přidá token na straně serveru do konfigurovaného hlavičky. Pokud nastavíte datum expirace, Skava po jeho uplynutí odmítne volání a požádá vás o obnovení tokenu.

Testování: Ping a Test Request

• Ping : rychlá kontrola dostupnosti. Zjišťuje pouze zda na vaši adresu reaguje a při tom neposílá token ani data formuláře. Zobrazuje dostupnost, stav a dobu odezvy. Ideální jako první krok.
• Zkušební požadavek : skutečná zkouška: odesílá vzorková data včetně tokenu na vaši adresu a zobrazuje kompletní odpověď včetně extrahovaných polí odpovědi.

Jako správce můžete spustit obě akce ještě v režimu návrhu, abyste ověřili integraci před vydáním.

Návrh a uvolnění

Každé rozhraní začíná jako návrh a lze jej volně upravovat. Jakmile je vše připraveno, uvolníte jej pomocí Uvolnit.

Zabezpečení

Jak tým využívá uvolněné rozhraní

Jakmile je rozhraní uvolněno, všichni členové firmy ho mohou spustit přímo z chatu: není potřeba žádný editor. Průběh je stejný jako u šablon dokumentů: vybrat, vyplnit, odeslat.

1. V chatu klepněte dole na Přidat a zvolte Vlastní prvek.
2. Vyberte požadovanou šablonu nebo rozhraní ze seznamu.
3. Vyplňte formulář a Odeslat.
4. Výsledek se zobrazí jako karta v chatu: viditelná pro všechny v chatu.

Ponechte, aby AI vytvořila prvek

Jako administrátor firmy nemusíte editor používat sami. Řekněte asistentovi Skava v chatu například „vytvoř mi objednávkový formulář pro můj katalog s množstvím a doručovací adresou". Vytvoří z toho návrh, později můžete pole měnit po jednom a zná váš nahraný katalog článků: pro objednávky navrhne výběr produktu místo textového pole pro číslo článku.

Co může také nastavit: koncový bod a metodu jakož i cílovou skupinu („pouze členové firmy" nebo „také vnější osoby ve stejném chatu"). U cílové skupiny se nejprve zeptá, místo aby ji jen nastavila, protože rozhoduje, kdo může spustit něco zvenčí.

Co explicitně nezasahuje: přístupový token. Nikdy se po něm neptá a nikdy ho nepřijímá, protože zprávy v chatu se ukládají. Zadáte ho sami v editoru, jinak žádný volání neodejde. A nemůže zveřejnit: poslední krok zůstává na vás, takže nic nevidí zákazníci bez vaší kontroly.

Kdo to může spustit

Karta „Koncový bod" říká, kdo může prvek používat. Výchozí nastavení jsou členové vaší firmy. Druhé nastavení ho otevírá vnějším osobám, ale pouze v chatu, kde je přítomen také někdo z vaší firmy: přesně ten případ, pro který je určen, kdy zákazník objednává od vás. Když vaše firma chat opustí, oprávnění samo skončí.

Produkty z vlastního katalogu

Jakmile nahrajete katalog produktů, generátor nabídne blok výběru produktu. Nejsou k dispozici žádné možnosti úprav: seznamem je váš katalog. Objednávající osoba jej vyhledá, uvidí obrázek, název a číslo položky a váš backend obdrží číslo položky. Skava zamítne číslo, které není ve vašem katalogu. Pro množství umístěte vedle něj běžné pole pro čísla.

Kartu si definujte sami

Váš backend rozhoduje, co karta obsahuje. Skava kontroluje pouze tvar, velikost a bezpečnost, nikoliv význam: nezná ani stavy objednávky, ani názvy polí. Chcete-li to provést, odpovězte objektem card:

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

• v musí být celé číslo 1. Bez něj se odpověď nepovažuje za kartu a použije se mapování odpovědí nakonfigurované v prvku.
• state je pouze barva a ikona: ok, pending, warn nebo error. Všechny významové informace se vkládají do status_text jako volný text.
• fields je seznam štítků a hodnot, maximálně 20 položek. Příliš dlouhé hodnoty se zkrátí, nikoliv zamítnou, takže objednávka nikdy nez selže kvůli detailu.

Vstupy uživatele patří serveru: zůstanou nezměněny, bez ohledu na to, co váš backend odešle. Jsou záznamem v chatu toho, co bylo skutečně odesláno.

Nahlášení stavu později

Když prvek běží, Skava odešle dvě další hodnoty: callback_url a callback_token. Později tam nahlašte nový stav a v chatu se objeví nová karta, i na telefonu, zatímco ji někdo sleduje. Předchozí zůstane, takže je čitelné, který stav byl nahlášen. Odešlete stejný objekt card jako výše, pomocí POST s hlavičkou Authorization: Bearer <callback_token>. Vedle karty jdou tři volitelné hodnoty:

• seq: váš vlastní čítač. Zpráva s menší nebo stejnou hodnotou se zahodí, takže se dvě zprávy nemohou předjet.
• final: ukončuje interakci. Token se stává neplatným a karta je finální.
• notify: nastavte na false, pokud chcete kartu odeslat tiše, bez počtu nepřečtených zpráv a bez upozornění. Vhodné pro mezikroky, které by neměly nikoho budítkem. Bez tohoto parametru je karta naprosto běžnou zprávou.

Interakce může odeslat maximálně 50 karet. Stejná zpráva dvakrát nevytvoří druhou kartu.

Skava odpovídá 200 a seznamem hints, pokud se něco zkrátilo nebo vyřadilo, a 422, pokud byla karta nepoužitelná. Interakce přijímá zprávy po dobu 90 dnů.

Karty jsou odesílány systémem Skava, nikoliv osobou, která spustila prvek, ani účtem vaší vlastní firmy. V nadpisu karty je uvedeno, který systém ji vytvořil.

Úplný příklad ke zkopírování se nachází v repozitáři v adresáři example_order_server/ a běží na adrese api.skava.io.

Související

Místo toho chcete vytvořit vyplnitelnou šablonu dokumentu? Podívejte se na Vlastní prvky: Dokumenty.

Často kladené dotazy