Popis služby datové výměny

Základní popis

Webová služba je zprovozněna na e-shopu jako aplikační adresář /i6ws/: https://www.exasoft.cz/i6ws/. Pro přístup do webové služby používáme zabezpečený separátní přístup, aby případné změny hesla na e-shopu apod. nenarušily chod automatizovaného zpracování dat služby.

Se službou lze komunikovat pomoci protokolu SOAP. U metod s jednoduchými parametry (exporty) také pomoci GET/POST, takže XML exporty lze stahovat/získat obyčejným odkazem. Na službu se lze napojit nejen programově - poskytuje popis služby pomoci WSDL, ale lze ji také používat/zkoušet browserem. Služba má jednoduché rozhraní, kde zobrazuje výpis metod, stručný popis, u některých také zkušební formuláře, kterými lze metody rovnou z browseru vyvolat. Služba umí XML data komprimovat (gzip, deflate), pokud se požadavek vyšle s hlavičkou: Accept-Encoding: gzip, deflate

Rozsah poskytovaných dat

Lite verze je základní a je zdarma. Poskytuje informace o skladové dostupnosti a cenách. Neobsahuje produktové technické parametry, popisky a obrázky.

Full verze obsahuje navíc detailní produktové informace včetně obrázků. Je zpoplatněna částkou 1.000 Kč/měsíc splatnou dopředu.

Exporty dat

Poskytuje stránka: https://www.exasoft.cz/i6ws/Default.asmx.

Exporty dat lze získat pomoci obecných metod:

• GetResult - vrací všechna data (resp. přesněji základní množinu bez bližší specifikace - u produktu - vše, u stavu skladu - vše skladem, u objednávek - jen otevřené apod.)
• GetResultByCode - vrací data filtrovaná dle jednoznačného kódu - typicky jen jeden řádek (u produktových exportů se lze dotazovat i přes PartNo, když vyhledávací řetězec začíná na {PartNo})
• GetResultByFromTo - vrací data filtrovaná dle data od/do - typicky na základě evidované změny

Seznam dostupných exportů: https://www.exasoft.cz/i6ws/ResultTypeInfo.ashx.

Význam sloupců tabulky:

• ResultType - Název exportu (předává se jako argument metod resultType)
• Schema - Po kliknutí se zobrazí jednoduché schéma => Lze vyčíst vrácené atributy (sloupce)
• GetResult - Informace o možnostech / časech použití metody GetResult
• ByCode - Informace o možnostech / časech použití metody GetResultByCode
• ByFromTo - Informace o možnostech / časech použití metody GetResultByFromTo
  • pokud je vše vyšedlé, tak metoda není pro daný resultType implementována (nelze použít)
  • pokud jsou vyšedlé nějaké dny v |Allowed days of week| nejde metoda daný den zavolat (např. pro použití jen o víkendu)
  • pokud jsou vyšedlé nějaké hodiny v |Allowed hours| nejde metoda danou hodinu zavolat (např. pro použití jen mimo hlavní pracovní dobu)
• Description - Popis exportu

Jenoduché stažení pomoci metody GET

Základní syntaxe URL: https://JMENO:HESLO@www.exasoft.cz/i6ws/Default.asmx/NAZEV_METODY?resultType=NAZEV_RESULTU&PARAMETRY

• JMENO – Přihlašovací jméno do webové služby
• HESLO - Přihlašovací heslo do webové služby
• NAZEV_METODY - GetResult | GetResultByCode | GetResultByFromTo
• PARAMETRY
  • GetResult - resultType=
  • GetResultByCode - resultType= &code=
  • GetResultByFromTo - resultType= &from= &to=

Aby fungovala syntaxe JMENO:HESLO@ s logovacími údaji přímo v linku, je třeba při ručním zkoušení za použití Internet Exploreru to explicitně povolit: http://support.microsoft.com/kb/834489. Jinak používat bez uvedení JMENO:HESLO@ v URL, prohlížeč při prvním požadavku zobrazí přihlašovací dialog.

Příklady URL:

