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

Posledná aktualizácia 22. 02. 2016

Popis komunikácie programu POHODA a webovej služby

  • Program POHODA využívá HTTP / HTTPS protokol na prenos ľubovoľných údajov pomocou páru požiadavka-odpoveď. Požiadavka i odpoveď sú zložené z textových hlaviček, prázdného riadku a binárných údajov. Typ údajov je určený pomocou MIME (Multipurpose Intenet Mail Extension) typov v hlavičke Content-Type.
  • Na prenos údajov je v programe POHODA podporovaná iba metóda POST. Metóda GET nie je v programe POHODA podporovaná.
  • Program POHODA podporuje iba prenos údajov vo formáte XML, ide o typ Content-Type: text/xml
  • XML údaje sú uložené v kódovaní Windows-1250.
  • Prenos údajov medzi programom POHODA a všeobecným internetovým obchodom je možné spustiť len z programu POHODA.

Ukážka komunikácie programu POHODA s webovou službou

Príklad požiadavky programu POHODA na stiahnutie Adries z Internetového obchodu

POST http://elektro-net.sk/adresy.php HTTP/1.1
User-Agent: User-Agent: STORMWARE HTTP client. http://www.stormware.sk
Content-Type: text/xml
Accept-Encoding: gzip, deflate
Host: http://elektro-net.sk
Content-Length: 527
Pragma: no-cache
Connection: Keep-Alive
Authorization: Basic bXV6YXRrb0BzdG9ybXdhcmUuY3o6dmFub2Nl

<?xml version="1.0" encoding="Windows-1250"?>
<dat:dataPack xmlns:dat="http://www.stormware.sk/schema/version_2/data.xsd" xmlns:lAdb="http://www.stormware.sk/schema/version_2/list_addBook.xsd" id="00000001" ico="25313142" application="Obecn? Internetov? obchod - import" version="2.0" note="Import adres">
  <dat:dataPackItem id="00000001" version="2.0">
    <lAdb:listAddressBookRequest version="2.0" addressBookVersion="2.0">
      <lAdb:requestAddressBook/>
    </lAdb:listAddressBookRequest>
  </dat:dataPackItem>
</dat:dataPack>

Príklad odpovede webovej služby Internetového obchodu

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 1151
Server: Apache Coyote/1.0

<?xml version="1.0" encoding="utf-8"?>
<dat:dataPack id="ad001" ico="12345678" application="StwTest" version = "2.0" note="Import adres" xmlns:dat="http://www.stormware.sk/schema/version_2/data.xsd" xmlns:adb="http://www.stormware.sk/schema/version_2/addressbook.xsd" xmlns:typ="http://www.stormware.sk/schema/version_2/type.xsd">
  <dat:dataPackItem id="AD001" version="2.0">
    <adb:addressbook version="2.0">
      <adb:addressbookHeader>
        <adb:identity>
          <typ:address>
            <typ:name>Anna Veselá</typ:name>
            <typ:city>Jihlava</typ:city>
            <typ:street>Jarní 4</typ:street>
            <typ:zip>58601</typ:zip>
          </typ:address>
          <typ:shipToAddress>
            <typ:name>Anna Veselá</typ:name>
            <typ:city>Třebíč</typ:city>
            <typ:street>Nová 31</typ:street>
          </typ:shipToAddress>
        </adb:identity>
        <adb:region>Vysočina</adb:region>
        <adb:mobil>606888970</adb:mobil>
        <adb:email>vesela@seznam.cz</adb:email>
      </adb:addressbookHeader>
    </adb:addressbook>
  </dat:dataPackItem>
</dat:dataPack>

Export údajov z programu Pohoda na Internetový obchod

Štandardné výstupné údaje z programu POHODA pre Všeobecný internetový obchod sú vo formáte XML. Ide o XML formát programu POHODA. Popis a štruktúra XML je uvedená na adrese WWW.STORMWARE.SK/XML. XML údaje sú v kódovaní UTF-8. Ak potrebujete výstupné údaje z programu POHODA upraviť na iný dátový typ, je nutné použiť XSLT transformáciu. XSLT šablóna prevedie štandardný výstupný formát XML POHODA na Vami požadovaný dátový súbor. Na webovú službu bude potom odoslaný iba Váš upravený údajový súbor.

Odpověď webové služby

Po spojení s webovou službou a následnom odovzdaní výstupných údajov z programu POHODA, očakáva program POHODA odpoveď z webovej služby. Na základe tejto odpovede vyhodnotí stav komunikácie POHODA – Všeobecný internetový obchod. Aktuálna verzia komunikácie POHODA umožní vyhodnotiť iba dva stavy (OK, Error).

Definícia odpovede webovej služby

Program POHODA nemá presne definovanú dátovú štruktúru odpovede z webovej služby, je nutné dodržať iba základné podmienky:

  • odpoveď webovej služby = všeobecný XML dokument
  • XML dokument obsahuje element <rsp:responsePack> s atribútom @state
  • atribút @state nesie hodnotu pre vyhodnotenie stavu komunikácie (OK,Error)
