Využite nový Účet POHODA pre bezpečnejšie a pohodlnejšie jednotné prihlasovanie k službám a aplikáciam STORMWARE

Pre vývojárov

Technické parametre POHODA mServer:

  • POHODA mServer využíva HTTP protokol na prenos ľubovoľných údajov pomocou páru požiadavka-odpoveď. Požiadavka a odpoveď sú zložené z textových hlavičiek, prázdneho riadku a binárnych údajov. Typ údajov je určený pomocou MIME (Multipurpose Intenet Mail Extension) typov v hlavičke Content-Type.
  • Prenos údajov je možný len vo formáte XML. Program POHODA podporuje len tento typ dát Content-Type: text/xml.
  • XML údaje je možné posielať iba pomocou metódy POST. Metóda GET na prenos XML údajov nie je podporovaná.
  • Pre prenos ľubovoľného typu súboru je nutné použiť metodu GET. POHODA mServer umožňuje preniesť(exportovať) iba súbory zo zložky dokumentov firmy.
  • POHODA mServer je určený na komunikáciu na lokálnej sieti/PC. POHODA mServer počúva na nastavenom porte. Ak obdrží http požiadavku, vykoná jej spracovanie a odpovie späť.
  • Hlavička HTTP požiadavky musí obsahovať parameter STW-Authorization, ktorý slúži na prístup (autentizáciu) k programu POHODA. POHODA mServer príjme HTTP požiadavku a spustí XML komunikáciu v programe POHODA pre spracovanie XML dát. Aby mohol POHODA mServer spustiť XML spracovanie údajov v programe POHODA, potrebuje platné prístupové údaje (užívateľské meno a heslo) do programu POHODA. Meno a heslo je posielané ako jeden textový reťazec. Za menom je pripojená dvojbodka a za ňou je heslo. Výsledný reťazec je potom zakódovaný metódou Base64 a odoslaní v rámci HTTP požiadavky. Aktuálne je podporovaná iba Basic Authentication.
  • POHODA mServer podporuje kompresiu prenášaných dát. Aktuálne sú podporované metódy: gzip/deflate.

Spracovanie požiadaviek na POHODA mServer

POHODA mServer vykonáva synchrónne spracovanie prijatých požiadaviek. Ak odošlete na POHODU mSever viac požiadaviek súčasne, najprv bude ich serializácia a následne ich postupné spracovanie v poradí tak, ako boli prijaté.

Zistenie stavu spustenia POHODA mServer prostredníctvom HTTP protokolu a metódy GET alebo POST

Pre zistenie stavu spustenia POHODA mServera je možné použiť parameter /status.
Pokiaľ bude mServer spustený a odošlete na neho požiadavku na zistenie stavu, vráti sa vám štandardná odpoveď pre úspešnú HTTP požiadavku: Status: 200 OK a ďalej bude odpoveď obsahovať XML dokument popisujúcí stav spusteného POHODA mServeru.

Príklad použitia: GET http://localhost:444/status

Príklad odpovede mServera programu POHODA na parameter /status

HTTP/1.1 200 OK
Connection: Keep-Alive
Content-Type: text/xml;
Content-Length: 189

<?xml version="1.0" encoding="UTF-8"?>
<mserver>
  <message>Response from POHODA mServer</message>
  <server>http://C0508P:444</server>
  <status>idle</status>
  <processing>0</processing>
</mserver>
Popis parametrov v XML response na stav mServera:
  • message, všeobecná textová správa mServera
  • server, adresa mServera
  • status, stav mServera (idle - nie je využívaný proces, working - spracováva požiadavku)
  • processing, počet požiadaviek na spracovanie na mServeri

Rozšírené informácie na stav POHODA mServer - informácie o účtovnej jednotke