• základní vlastnosti všech produktů: https://www.exasoft.cz/i6ws/Default.asmx/GetResult?resultType=StoItemBase
• základní vlastnosti jednoho produktu GEM250304: https://www.exasoft.cz/i6ws/Default.asmx/GetResultByCode?resultType=StoItemBase&code=GEM250304
• základní vlastnosti jednoho produktu GEM250304: https://www.exasoft.cz/i6ws/Default.asmx/GetResultByCode?resultType=StoItemBase&code=GEM250304
• informace o stavu skladu jednoho produktu GEM250304 dle originálního Part Number PP12-2M: https://www.exasoft.cz/i6ws/Default.asmx/GetResultByCode?resultType=StoItemQtyFree&code={PartNo}PP12-2M
• informace o ceně jednoho produktu GEM250304: https://www.exasoft.cz/i6ws/Default.asmx/GetResultByCode?resultType=StoItemPriceOrd&code=GEM250304
• všechny produkty skladem: https://www.exasoft.cz/i6ws/Default.asmx/GetResult?resultType=StoItemQtyFree
• základní vlastnosti vice produktů, u kterých došlo ke změně mezi 13.06.2005-06.06.2079: https://www.exasoft.cz/i6ws/Default.asmx/GetResultByFromTo?resultType=StoItemBase&from=2005-06-13&to=2079-06-06

Ukázkové stažení s výsledným uložením XML souboru pomocí VBScriptu

Option Explicit
Main
Private Sub Main
   Dim strUrl, strFile
   strUrl = "https://JMENO:HESLO@www.exasoft.cz/i6ws/Default.asmx/GetResultByCode?resultType=StoItemBase&code=GEM250304"
   strFile = "C:\StoItemBase.xml"
   With CreateObject("MSXML2.XMLHTTP")
   WScript.Echo "Opening url: " & strUrl
  .Open "GET", strUrl, False
   .Send
   If .Status <> 200 Then Err.Raise vbObjectError + 1, "GetResponseXml", "Bad response status: [" & .Status & "] " & .StatusText & vbCrLf & .ResponseText
   WScript.Echo "Saving file: " & strFile
   .ResponseXml.Save strFile
   WScript.Echo "Done."
   End With
End Sub

Pokud se obsah bloku uloží do textového souboru s názvem: i6ws_client.vbs, lze jej pak spustit v příkazovém řádku CMD.EXE jako: cscript.exe i6ws_client.vbs. Script provede stažení základních informací o produktu GEM250304 a jeho uložení do souboru: C:\StoItemBase.xml.

Popis struktury exportu StoItemBase

StoItemBase je základní export poskytující informace produktech. Další produktové exporty jsou často jeho podmnožinou (jen ceny, informace o skladech apod.) Za použití URL z ukázky výše:

https://JMENO:HESLO@www.exasoft.cz/i6ws/Default.asmx/GetResultByCode?resultType=StoItemBase&code=GEM250304

by byla stažena následující XML struktura:

<Result
   UrlBase="string | základní URL pro tvorbu odkazu na produkt"
   UrlBaseThumbnail="string | základní URL pro tvorbu odkazu na obrázek - malý"
   UrlBaseImg="string | základní URL pro tvorbu odkazu na obrázek - běžný"
   UrlBaseEnlargement="string | základní URL pro tvorbu odkazu na obrázek - velký">
       <StoItem
          Id="number | jednoznačná identifikace produktu (aut. číslo), zřetězením, s atributy Url* lze dostat výsledný link"
          Code="string | jednoznačná identifikace produktu jako text (slouží k vyhledávání apod.)"
          Code2="string | alternativní identifikace produktu"
          PartNo="string | kód výrobce"
          PartNo2="string | EAN kód výrobce"
          Name="string | název produktu na e-shopu"
          NameAdd="string | alternativní název produktu"
          NameDoc="string | fakturační / systémový název produktu"
          ManName="string | název výrobce"
          PriceEU="number | doporučená koncová cena včetně poplatků bez DPH"
          PriceDea="number | celková cena produktu včetně poplatků bez DPH"
          PriceRef="number | výsledná hodnota recyklačního poplatku bez DPH"
          PriceRef2="number | výsledná hodnota autorského poplatku bez DPH""
          TaxRate="number | sazba DPH"
          QtyFree="number | info o produktu skladem ve smyslu ANO/NE, skutečný stav skladu možno zobrazit po domluvě"
          WarDur="number | doba záruky přepočtena na dny - pro podnikatele"
          WarDurEU="number | doba záruky přepočtena na dny - pro koncové uživatele"
          SNTrack="bit | informace o tom, jestli se u produktů sledují sériová čísla"
          ThumbnailIs="bit | informace o tom, má-li produkt obrázek - malý"
          ThumbnailSize="number | informace o velikosti obrázku - malý"
          ImgIs="bit | informace o tom, má-li produkt obrázek - běžný"
          ImgSize="number | informace o velikosti obrázku - běžný"
          EnlargementIs="bit | informace o tom, má-li produkt obrázek - velký"
          EnlargementSize="number | informace o velikosti obrázku - velký"
          SisName="string | stav produktu (novinka, výprodej apod.)"
          NoteShort="string | zkrácená poznámka"
          Note="string | poznámka"
       />