Ak odpoveď webovej služby:
  • nie je dátového typu XML a neobsahuje element <rsp:responsePack> s atribútom @state
  • atribut @state nie je nastavený na hodnotu "OK"
bude vždy komunikácia so Všeobecným internetovým obchodom vyhodnotená ako chybná!

Príklad správnej odpovede webovej služby na export údajov z programu POHODA stiahnuť.

Príklad odpovede webovej služby Internetového obchodu

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 224
Server: Apache Coyote/1.0

<?xml version="1.0" encoding="utf-8"?>
<rsp:responsePack xmlns:rsp="http://www.stormware.sk/schema/response.xsd" note="response from the EShop" application="eShop" state="ok" id="00000001" version="1.0" ></rsp:responsePack>

Import údajov do programu POHODA z internetového obchodu

Program POHODA vytvorí požiadavku na stiahnutie údajov zo Všeobecného internetového obchodu, ktorú odovzdá webovej službe. Webová služba požiadavku spracuje a následne odovzdá odpoveď späť programu POHODA. Štandardná požiadavka z programu POHODA na stiahnutie údajov zo Všeobecného internetového obchodu je vo formáte XML. Ide o XML súbor programu POHODA.

Popis a štruktúra údajov XML požiadavky je uvedená na adrese WWW.STORMWARE.SK/XML. XML údaje sú v kódovaní UTF-8. Ak potrebujete požiadavku na údaje zo Všeobecného internetového obchodu upraviť na vlastný dátový typ, je nutné použiť XSLT transformáciu. XSLT šablóna Vám umožní previesť štandardnú požiadavku XML z programu POHODA na Vami nadefinovaný súbor. Na webovú službu bude odoslaný iba upravený dátový súbor. Program POHODA sa spojí s webovou službou, ktorej odovzdá požiadavku na stiahnutie údajov z Internetového obchodu. Webová služba požiadavku prevezme, vyhodnotí, spracuje a vytvorí odpoveď, ktorú odovzdá späť programu POHODA.

Príklady XML požiadaviek na stiahnutie údajov z Internetového obchodu do programu POHODA

Zásoby
XML požiadavka na stiahnutie všetkých zásob z Internetového obchodu
požiadavka
XML požiadavka na stiahnutie zásob z Internetového obchodu. Filter = kód zásoby
požiadavka
XML požiadavka na stiahnutie zásob z Internetového obchodu. Filter = nové zásoby.
požiadavka
Adresy
XML požiadavka na stiahnutie všetkých adries z Internetového obchodu.
požiadavka
XML požiadavka na stiahnutie adries z Internetového obchodu. Filter = názov obce adresy
požiadavka
XML požiadavka na stiahnutie adries z Internetového obchodu. Filter = nové adresy.
požiadavka
Objednávky
XML požiadavka na stiahnutie všetkých objednávok z Internetového obchodu.
požiadavka
XML požiadavka na stiahnutie objednávok z Internetového obchodu. Filter = dátum objednávky (od-do).
požiadavka
Požiadavka na stiahnutie objednávok z Internetového obchodu. Filter = nové objednávky.
požiadavka
Odpoveď webovej služby:
  • neobsahuje informácie o stave komunikácie.
  • obsahuje iba údaje, ktoré sú určené pre import do programu POHODA.
  • v elemente <dataPack> definujeme atribút "ICO" ktorý vyberá účtovná jednotka v programe POHODA, do ktorej sa budú údaje načítavať.
Definícia odpovede webovej služby:

Program POHODA má v tomto prípade presne definovanú štruktúru odpovede webovej služby.

Odpoveď webovej služby musí dodržať základné podmienky:

  • ide o XML súbor typu POHODA.
  • XML musí byť validný podľa XSD schémy pre danú agendu.

Definície XML súboru nájdete na adrese WWW.STORMWARE.SK/XML.

Ak odpoveď webovej služby:

  • nie je dátového typu XML programu POHODA,

potom je potrebné použiť XSLT transformáciu pre úpravu odpovede Všeobecného internetového obchodu na požadovaný dátový typ a štruktúru.
Príklad odpovede webovej služby, import údajov zo Všeobecný internetový obchod do POHODA:

Agenda
XML obsahuje údaje
XML neobsahuje údaje
Zásoby
zasoby.xml
zasoby_empty.xml
Adresár
adresy.xml
adresy_empty.xml
Objednávky
objednavkyPrij.xml
objednavky_empty.xml

Sledovanie histórie komunikácie POHODA - Všeobecný internetový obchod