Pre získanie rozšírených informácii o účtovnej jednotke priradenej k danej inštancii POHODA mServer je možné použiť parameter /status?company Detail, ktorý na rozdiel od bežného dotazu na stav vyžaduje autentizáciu do POHODY.
Pokiaľ bude POHODA mServer spustený a odošlete na neho požiadavku na zistenie stavu s parametrom /status?company Detail vrátane autentizácie do POHODY, vráti vám POHODA mServer štandardnú odpoveď pre úspešnú HTTP požiadavku Status: 200 OK a ďalej bude odpoveď obsahovať XML dokument popisujúci stav spusteného POHODA mServera + informácie o účtovnej jednotke.

Príklad použitia: GET http://localhost:444/status?companyDetail

Príklad odpovede mServera programu POHODA na parameter /status?companyDetail

HTTP/1.1 200 OK
Connection: Keep-Alive
Content-Type: text/xml;
Content-Length: 350

<?xml version="1.0" encoding="UTF-8"?>
<mserver>
  <message>Response from POHODA mServer</message>
  <server>http://C0508P:444</server>
  <status>idle</status>
  <processing>0</processing>
  <companyDetail>
   <company>Novák</company>
   <databaseName>12345678_2021.mdb</databaseName>
   <year>2021</year>
   <period>2021</period>
  </companyDetail>
</mserver>
Popis rozširujúcich parametrov bloku <companyDetail> v XML response na stav mServera:
  • company, názov účtovnej jednotky
  • databaseName, názov databázového súboru účtovnej jednotky
  • year, účtovný rok účtovnej jednotky
  • period, účtovné obdobie do ktorého je účtovná jednotka aktuálne prepnutá pod daným užívateľom

Komunikácia s POHODA mServer prostredníctvom metódy POST:

Je určená pre:

  • prenos dát do/z účtovnej jednotky programu POHODA

Pri volaní mServera prostredníctvom HTTP protokolu a metódy POST je potrebné v hlavičke HTTP požiadavky zadať:

  • adresu mServera
  • číslo portu, na ktorom mServer "počúva"
  • umiestnenie na serveri "/XML"
  • autentizácia pre prístup do programu POHODA, parameter STW-Authorization

Príklad použitia: POST http://localhost:444/xml

V hlavičke HTTP požiadavku je možné zadať tieto nepovinné rozširujúce parametre:

  • STW-Application, ktorý slúži pre identifikáciu aplikácie, ktorá komunikáciu s POHODA mSerververom vyvolá
  • STW-Instance, ktorý slúži pre identifikáciu jednotlivých komunikácii v rámci jednej aplikácie s POHODA mServer
  • STW-Check-Duplicity ktorý slúží pre nastavenie kontroly duplicity XML požiadaviek.
  • Accept-Encoding informácia pre POHODA mServer, že klient podporuje kompresiu prenášaných dát.
  • Content-Encodingstrong> informace pre POHODA mServer, že klient poslal komprimované údaje.

Pomocou týchto parametrov môžete následne spraviť filtrovanie záznamov v dialógu pre monitoring komunikácie na mServeri.

Prenos údajov cez POHODA mServer

POHODA mServer využíva na prenos údajov štandardnú XML komunikáciu programu POHODA. Bližšie informácie nájdete na www.stormware.sk/xml.

Ukážka komunikácie HTTP klienta s POHODA mServer

Príklad požiadavky HTTP klienta na mServer POHODA na export "Zásob" z programu POHODA.

POST http://localhost:444/xml HTTP/1.1
User-Agent: User-Agent: STORMWARE HTTP client. http://www.stormware.cz
STW-Authorization: Basic QDo=
Content-Type: text/xml
Accept-Encoding: gzip, deflate
Host: http://localhost:444
Content-Length: 527
Pragma: no-cache
Connection: Keep-Alive

<?xml version="1.0" encoding="Windows-1250"?>
<dat:dataPack xmlns:dat="http://www.stormware.cz/schema/version_2/data.xsd" xmlns:stk="http://www.stormware.cz/schema/version_2/stock.xsd" xmlns:ftr="http://www.stormware.cz/schema/version_2/filter.xsd" xmlns:lStk="http://www.stormware.cz/schema/version_2/list_stock.xsd" xmlns:typ="http://www.stormware.cz/schema/version_2/type.xsd" id="00000001" ico="25313142" application="HTTP klient" version="2.0" note="Export zasob">
  <dat:dataPackItem id="00000001" version="2.0">
    <lStk:listStockRequest version="2.0" stockVersion="2.0">
      <lStk:requestStock/>
    </lStk:listStockRequest>
  </dat:dataPackItem>