</Result>

Pro úsporu velikosti XML nejsou nulové nebo prázdné atributy vůbec vráceny.

• prázdné texty - např.: Code2, PartNo, PartNo2, NameAdd, NameE, ManName, SisName, NoteShort, Note
• NULL /nepřiřazené hodnoty - např.: PriceRef, RefProName, RefCode, PriceRef2, RefProName2, RefCode2, WeightRef, MeasureRef2
• nulové hodnoty - např: QtyFreeIs, QtyFree, SNTrack, ThumbnailIs, ThumbnailSize, ImgIs, ImgSize, EnlargementIs, EnlargementSize

Bližší komentář k některým atributům:

• ThumbnailIs | ThumbnailSize + ImgIs | EnlargementSize + EnlargementIs | EnlargementSize - Drive exportované informace jen ve smyslu ANO/NE *Is lze nahradit nově přidanými *Size (*Is = 1 je to stejné jako *Size > 0)
  • *Is sloupce zůstaly jen pro zpětnou kompatibilitu.
  • Ze *Size lze detekovat změnu obrázku (dá se předpokládat, že se změnou obrázku se změní také jeho velikost)
• WarDur + WarDurEU - Záruka je v systému vedena jako Doba(2,24,...)+Jednotka(Rok, Měsíc,...).
  • Ve službě je pro univerzálnost přepočtena na dny.
  • Z takto exportované hodnoty lze udělat zpětný přepočet:
    • MAXINT=2147483647 - jedná se o doživotní záruku
    • Je-li číslo beze zbytku dělitelné 365 - jde udělat přepočet na roky
    • Je-li číslo beze zbytku dělitelné 31 - jde udělat přepočet na měsíce.

Tvorba odkazu z exportovaných údajů:

Pro úsporu místa jsou konstantní části odkazu uvedeny v atributech jen jednou v kořenovém elementu Result.

Výsledný odkaz se vytvoří zřetězením atributu UrlBase* z kořenového elementu Result a atributem Id z řádkového elementu StoItem, takže:

• UrlBase + Id = odkaz na stránku s detailem produktu na e-shopu distributora
• UrlBaseThumbnail + Id = odkaz na obrázek (malý), má smysl jen pokud ThumbnailSize > 0
• UrlBaseImg + Id = odkaz na obrázek (běžný), má smysl jen pokud ImgSize > 0
• UrlBaseEnlargement + Id = odkaz na obrázek (velký), má smysl jen pokud EnlargementSize > 0

OBJEDNAVANI

Poskytuje služba/stránka: Order.asmx https://www.exasoft.cz/i6ws/Order.asmx

služba nemusí být povolena. Pokud služba není funkční, končí volání služby stavovým kódem: 501 Not Implemented

Lze jednoduše vyzkoušet GET požadavkem: https://JMENO:HESLO@www.exasoft.cz/i6ws/Order.asmx/GetStatus?Id=0 (dotaz na neexistující objednávku - vrátí buď chybu 500, nebo 501 - vůbec nezná metodu).

Vlastní popis objednávání přes webovou službu je v samostatném dokumentu: OrderReadMe.txt, https://JMENO:HESLO@www.exasoft.cz/i6ws/OrderReadMe.txt