Východiskové nastavenie komunikácie POHODA – Všeobecný internetový obchod využíva pre ukladanie údajov komunikáciu TEMPorary zložky operačného systému Windows. V tomto prípade nie je komunikácie uchovaná. Ak budete chcieť sledovať priebeh komunikácie a jej históriu, je potrebné zapnúť v programe Pohoda voľbu Sledovanie komunikácie (história) v agende Nastavenie všeobecného internetového obchodu.
Podľa typu komunikácie bude vytvorená podzložka EXPORT/IMPORT, do ktorej budú uložené dátové súbory komunikácie (požiadavka a odpoveď) POHODA - Všeobecný internetový obchod.
Priebeh komunikácie je zaznamenaný do „Log“ súboru, ktorý je uložený v údajovom adresári programu POHODA, podadresár LOG. Názov súboru je: IOobchod.log
XML dokumenty, uložené pri sledovaní histórie komunikácie, sú uložené v inom kódovaní ako súbory, ktoré sú odoslané webovej službe. XML dokumenty uložené v histórii sú v kódovaní "Windows-1250".

Štruktúra Log súboru komunikácie POHODA - Všeobecný internetový obchod: stiahnuť
Vzorový príklad Log súboru komunikácie POHODA - Všeobecný Internetový obchod: stiahnuť

Autentizácia webovej služby

Program POHODA používa jednoduchú autentizáciu pri prístupe k webovej službe. Ide teda o Basic access authentication.

Kontrola duplicity importu údajov do programu POHODA

Kontrola duplicity je založená na kontrole importovaných blokov <dataPack> a <dataPackItem>  vstupního XML dokumentu. Tieto bloky obsahujú atribút ID, ktorý jednoznačne identifikuje importované údaje.
Pri zapnutej kontrole duplicity je skontrolované ID bloku <dataPack> a <dataPackItem> oproti zoznamu už importovaných XML dokumentov do programu POHODA. Tieto záznamy sa nachádzajú v agende XML log. Ak je nájdená duplicita, import údajov bude ukončený.
Kontrola duplicity nekontroluje duplicitu v účtovných údajoch (Napr. číslo dokladu, IČO adresa , atď ...). Agenda XML log je vo východiskovom nastavení programu POHODA nastavená pre plnú editáciu, preto je možné záznamy zmazať. Ak budete chcieť zakázať zmazanie záznamov v tejto agende, je nutné upraviť nastavenie prístupových práv tejto agendy v programe POHODA.

Doplňujúce kontroly importovaných údajov:

Doklad objednávka
kontrola importovaného dokladu podľa čísla dokladu.
V tomto prípade je nutné vo vstupnom XML dokumente uviesť element <ord:number> a podelement <typ:numberRequested>. Definícia elementu je popísaná v schéme Order.xsd a Type.xsd.Pri importe XML dokumentu, ktorý obsahuje tento element bude navyše vykonaná kontrola na číslo dokladu. Ak doklad s rovnakým číslom v programe POHODA existuje, import bude ukončený.
Doklad Adresa
kontrola importovanej adresy podľa zadaných parametrov (filtra).
V tomto prípade je potrebné uviesť vo vstupnom XML dokumente element <duplicityFields>,v ktorom budeme definovať parametre pre kontrolu duplicity adresy.
Definícia elementu je popísaná v schéme Addressbook.xsd. Pri importe XML dokumentu, ktorý obsahuje tento element, bude navyše vykonaná kontrola na duplicity adresy. Ak táto adresa už v programe POHODA existuje, import bude ukončený.
Chybové kódy komunikácie POHODA - Všeobecný internetový obchod:
Kód chyby
Popis chyby
-1
„Chyba parsovania URL"
-3
„Požiadavka XML je prázdna“
-4
"Odpoveď (response) webovej služby obsahuje nepovolený Content-Type. Program POHODA vyžaduje Content-Type: text/xml“
-12002
„Vypršal časový limit na odpoveď servera“
-12045
„Nepodarilo se overit autoritu certifikátu. Je nutné naimportovat certifikát autority vystaviteľa do úložiska "Dôveryhodné koreňové certifikačné autority".“
-12057
„Certifikát SSL na danej URL adrese má definované vo vlastnostiach certifikátu v údaji "common name" iný názov ako má tento web doménu. Tieto údaje by mali byť zhodné.“
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 zatiaľ nebola vykonaná"
403
Forbidden
"Požiadavka bola legálna, ale server odmietol odpovedať"
404
Not found
„Požadovaný dokument nebol nájdený“
405
Method Not Allowed
„Požiadavka bola zavolaná na zdroji s metódou, ktorá nie je podporovaná. Napríklad ide o službu, na ktorú sa odosielajú údaje metódou POST a niekto sa ich namiesto toho pokúsi 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 cielového servera odpoveď v danom čase“
505
HTTP Version Not Supported
„Server nepodporuje verziu protokolu HTTP použitú v požiadavke“

Príklad webovej služby komunikácie: POHODA - Všeobecný Internetový obchod

Kam ďalej?

Nastavenie
Import a export údajov
Kontakt