Ako nastaviť a využívať rozhranie API Dotykačky

API je dohodnutý spôsob, ktorým si Dotykačka vymieňa údaje s inými programami. Vďaka nemu môže e-shop odpísať predaný tovar zo skladu pokladne, účtovný program si stiahne tržby, rezervačný systém založí rezerváciu stola a aplikácia, ako je Dotyman, si načíta produkty a stav skladov – bez toho, aby ste čokoľvek prepisovali ručne.

API nie je prepínač, ktorý v pokladni zapnete, a potom to funguje. Je to nástroj pre programátorov. Ako majiteľ prevádzky sa s ním stretnete v dvoch situáciách:

• Pripájate hotovú aplikáciu, ktorá API Dotykačky už používa. Vtedy jej len povolíte prístup – zvládnete to za pár minút a bez programátora.
• Chcete vlastné prepojenie, napríklad s interným systémom. Vtedy potrebujete programátora a prístup k API si musíte vyžiadať od Dotykačky.

Čo budete potrebovať

• Licenciu Dotykačka NAPLNO alebo NEOBMEDZENE. Verzia JEDNODUCHO API neobsahuje.
• Pri vlastnom prepojení programátora a prístupové údaje od Dotykačky (pozri nižšie).

Potrebujete API vôbec?

Skôr než začnete niečo programovať, overte si, či na váš problém neexistuje hotové riešenie:

• Hotové integrácie Dotykačky. Na Slovensku sú to napríklad e-shopy Shoptet a WooCommerce, objednávkové služby Bolt a Wolt alebo platenie od stola cez Qerko. Väčšina sa zapína sprievodcom vo Vzdialenej správe.
• Export zo Vzdialenej správy. Ak potrebujete údaje raz za mesiac do tabuľky alebo pre účtovníka, často stačí export do CSV alebo Excelu. Príklad nájdete v návode Export skladových pohybov.
• Aplikácie tretích strán, ktoré už s Dotykačkou spolupracujú. Stačí im povoliť prístup.

Vlastné prepojenie cez API sa oplatí, keď sa údaje musia prenášať pravidelne a automaticky, a hotové riešenie neexistuje.

Povolenie prístupu hotovej aplikácii

Keď aplikácia potrebuje prístup k vašej Dotykačke, postup je takmer vždy rovnaký:

1. V aplikácii kliknete na tlačidlo typu Pripojiť Dotykačku.
2. Otvorí sa prihlásenie na stránke Dotykačky (nie v aplikácii). Prihlásite sa svojím účtom do Vzdialenej správy.
3. Vyberiete cloud, ku ktorému má aplikácia získať prístup, a prístup potvrdíte.
4. Dotykačka vás vráti späť do aplikácie a tá je pripojená.

Heslo od Dotykačky aplikácii nikdy nedávate. Dotykačka jej vydá vlastný prístupový kľúč (token), ktorý môžete kedykoľvek zrušiť. Ak by od vás niekto chcel meno a heslo do Vzdialenej správy, aby „to prepojil“, nepristupujte na to.

Prístup je k celému cloudu

Pripojená aplikácia získa prístup k celému cloudu – ku všetkým prevádzkam, produktom, skladom, predajom aj zákazníkom, na čítanie aj na zápis. Obmedziť ho len na časť údajov sa nedá. Povoľujte ho preto len aplikáciám a firmám, ktorým dôverujete.

Takto sa k Dotykačke pripája aj Dotyman, podrobne to popisuje návod Pripojenie Dotykačky k Dotymanu.

Kontrola a zrušenie prístupu

Všetky aplikácie, ktoré majú prístup k vášmu cloudu, nájdete vo Vzdialenej správe:

1. Prihláste sa do Vzdialenej správy a vyberte cloud.
2. Na hornej lište kliknite na ikonu cloudu a zvoľte Nastavenie cloudu → Správa integrácií.
3. Rozbaľte integráciu – uvidíte jej token a často aj kontakt na podporu dodávateľa aplikácie.
4. Ak aplikáciu už nepoužívate, integráciu označte a zmažte.