</dat:dataPack>

Príklad odpovede mServera programu POHODA

HTTP/1.1 200 OK
Connection: Keep-Alive
Content-Type: text/xml; charset=Windows-1250
Content-Length: 1151

<?xml version="1.0" encoding="Windows-1250"?>
<rsp:responsePack version="2.0" id="Z001" state="ok" programVersion="11600.32 (8.2.2017)" ico="12345678" note="export zásob" xmlns:rsp="http://www.stormware.cz/schema/version_2/response.xsd" xmlns:rdc="http://www.stormware.cz/schema/version_2/documentresponse.xsd" xmlns:typ="http://www.stormware.cz/schema/version_2/type.xsd" xmlns:lst="http://www.stormware.cz/schema/version_2/list.xsd" xmlns:lStk="http://www.stormware.cz/schema/version_2/list_stock.xsd" xmlns:lAdb="http://www.stormware.cz/schema/version_2/list_addBook.xsd" xmlns:acu="http://www.stormware.cz/schema/version_2/accountingunit.xsd" xmlns:inv="http://www.stormware.cz/schema/version_2/invoice.xsd" xmlns:vch="http://www.stormware.cz/schema/version_2/voucher.xsd" xmlns:int="http://www.stormware.cz/schema/version_2/intDoc.xsd" xmlns:stk="http://www.stormware.cz/schema/version_2/stock.xsd" xmlns:ord="http://www.stormware.cz/schema/version_2/order.xsd" xmlns:ofr="http://www.stormware.cz/schema/version_2/offer.xsd" xmlns:enq="http://www.stormware.cz/schema/version_2/enquiry.xsd" xmlns:vyd="http://www.stormware.cz/schema/version_2/vydejka.xsd" xmlns:pri="http://www.stormware.cz/schema/version_2/prijemka.xsd" xmlns:bal="http://www.stormware.cz/schema/version_2/balance.xsd" xmlns:pre="http://www.stormware.cz/schema/version_2/prevodka.xsd" xmlns:vyr="http://www.stormware.cz/schema/version_2/vyroba.xsd" xmlns:pro="http://www.stormware.cz/schema/version_2/prodejka.xsd" xmlns:con="http://www.stormware.cz/schema/version_2/contract.xsd" xmlns:adb="http://www.stormware.cz/schema/version_2/addressbook.xsd" xmlns:prm="http://www.stormware.cz/schema/version_2/parameter.xsd" xmlns:lCon="http://www.stormware.cz/schema/version_2/list_contract.xsd" xmlns:ctg="http://www.stormware.cz/schema/version_2/category.xsd" xmlns:ipm="http://www.stormware.cz/schema/version_2/intParam.xsd" xmlns:str="http://www.stormware.cz/schema/version_2/storage.xsd" xmlns:idp="http://www.stormware.cz/schema/version_2/individualPrice.xsd" xmlns:sup="http://www.stormware.cz/schema/version_2/supplier.xsd" xmlns:prn="http://www.stormware.cz/schema/version_2/print.xsd" xmlns:act="http://www.stormware.cz/schema/version_2/accountancy.xsd" xmlns:bnk="http://www.stormware.cz/schema/version_2/bank.xsd" xmlns:sto="http://www.stormware.cz/schema/version_2/store.xsd" xmlns:grs="http://www.stormware.cz/schema/version_2/groupStocks.xsd" xmlns:acp="http://www.stormware.cz/schema/version_2/actionPrice.xsd" xmlns:csh="http://www.stormware.cz/schema/version_2/cashRegister.xsd" xmlns:bka="http://www.stormware.cz/schema/version_2/bankAccount.xsd" xmlns:ilt="http://www.stormware.cz/schema/version_2/inventoryLists.xsd" xmlns:nms="http://www.stormware.cz/schema/version_2/numericalSeries.xsd" xmlns:pay="http://www.stormware.cz/schema/version_2/payment.xsd" xmlns:mKasa="http://www.stormware.cz/schema/version_2/mKasa.xsd" xmlns:ftr="http://www.stormware.cz/schema/version_2/filter.xsd">
  <rsp:responsePackItem version="2.0" id="0001" state="ok">
    <lStk:listStock version="2.0" dateTimeStamp="2017-02-09T13:09:45" dateValidFrom="2017-02-09" state="ok">
      <lStk:stock version="2.0">
        <stk:stockHeader>
          <stk:id>1</stk:id>
          <stk:stockType>text</stk:stockType>
          <stk:code>Jídel</stk:code>
          <stk:PLU>624</stk:PLU>
          <stk:isSales>true</stk:isSales>
          <stk:isSerialNumber>false</stk:isSerialNumber>
          <s>true</stk:isInternet>
          <stk:isBatch>false</stk:isBatch>
          <stk:purchasingRateVAT>high</stk:purchasingRateVAT>
          <stk:sellingRateVAT>high</stk:sellingRateVAT>
          <stk:name>Stůl jídelní - rozkládací</stk:name>
          <stk:unit>ks</stk:unit>
          <stk:storage>
            <typ:id>9</typ:id>
            <typ:ids>Ceník</typ:ids>
          </stk:storage>
          <stk:typePrice>
            <typ:id>4</typ:id>
            <typ:ids>Nábytek</typ:ids>
          </stk:typePrice>
          <stk:weightedPurchasePrice>2511.56</stk:weightedPurchasePrice>
          <stk:purchasingPrice>2500</stk:purchasingPrice>
          <stk:sellingPrice>3000</stk:sellingPrice>
        </stk:stockHeader>
        <stk:stockPriceItem>
          <stk:stockPrice>
            <typ:id>1</typ:id>
            <typ:ids>Prodejní</typ:ids>
            <typ:price>7680</typ:price>
          </stk:stockPrice>
        </stk:stockPriceItem>
      </lStk:stock>
    </lStk:listStock>
  </rsp:responsePackItem>
