STORMWARE Podpora FAQ Všeobecný internetový obchod Pre vývojárov

Pre vývojárov

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

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ý dátový súbor.

Odpoveď webovej 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ť .

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

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:

• jedná sa 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:

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 internetového obchodu – časť Nastavenie pre všeobecný internetový obchod.
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 dátovom 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:

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

• Vzorový príklad webovej služby stiahnuť

(aktualizáce údajov 16.01.2015)