Pohoda API: XML, mServer a SQL v přehledu pro vývojáře

Když se řekne „Pohoda API“, většinou se tím myslí XML rozhraní. Výrobce, společnost STORMWARE, ho sám označuje jako API a přes něj do Pohody chodí objednávky z e-shopů, doklady z pokladen i data z dalších aplikací. Kdo potřebuje data jen číst, má u řad POHODA SQL a E1 ještě druhou cestu: přímo z databáze. V tomhle přehledu najdete, jak obě cesty fungují, kdy kterou použít a na co si dát pozor.

Krátká odpověď

Tři cesty k datům

• XML import a exportPřipravíte XML soubor podle schématu a Pohoda ho zpracuje. Spustit to jde ručně v programu (Soubor → Datová komunikace → XML import/export) nebo automaticky přes příkazovou řádku. Hodí se pro dávky, například noční přenos dokladů.
• POHODA mServerStejné XML, jen posílané přes HTTP nebo HTTPS. Vaše aplikace pošle požadavek a hned dostane odpověď. Na tom stojí většina e-shopových konektorů.
• Přímé čtení z SQLJen u řad POHODA SQL a E1. Data čtete vyhrazeným účtem s právy jen pro čtení, bez fronty a bez zátěže programu. Na přehledy a reporty ideální, na zápis ne.

Jak vypadá XML komunikace

Každý XML soubor pro Pohodu má stejnou obálku. Kořenový element dataPack obsahuje jednotlivé položky dataPackItem a v každé je jeden doklad k importu nebo jeden požadavek na export. Jeden dataPack může míchat import i export. Strukturu popisují XSD schémata: Pohoda má pro každou agendu vlastní schéma a aktuální je verze 2.x. Celý balík schémat i s popisem si stáhnete na webu Stormware. Vývojářskou dokumentaci, tedy popis struktury, podporovaná data a u exportu i filtrování a stránkování, má výrobce na portálu api.stormware.cz.

Na každý požadavek dostanete odpověď. U každého dokladu v ní najdete, jestli prošel, a pokud ne, číslo chyby, popis a cestu XPath k problematickému elementu. Pohoda umí hlídat i duplicity: když zapnete kontrolu, stejný doklad se podle identifikátorů v obálce podruhé neimportuje.

Uživatel, pod kterým XML zpracováváte, musí mít v Pohodě práva. Pro import potřebuje zápis do příslušné agendy, pro export aspoň čtení. Chybějící práva jsou jedna z nejčastějších příčin, proč import „nic neudělá“.

Které agendy jdou přes XML

Seznam je široký. Importovat jde mimo jiné faktury, objednávky, nabídky, poptávky, příjemky, výdejky, převodky, prodejky, pokladní doklady, bankovní doklady, zakázky a výrobu. Ze seznamů pak adresy, zásoby, sklady, číselné řady, bankovní účty a kategorie internetového obchodu. Export umí navíc třeba saldo, účetní deník, střediska, prodejní ceny nebo seznam účetních jednotek. Přesný a aktuální přehled drží Stormware v seznamu dokladů pro import a pro export, i s ukázkovými soubory.

mServer v kostce

mServer je součást programu POHODA. Naslouchá na zvoleném portu a XML přijímá metodou POST s typem text/xml. Přihlašuje se hlavičkou STW-Authorization s údaji uživatele Pohody a funguje přes HTTP i HTTPS. Požadavky zpracovává jeden po druhém v pořadí, jak přišly, takže velké dávky je dobré rozložit. Stav zjistíte jednoduchým požadavkem na adresu /status.

Každá konfigurace mServeru patří k jedné účetní jednotce, tedy k jedné firmě v jednom účetním roce. Běžící mServer si navíc vyhradí celou instanci programu a výrobce ho doporučuje provozovat na serverovém systému ve vnitřní síti. Provozu, nákladům a praktickým tipům se podrobně věnuje článek mServer v Pohodě.

Přímé čtení z databáze

Řady POHODA SQL a E1 ukládají data do Microsoft SQL Serveru. Pro čtení tak nepotřebujete ani mServer, ani XML. Stačí vyhrazený databázový účet s právy jen pro čtení a zabezpečená cesta k serveru. Čtení jde mimo program a odpověď přijde hned. Základní řada Pohody používá souborovou databázi, takže tam tahle cesta nejde.

Přesně tak funguje naše POHODA MCP: AI asistent čte data přímo z SQL databáze a mServer ani placené doplňky nepotřebuje. Zápisové akce ve vyšším tarifu pak jdou přes XML rozhraní, stejně jako u každé jiné integrace.

Na co si dát pozor

1. Nový účetní rok je nová účetní jednotka. Konfiguraci mServeru i XML importu je potřeba na začátku roku přepnout na novou jednotku, jinak integrace dál pracuje se starým rokem.
2. Aktualizace Pohody. Po aktualizaci je někdy nutné převést účetní jednotku do nové verze. Dokud se to nestane, XML zpracování skončí chybou. Po každé aktualizaci proto ověřte, že komunikace znovu běží.
3. Zálohy a údržba databáze. Běžící mServer drží spojení s databází a blokuje některé operace, například zálohování. Výrobce nedoporučuje nechat ho běžet nepřetržitě ani ho spouštět jako službu Windows. Spouštění a vypínání se plánuje přes plánovač úloh.
4. Fronta požadavků. mServer zpracovává požadavky postupně. Když e-shop pošle stovky objednávek najednou, čekají v řadě. Počítejte s tím při návrhu synchronizace.
5. Verze schémat. Stormware schémata průběžně rozšiřuje. Validujte XML proti aktuálnímu balíku a sledujte plánované změny v kompatibilitě.

Postavit to sám, nebo ne?

Na jednorázový import nebo jednoduchý skript XML rozhraní stačí a dokumentace je slušná. Jakmile ale potřebujete spolehlivý obousměrný přenos, hlídání chyb a opakování, roste práce rychle. Možnosti pro e-shopy srovnává článek Propojení Pohody s e-shopem, automatizační nástroje rozebírá Make, Zapier, n8n a Pohoda. Co umí jednotlivé varianty pro napojení dalších systémů, najdete u detailu POHODA Komplet.

Časté otázky