Pro integrace Dativery s účetním programem POHODA budete potřeba Dativery Agent. Co je Dativery Agent a proč jej potřebujete?

Některé z firemních aplikací nejsou cloudové, neběží v prohlížeči, ale jsou tradiční, desktopové. Zákazník si je instaluje na svůj počítač nebo lokální server. Pro komunikaci lokálně instalované aplikace s aplikací cloudovou je nutné vytvořit jejich síťové propojení.

Potřeba propojení se obvykle řeší najmutím IT správce, který zpřístupní aplikaci do Internetu. K tomu potřebujete nastavit firewall a také vlastnit veřejnou IP adresu. Abyste navíc zajistili zvýšenou bezpečnost, omezíte přístup podle IP adresy cloudové služby nebo nakonfigurujete soukromou virtuální síť (VPN). U cloudových služeb se ovšem IP adresy často mění a provozovat velké množství VPN uzlů je také problematické a především drahé. A většina cloudových služeb proto VPN vůbec neumožňuje.

Proto jsme vytvořili aplikaci Dativery Agent. Nainstalujete jej na počítač nebo server, kde běží vaše aplikace, a on ji umožní bezpečně a hlavně jednoduše zpřístupnit. Díky podpoře pro konkrétní aplikace zvládne instalaci opravdu každý. Například u POHODY si zobrazíte seznam účtovaných firem a kliknutím vytvoříte spojení (pošlete pozvánku).

Stáhnout Dativery Agent

Technický popis

Pokud vás zajímají technické detaily, čtěte dál. Co tedy Dativery Agent dělá? Po instalaci Dativery Agenta na počítač se spustí jako služba na pozadí a trvale naváže spojení s naším serverem link.dativery.com pomocí WebSocketu (HTTPS). Vygeneruje si autorizační údaje, kterými se ověřuje proti této službě, a tato služba se ověřuje platným SSL certifikátem.

Když spustíte desktopovou aplikaci Dativery Agentu, vidíte jeho stav (i zda se může připojit k našemu serveru) a můžete jej konfigurovat. V rozhraní nechybí tlačítko “Pozastavit”, které informuje náš server, že si dočasně nepřejete komunikovat. Server link.dativery.com při pozastavení vůbec nepřeposílá žádné požadavky. Pozastavení Dativery Agentu je vhodné například ve chvíli, kdy zálohujete nebo aktualizujete propojenou aplikaci (např. Pohodu).

Dativery Agent pro Windows

Agent díky pluginům zobrazí seznam instalovaných a podporovaných aplikací. Umožňuje také zaslat pozvánku k používání dalšímu uživateli. Pozvánka po akceptování poskytne autorizační údaje. Tyto údaje mají dvě části. První umožní přeposlat požadavek z link.dativery.com na Agenta, druhá část umožní z Agenta přístup do konkrétní účtované firmy.

Komunikační protokol

Jak vypadá samostatná komunikace? Místo přímé adresy serveru pošlete požadavek na link.dativery.com. 

POST http://localhost:444/xml HTTP/1.1
STW-Authorization: Basic QDo=
Content-Type: text/xml

Požadavek by tedy vypadal takto:

POST https://link.dativery.com/xml HTTP/1.1
X-Link-Authorization: Basic NGU1YTQwMzctNGIyMS00YTYzLTkwODQtNjAzOTUxYjY1OTdjOmVjN2MyMjVkLTBkMWU=
STW-Authorization: Basic QDo=
Content-Type: text/xml

Struktura X-Link-Authorization je stejná jako u běžné autorizace. První část (uživatelské jméno) umožní přístup přes Internet do Dativery Agentu (první úroveň autorizace). Druhá část pak identifikuje konkrétní účtovanou organizaci.

Díky této dvojité autorizaci je zabezpečený jak samotný počítač s Dativery Agentem, tak i samotné organizace. Oproti VPN je tak zajištěna vyšší bezpečnost. Především v případě, že jste účetní firma a chcete jednomu ze svých klientů umožnit přístup k jeho účtovaným datům. Agent zajistí, že se nedostane k datům jiných zákazníků, i když byste používali slabá hesla.

Jaké bezpečnostní prvky celé řešení obsahuje?

  • HTTPS s platným certifikátem pro link.dativery.com.
  • Autorizace agenta vůči link serveru. Tím je zajištěna možnost, že je možné libovolně měnit IP adresy přes kterou Agent přistupuje.
  • Bez autorizačních údajů není útočník vůbec schopen komunikovat s Agentem.
  • Dvojitá autorizace. Agent bez správné autorizace nedovolí komunikovat s účtovanými firmami.
  • Rate limiting – implementovali jsme přiškrcování. Jeden uživatel tak nemůže provádět příliš mnoho požadavků a tím ohrožovat služby.
  • Vysoká dostupnost díky Elastic LoadBalanceru od AWS.
  • Určitá míra odolnosti vůči DoS útokům.