</rsp:responsePack>

Komunikácia s POHODA mServer prostredníctvom metódy GET:

Je určená pre:

  • prenos ľubovoľného typu súboru zo zložky dokumentov firmy programu POHODA (iba export dát). Napr. tlačová zostava uložená do PDF súboru, obrázky zásoby, dokumenty doklad, atď.

Pri volaní mServera prostredníctvom HTTP protokolu a metódy GET je nutné v HTTP požiadavke zadať:

  • adresa mServera
  • číslo portu, na ktorom mServer "počúva"
  • umiestnenie na serveri "/documents" + cesta k súboru
  • autentizácia pre prístup do programu POHODA, parameter STW-Authorization

Parameter /documents v URL adrese = cesta do zložky dokumentov firmy (účtovnej jednotky).
Za tento parameter je potrebné zadať cestu k súboru, ktorý chceme preniesť. Súbor sa musí nachádzať v zložke dokumentov firmy alebo v jej pod zložkách.

Upozornenie: Slovenské znaky s diakritikou v URL adrese je nutné prekódovať do"Windows-1250".
Bližšie informácie o kódovaní URL nájdete napr. https://cs.wikipedia.org

Príklad:
Zložka dokumentov firmy = C:\Stormware\Pohoda\Dokumenty\Novák
Súbor, ktorý chceme preniesť = C:\Stormware\Pohoda\Dokumenty\Novák\Obrázky\židle.jpg
URL adresa, ktorú použijeme v HTTP požiadavke = http://localhost:444/documents/obr%E1zky/%9Eidle.jpg