Sem príde snímka obrazovky: Nastavenie cloudu → Správa integrácií.

Po zmazaní tokenu aplikácia okamžite prestane s Dotykačkou komunikovať. Ak ju ešte potrebujete, budete ju musieť pripojiť znova.

Upratujte raz za čas

Pozrite sa do Správy integrácií aspoň raz za pol roka a vždy, keď končíte spoluprácu s nejakou firmou alebo programátorom. Zabudnutý prístup je zbytočné riziko.

Vlastné prepojenie krok za krokom

Pri vlastnom prepojení vystupujú dve veci, ktoré si ľudia často pletú:

• Prístup pre aplikáciu (Client ID a Client Secret) – identifikuje váš program voči Dotykačke. Vydáva ho Dotykačka na žiadosť a je rovnaký pre všetky cloudy, ku ktorým sa program pripojí.
• Povolenie pre konkrétny cloud (token) – vznikne tak, ako je popísané vyššie: majiteľ cloudu sa prihlási a prístup potvrdí.

1. Požiadajte o prístup k API

Vyplňte registračný formulár klientskej aplikácie, odkaz je v kapitole Ako začať s API? oficiálneho manuálu. Dotykačka sa do 10 pracovných dní ozve, prípadne sa dopýta, na čo prepojenie potrebujete, a pošle Client ID a Client Secret.

Ak má aplikácia názov vo viacerých jazykoch, uveďte ho vo formulári pre každý jazyk, napríklad sk:Názov a en:Name.

2. Testujte na testovacom cloude

Spolu s prístupom dostanete testovací licenčný kľúč. Aktivujte ním pokladničnú aplikáciu Dotykačka na zariadení, ktoré nepoužívate na predaj, a vznikne samostatný testovací cloud. Programátor tak skúša na vymyslených dátach, nie na vašej ostrej pokladni.

3. Pripojte program k cloudu

Program sa k cloudu pripojí rovnako ako hotová aplikácia: otvorí prihlásenie na stránke Dotykačky, vy vyberiete cloud a prístup potvrdíte. Program dostane dlhodobý token, ktorý si musí bezpečne uložiť, a z neho si priebežne vyrába krátkodobé prístupové tokeny (platia približne hodinu).

4. Programujte podľa dokumentácie

Úplná dokumentácia API je v angličtine na docs.api.dotypos.com. Nájdete tam aj kolekciu pre Postman na rýchle vyskúšanie a zoznam knižníc tretích strán. Či API práve funguje, ukazuje status.dotykacka.cz.

Čo cez API ide a čo nie

Čítať sa dajú takmer všetky údaje: prevádzky, produkty a kategórie, receptúry, sklady a aktuálny stav skladu, objednávky a predané položky, platby, zákazníci, zamestnanci, stoly, dodávatelia, rezervácie či dochádzka.

Zapisovať sa dá napríklad:

• zákazníci vrátane kreditu a zákazníckych zliav,
• produkty, kategórie, varianty a receptúry,
• zamestnanci a dodávatelia,
• rezervácie stolov,
• naskladnenie, presun medzi skladmi, výdaj zo skladu a inventúra,
• elektronické dodacie listy – tie potom potvrdzuje človek v aplikácii Sklad.

Účty na pokladni (otvoriť účet na stôl, pridať položky, vystaviť a zaplatiť) sa cez API zadávajú ako pokyny pre pokladňu (v dokumentácii POS Actions). Vykoná ich priamo pokladňa danej prevádzky, takže musí byť zapnutá, online a otvorená. Na Slovensku sa doklad cez API vždy vystaví a zaplatí naraz a musí sa vytlačiť na pokladni alebo poslať e-mailom – to vyžaduje eKasa.

