Skava Skava / Wiki

Vlastní prvky: API

Rozhraní API je formulář, jehož vyplněné hodnoty Skava odešle jako JSON na adresu, kterou zadáte (váš backend). Tímto způsobem můžete Skavu bezpečně propojit se svými vlastními systémy.

i

Rozhraní API spravujete ve Webaplikaci v sekci Vlastní prvky → přepínač Rozhraní API. Vytváření a úpravy jsou vyhrazeny administrátorům firmy; zveřejněná rozhraní pak mohou spouštět všichni členové firmy.

Nastavení rozhraní API

Rozhraní se skládá ze vstupních polí (tvoří JSON), cílové adresy a autentizace.

  1. Vytvoření polí: Každé pole má svůj JSON klíč. Vpravo vidíte živý náhled JSON, který je odeslán do vašeho backendu přesně v tomto tvaru.
  2. Adresa (URL): adresa https:// vašeho backendu. Povoleny jsou pouze adresy HTTPS a veřejně přístupné adresy (viz Bezpečnost níže).
  3. Metoda: POST (výchozí), PUT, PATCH nebo GET. Při použití GET se hodnoty přidávají jako parametry dotazu místo odeslání v těle požadavku.
  4. Autentizace: Nastavte název hlavičky (např. Authorization) a předponu hodnoty (např. Bearer ), poté uložte token. Volitelně nastavte datum vypršení platnosti.
  5. Polí odpovědi (volitelné): Definujte pomocí cesty, 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.
Skava webapp: Záložka Fields rozhraní API. Nahoře automaticky zahrnuté kontextové hodnoty (jméno uživatele, firma, projekt …), níže vlastní pole s klíčem JSON, vpravo náhled formuláře a živý náhled JSON.
Záložka Fields: každé pole dostane klíč JSON. Nahoře jsou automaticky zahrnuty kontextové hodnoty, jako jsou uživatel, firma a název projektu. Vpravo vidíte formulář a živý JSON: přesně to, co se odešle do vašeho backendu.
Skava webapp: Záložka Endpoint rozhraní API s poli pro URL, metodu POST, timeout, hlavičku auth, předponu hodnoty Bearer a vstup pro zašifrovaný token.
Záložka Endpoint: cílová adresa (pouze HTTPS), metoda, timeout a hlavička auth včetně předpony hodnoty. Token je uložen zašifrovaně a nikdy se nepředává klientům.
Skava webová aplikace: Záložka Náhled rozhraní API. Nastaveno je pole odpovědi s klíčem JSON Success, vpravo je náhled toho, jak bude výsledek vypadat v chatu.
Záložka Náhled (volitelné): pomocí cesty definujete, které hodnoty z odpovědi backendu se zobrazí. Vpravo Skava z nich sestaví kartu s výsledkem, přesně tak, jak se později objeví v chatu.

Bezpečně uložit token

Token je uložen šifrovaně a nikdy se nevrací klientům: aplikace zobrazuje pouze to, zda je token nastaven a kdy vyprší. Při odesílání ho Skava serverově připojí do nastaveného hlavičkového pole. Pokud nastavíte datum vypršení, Skava po jeho uplynutí zavolání zamítne a požádá vás o obnovu tokenu.

Testování: Ping a Testovací požadavek

  • Ping: lehká kontrola dostupnosti. Zkontroluje pouze zda se vaše adresa odpovídá a při tom neodesílá token ani formulářová data. Zobrazuje dostupnost, stav a čas odezvy. Ideální jako první krok.
  • Testovací požadavek: skutečná zkouška: odešle ukázková data včetně tokenu na vaši adresu a zobrazí kompletní odpověď i extrahovaná pole odpovědi.

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

Skava webová aplikace: záložka Test rozhraní API s tlačítky Ping a Testovací požadavek, výsledkem Stav 200 OK, časem odezvy a kompletní JSON odpovědí z backendu.
Záložka Test: Ping a Testovací požadavek vedle sebe. Zde se stavem 200, časem odezvy a kompletní odpovědí backendu ve formátu JSON.

Návrh a vydání

Každé rozhraní začíná jako návrh a lze ho volně upravovat. Jakmile je vše připravené, vydáte ho pomocí tlačítka Vydát.

!

Po vydání jsou cílová adresa, metoda, pole, hlavička pro ověření a časový limit pevně stanoveny. Je to záměrné: nikdo nemůže tichomile změnit, kam data putují. Přesně tři věci zůstávají měnitelné, protože je provoz potřebuje: token a jeho platnost (aby bylo možné nahradit vypršlý nebo spotřebovaný token) a publikum, tedy zda ho může spustit v chatu jen váš tým nebo i partnerské firmy. Pro jakékoli další změny vytvoříte novou verzi.

Bezpečnost

i

Aby se zabránilo zneužití rozhraní, platí přísná pravidla: povoleny jsou pouze HTTPS adresy a adresa musí ukazovat na veřejnou cílovou adresu: vnitřní adresy (např. localhost, soukromé sítě nebo cloudová metadata) jsou zamítnuty. Skava toto kontroluje při každém volání, připojuje se přesně na ověřenou adresu, neposleduje přesměrování a omezuje časový limit a velikost odpovědi.

Jak tým využívá zveřejněné rozhraní

Jakmile je rozhraní zveřejněno, mohou jej všichni členové firmy spustit přímo z chatu, bez nutnosti editace. Neexistuje společné vstupní pole ani mezipokudí: každý zveřejněný prvek se nachází v menu Plus pod svým názvem, s logem firmy, která jej nabízí.

  1. V chatu klepněte na Plus dole a poté na požadovaný prvek, například Požadavek na materiál.
  2. Vyplňte formulář a klepněte na Odeslat.
  3. Výsledek se zobrazí jako karta v chatu, viditelná pro všechny účastníky konverzace.