Do Agenta připravujeme i podporu dalších aplikací. Má i možnost přímé integrace do cílové aplikace. Ale to je vhodné pouze pro výrobce těchto aplikací.

Akceptace pozvánky

Pro bezpečné zpracování požadavku vám Dativery Agent neposkytne přímo autorizační údaje, ale pozvánku. V Dativery Agentu vytvoříte pozvánku a z ní pak získáte autorizační údaje.

Příklad pozvánky:

8d7333831d3a32132025f31349b6d151|d4ec8d75e1799beaf5a782dc4732066c0489591db2007b7

Pozvánka se skládá ze dvou částí, oddělených znakem |. Má tedy strukturu {serverId}|{invitationId}. {serverId} reprezentuje daného agenta, {invitationId} pak pozvánku.

Získání autorizačních údajů z pozvánky:

GET https://link.dativery.com/@/invitation/{serverId}/{invitationId}/prepare/ HTTP/1.1

Odpověď:

{
   "status": "ok",
   "invitation": {
        "serverId": "8d7333831d3a32",
        "agendaId": "d4ec8d75e1799b",
        "accessSecret": "132025f31349b6",
        "agendaSecret": "f31349b6d151d1"
   }
}

Ze získaných dat lze poskládat X-Link-Authorization stejným způsobem, jako se sestavuje HTTP hlavička Authorization.

Jméno: {serverId}|{agendaId}
Heslo: {accessSercret}|{agendaSecret}

X-Link-Authorization: “Basic ” + Buffer.from(“{serverId}|{agendaId}:{accessSercret}|{agendaSecret}”, “utf-8”).toString(“base64”)

Pokud chcete pozvánky vyčíst, aby již nebyla znovu použitelná.

GET https://link.dativery.com/@/invitation/{serverId}/{invitationId}/accept/ HTTP/1.1

Způsoby komunikace s Pohodou

Pro komunikaci s Pohodou můžete použít různé způsoby přístupu k API:

XML import (/xml)

Dativery agent zavolá pohoda.exe /xml soubor.xml a odpověď pošle zpátky. Toto je jediný doporučený způsob zápisu dokladů do Pohody.

Umí pracovat s přepínáním období takto:

/xml?periodDate=2023-01-01

Aby přepínání období fungovalo správně, musí být alespoň jednou přepnuté manuálně v aplikaci Pohoda.

SQL přístup (/api/v1/TABULKA)

XML importy a exporty od Pohody mají velké množství omezení a je také dost pomalé (6 vteřin). Proto je dost často nutné data načítat přímo z aplikace. Někdy je také nutné importovaný doklad následně modifikovat. Tento přístup ignoruje nastavená přístupová práva v Pohodě.

Tento přístup podporuje jak klasickou pohodu (MDB), SQL i E1.

GET /api/v1/OBJ?filter=CisObj=’1′

Podporované parametry:

  • filter – umí filtrovat. Dochází k automatické konverzi podle typu (např. datum se v SQL zapisuje jinak než MDB). Nejedná se o výřez SQL, ale vlastní dotazovací jazyk, který umí AND, OR, () a většinu operátorů.
  • columns – umí omezit počet načítaných sloupečků. Pokud načítáte větší množství, je lepší to omezit – nenarazíte tak na paměťové limity.
  • limit – umožňuje omezit počet vrácených záznamů
  • order – umožňuje určit řazení

Formát výstupu se určuje pomocí hlavičky Accept-encoding a podporuje tyto:

  • application/xml (výchozí, protože celá komunikace s Pohodou je většinou XML)
  • application/json

Seznam tabulek v Pohodě

Nastavení (/settings)

Načtení nastavení z Pohody. Pokud potřebujete například zjistit primární měnu jednotky nebo účtování kurzových rozdílů, můžete načíst nastavení API.

Já bych ale raději plugin do cílové aplikace

Jedním z častých dotazů je, proč používáme Agenta a nenapíšeme doplněk přímo pro cílovou aplikaci. Většina aplikací doplňky vůbec nepodporuje.

Některé aplikace mají podporu pro propojení typu “Obecný internetový obchod”. Nevýhodou těchto řešení je, že obvykle mají zásadně omezený způsob komunikace a především strukturu dat. Omezené propojení silně omezuje i možnosti propojení internetového obchodu. A v případě, že nepropojujete právě internetový obchod, je použití takového propojení už zcela nereálné. 

Proto jsme investovali nemalé úsilí do vytvoření Dativery Agenta. Ať slouží 🙂 

Blog, Novinky