Nedá sa vytvoriť prevádzka, stôl, chod ani spôsob platby, zadať vklad alebo výber hotovosti, otvoriť či uzavrieť pokladňu ani zmeniť už vystavený doklad. To ostáva na pokladni a vo Vzdialenej správe.

História skladových pohybov

API vráti aktuálny stav skladu, ale nie úplnú históriu pohybov za mesiac. Preto Dotyman pre report SBL používa export Skladové pohyby zo Vzdialenej správy a stav skladu si sám ukladá každý deň pred polnocou a po nej.

Webhooky: keď má Dotykačka dať vedieť sama

Bežne sa program pýta Dotykačky („čo je nové?“). Webhook funguje opačne: pri zmene pošle Dotykačka správu na adresu, ktorú určíte. Spravujú sa vo Vzdialenej správe v Nastavenie cloudu → Správa webhookov a dajú sa nastaviť pre:

• skladové pohyby na konkrétnom sklade,
• produkty,
• pohyby bodov na zákazníckom účte,
• realizované predaje,
• rezervácie.

Webhook môže byť len „ping“ (Dotykačka zavolá adresu bez údajov a program si zmeny dočíta sám), alebo rovno poslať zmenené záznamy.

Webhooky Shoptetu nemeňte

Ak máte Dotykačku prepojenú s e-shopom Shoptet, v Správe webhookov uvidíte webhooky, ktoré vytvoril Shoptet. Neupravujte ich ani nemažte, inak prestane fungovať synchronizácia skladu s e-shopom.

Tipy z praxe

• Najprv si napíšte, čo presne má prepojenie robiť. Ktoré údaje, ktorým smerom, ako často a čo sa má stať pri chybe. Programátor vám potom vie odhadnúť cenu a aj Dotykačke vo formulári ľahšie vysvetlíte, na čo API potrebujete.
• Nikdy neposielajte prístupové údaje e-mailom ani chatom. Client Secret a tokeny patria len do bezpečne uloženej konfigurácie programu. Ak unikli, zmažte integráciu v Správe integrácií a požiadajte Dotykačku o nový Secret.
• Programátorovi nedávajte prístup do svojej Vzdialenej správy. Na vývoj mu stačí testovací cloud, k ostrému cloudu pripojíte hotový program sami.
• Počítajte s vypnutou pokladňou. Pokyny pre pokladňu (účty, doklady) zlyhajú, keď je pokladňa offline. Údaje z cloudu (produkty, predaje, sklad) sú dostupné aj vtedy.
• Dávajte si pozor na hodiny. Pri pripájaní sa overuje presný čas a ak sa hodiny na serveri programu rozchádzajú o viac ako minútu, Dotykačka pripojenie odmietne s hláškou o vypršaní spojenia.

Pre programátora

Niekoľko vecí, ktoré v dokumentácii ľahko prehliadnete:

• Čísla prichádzajú ako text ("id": "123456789"), pretože identifikátory sú veľmi dlhé. Odpovede POS Actions ich však posielajú ako čísla – parser musí zvládnuť oboje.
• DPH je násobiteľ, nie percento ("vat": "1.23"), a ceny chodia bez DPH s mnohými desatinnými miestami.
• Jednotky sú názvy (Piece, Liter, Kilogram). Množstvá v receptúrach sú v jednotke receptúry (Deciliter, Gram), nie v jednotke suroviny.
• Prázdny výsledok vráti 404, ak neposielate hlavičku Allow-Version: BC1. S ňou dostanete prázdny zoznam.
• Stránkovanie má najviac 100 záznamov na stránku. Pri objednávkach API nevracia celkový počet, takže čítajte, kým nepríde neúplná stránka.
• Úprava záznamu vyžaduje ETag z predchádzajúceho načítania (hlavička If-Match). Bez neho API zmenu odmietne.

Viac v oficiálnom manuáli

• API Dotykačka a Ako začať s API?
• Správa integrácií
• Správa webhookov
• Služby a rozšírenia – hotové integrácie
• Verzie Dotykačky – čo obsahuje ktorá licencia