V hlavičke HTTP požiadavky je možné zdať tieto nepovinné rozširujúce parametre:

  • If-Modified-Since, prenos iba zmenených súborov od uvedeného dátumu.
  • STW-Application, ktorý slúži pre identifikáciu aplikácie, ktorá komunikáciu s POHODA mServerom vyvolá.
  • STW-Instance, ktorý slúži pre identifikáciu jednotlivých komunikácii v rámci jednej aplikácie s POHODA mServerom.

Ukážka komunikácie HTTP klienta s POHODA mServerom

Príklad požiadavky HTTP klienta na mServer POHODA na export "obrázku zásoby" zo zložky dokumentov firmy programu POHODA.

GET http://localhost:444/documents/obrazky/zidle.jpg HTTP/1.1
User-Agent: User-Agent: STORMWARE HTTP client. http://www.stormware.cz
STW-Authorization: Basic QDo=
Host: http://localhost:444
STW-application: eShop
STW-Instance: export souboru
If-Modified-Since: Wed, 19 Jun 2017 07:28:00
Connection: Keep-Alive
Cache-Control: no-cache

Príklad odpovede mServeru programu POHODA

HTTP/1.1 200 OK
Date: Thu, 05 Oct 2017 11:09:47 GMT
Connection: Keep-Alive
Content-Type: image/jpeg
Content-Length: 12431
Last-Modified: Mon, 02 Oct 2017 08:55:23 GMT


POHODA mServer vs prístupová práva programe POHODA

Pred použitím POHODA mServeru je nutné vykonať nastavenie prístupových práv v programe POHODA.
  • Pre prenos XML údajov je potrebné povoliť XML komunikáciu v programe POHODA vo vetve Práva/Súbor/Dátová komunikácia
  • Pre povolenie nastavenia POHODA mServer a prenos súborov zo zložky dokumentov firmy je potrebné povoliť práva vo vetve Práva/Administrátorské funkcie/POHODA mServer
Stavové kódy HTTP
Kód chyby
 
Popis chyby
400
Bad request
"Požiadavka nemôže byť vybavená, pretože bola syntakticky nesprávne zapísaná"
401
Unauthorized
"Používané tam, kde je vyžadovaná autentifikácia, ale nebola zatiaľ vykonaná". V tomto prípade ide o problém, kedy buď v HTTP požiadavke chýbajú autentizačné údaje alebo daný užívateľ nie je v programe POHODA vytvorený.
403
Forbidden
"Požiadavka bola legálna, ale server odmietol odpovedať". Napríklad ide o problém, kedy daný užívateľ nemá právo na otvorenie účtovnej jednotky v programe POHODA.
404
Not found
„Požadovaný dokument nebol nájdený“. Ide o problém, kedy bola chybne zadaná URL cesta k mServeru. Napríklad ide o problém, kedy v URL adrese nie je uvedená cesta k umiestneniu na serveri "/XML". Príklad správne zadnej URL: 192.168.0.1:444/xml
405
Method Not Allowed
„Požiadavka bola zavolaná na zdroj s metódou, ktorú nepodporuje. Napríklad ide o službu, na ktorú sa odosielajú údaje metódou POST a niekto sa ich namiesto toho pokúša odoslať metódou GET.“
408
Request Timeout
„Vypršal čas vyhradený na spracovanie požiadavky“
500
Internal server error
„Pri spracovávaní požiadavky došlo k bližšie nešpecifikovanej chybe“
502
Bad Gateway
„Proxy server alebo brána obdržali od servera neplatnú odpoveď“
503
Service unavailable
„Služba je dočasne nedostupná“
504
Gateway Timeout
„Proxy server nedostal od cieľového servera odpoveď v danom čase“
505
HTTP Version Not Supported
„Server nepodporuje verziu protokolu HTTP použitú v požadavke“

ASP konektor pro IIS

  • Ukážkový príklad ASP konektora pre IIS na presmerovanie HTTP požiadavky z Internetu do lokálnej siete stiahnuť
  • Návod nasadenia ASP konektora pre mServer stiahnuť
Späť navrch

Kam ďalej?

Spustenie POHODA mServera
POHODA mServer
Kontakt