Webová aplikace Skava: vyplnitelný formulář akce API Objednání materiálu s poli číslo artiklu, popis, množství, jednotka, požadovaný datum dodání a poznámka, včetně poznámky o automaticky zahrnutých hodnotách.
Krok 3: Vyplňte formulář. Poznámka dole ukazuje, které hodnoty jsou zahrnuty automaticky.
Webová aplikace Skava: karta výsledku akce API Objednání materiálu v chatu se stavem 200, zadanými hodnotami a odpovědí backendu (číslo objednávky, stav, datum dodání) včetně rozbalitelných surových dat.
Krok 4: Karta výsledku v chatu se vstupy a odpovědí vašeho backendu.

Nechte AI vytvořit 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 adresou pro doručení“. Na základě toho vytvoří koncept, později může pole upravovat jedno po druhém a zná váš nahraný katalog produktů: u objednávek navrhne výběr produktu místo textového pole pro číslo artiklu.

Co může nastavit také: koncový bod a metodu i publikum („pouze členové firmy“ nebo „také vnější osoby ve stejném chatu“). U publika se nejprve zeptá, místo aby to rovnou nastavil, protože tím rozhoduje, kdo může spouštět akce zvenčí.

Co explicitně nedotýká: 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áváte ho sami v editoru, jinak žádný volání neodejde. A nemůže publikovat: poslední krok zůstává na vás, takže se nic nezobrazí zákazníkům bez kontroly.

Kdo ho může spouštět

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

Produkty z vašeho vlastního katalogu

Jakmile nahrajete katalog položek, nabídně stavitel blok výběr produktu. Žádné možnosti k údržbě: seznamem je váš katalog. Osoba, která objednává, v něm hledá, vidí obrázek, název a číslo položky a váš backend přijme číslo položky. Skava zamítne číslo, které ve vašem katalogu není. Pro množství umístěte vedle něj běžné číselné pole.

Kartu si definujte sami

Váš backend rozhoduje, co karta říká. Skava kontroluje pouze tvar, velikost a bezpečnost, nikdy význam: nezná stavy objednávek ani názvy polí. K tomu 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ěď nepočítá jako karta a použije se mapování odpovědí nakonfigurované v prvku.
  • state je pouze barva a ikona: ok, pending, warn nebo error. Vše, co nese význam, patří do status_text jako volný text.
  • fields je seznam popisků a hodnot, maximálně 20 položek. Příliš dlouhé hodnoty se zkrátí, místo aby se zamítly, takže objednávka nikdy nezavrhne kvůli detailu.

Vstupy uživatele patří serveru: zůstávají nedotčené bez ohledu na to, co vaše backend posílá. Jsou záznamem v chatu o tom, co bylo skutečně odesláno.

Nahlášení stavu později

Když se element spustí, Skava pošle dvě další hodnoty: callback_url a callback_token. Později tam nahlaste nový stav a v chatu se objeví nová karta, i na telefonu, zatímco někdo dívá. Předchozí zůstává, takže je čitelné, který stav byl nahlášen. Pošlete stejný objekt card jako výše, přes POST s hlavičkou Authorization: Bearer <callback_token>. Tři volitelné hodnoty jdou vedle karty:

  • seq: vlastní číselník. Zpráva s menší nebo stejnou hodnotou se zahodí, takže se dvě zprávy nemohou předjet.
  • final: uzavře interakci. Token se stane neplatným a karta je finální.
  • notify: nastavte na false, pokud chcete kartu odeslat potichu, bez počtu nepřečtených zpráv a bez notifikace. Vhodné pro mezistavy, které by neměly nikoho budit. Bez tohoto parametru je karta běžnou zprávou.

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

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

Karty odesílá systémový odesílatel Skavy, nikoli osoba, která element spustila, ani účet vaší firmy. Kdo z jakého systému píše, je uvedeno v názvu karty.

Úplný příklad ke zkopírování najdete v repozitáři pod example_order_server/ a běží na api.skava.io.

Související

Chcete spíše vytvořit vyplnitelnou šablonu dokumentu? Podívejte se na Vlastní prvky: Dokumenty.

Časté dotazy

Co je rozhraní API v Skava?

Formulář, jehož vyplněné hodnoty Skava odešle jako JSON na adresu, kterou zadáte (váš backend): praktické pro propojení Skavy s vašimi vlastními systémy.

Kdo smí vytvářet a spouštět rozhraní API?

Vytváření a úpravy jsou vyhrazeny administrátorům firmy. Zveřejněné rozhraní pak mohou spouštět všichni členové firmy.

Jaký je rozdíl mezi „Ping“ a „Test Request“?

Ping pouze ověří, zda je adresa dosažitelná: bez tokenu a bez dat. Test Request odešle ukázková data včetně tokenu a zobrazí kompletní odpověď.

Je můj API token bezpečný?

Ano. Token je uložen zašifrovaně a nikdy se nepředává klientům. Aplikace zobrazuje pouze, zda je token nastaven, a kdy vyprší.

Které adresy jsou povoleny jako koncové body?

Pouze veřejně přístupné adresy https://. Interní cíle, jako je localhost, soukromé sítě nebo cloudová metadata, se zamítají: tím se chrání rozhraní před zneužitím.

Proč už nemohu změnit zveřejněné rozhraní?

Cílová adresa, metoda, pole a hlavička pro ověření jsou po zveřejnění pevně dané, aby nikdo nemohl tichomile změnit, kam data putují. Token, jeho platnost a cílové publikum (pouze vlastní tým nebo i partnerské firmy) zůstávají upravitelné; právě takto nahradíte vypršlý token. Pro ostatní změny vytvořte novou verzi.