Kasutaja tarvikud

Lehe tööriistad



et:xmlcore

Erinevused

Siin näed erinevusi valitud versiooni ja hetkel kehtiva lehekülje vahel.

Lõlita võrdlemise vaatele

Both sides previous revision Previous revision
Next revision
Previous revision
et:xmlcore [2015/08/26 09:38]
ott
et:xmlcore [2024/01/24 11:32] (Hetkel kehtiv)
kaie
Rida 1: Rida 1:
 ======XML andmevahetusliidese üldine kirjeldus====== ======XML andmevahetusliidese üldine kirjeldus======
 =====Üldine===== =====Üldine=====
-Iga Directo baasi külge saab soovi korral häälestada andmevahetusliidese,​ mis võimaldab ​mõlemasuunalist ​andmeliiklust. Oluline on tähele panna, et liides pole mitte vaikimisi olemas ja kättesaadav,​ vaid häälestatakse iga konkreetse ​juhtumi puhul eraldi konkreetse ülesandepüstituse vajadustest lähtuvalt. Liidese paigaldamine on seotud ühekordse häälestustasugamille suurus ​sõltub kummaski suunas liikuvate ​andmeliikude ​arvust, seega on enne tööde alustamist vaja ühendust võtta Directo ​müügiesindajaga ​ja kokku leppida täpsed vajadused ​ja kooskõlastada projekti maksumus.+Iga Directo baasi külge saab soovi korral häälestada andmevahetusliidese,​ mis võimaldab ​mõlema suunalist ​andmeliiklust. Oluline on tähele panna, et liides pole mitte vaikimisi olemas ja kättesaadav,​ vaid häälestatakse iga juhtumi puhul eraldi konkreetse ülesandepüstituse vajadustest lähtuvalt. Liidese paigaldamine ​ja arendamine ​on tasulinevastavalt [[https://​directo.ee/​hinnad#​Liidesed|hinnakirjale]] ning selle töö maht sõltub kummaski suunas liikuvate ​andmeliikide ​arvust, seega on enne tööde alustamist vaja ühendust võtta Directo ​projektijuhiga ​ja kokku leppida täpsed vajadused ​ning kooskõlastada projekti maksumus.
  
 Sõltumata konkreetse liidestusprojekti spetsiifikast on teatud printsiibid,​ millega peab igal juhul arvestama. Sõltumata konkreetse liidestusprojekti spetsiifikast on teatud printsiibid,​ millega peab igal juhul arvestama.
Rida 8: Rida 8:
   * Andmete kodeering on UTF-8   * Andmete kodeering on UTF-8
   * Transpordiprotokoll on HTTPS (avalikult tunnustatud sertifikaadiga)   * Transpordiprotokoll on HTTPS (avalikult tunnustatud sertifikaadiga)
-  * Andmete pärimisel kasutatakse GET meetodit +  * Liidesele ligipääsuks ​kasutatakse POST meetodit
-  * Andmete postitamisel ​kasutatakse POST meetodit+
   * Andmeliikluse algatab alati väline osapool sõltumata sellest, kas andmeid päritakse või saadetakse, Directo liides on passiivne   * Andmeliikluse algatab alati väline osapool sõltumata sellest, kas andmeid päritakse või saadetakse, Directo liides on passiivne
   * POST päringule vastab liides sünkroonse XML sõnumiga, mille töötlemine võib protsessi edukuse huvides oluline olla   * POST päringule vastab liides sünkroonse XML sõnumiga, mille töötlemine võib protsessi edukuse huvides oluline olla
   * Andmete struktuur peab olema kirjeldatav XSD schemana, võimaluse korral eelistada schemat, kus väärtuste kandjaks on atribuudid, mitte elemendid   * Andmete struktuur peab olema kirjeldatav XSD schemana, võimaluse korral eelistada schemat, kus väärtuste kandjaks on atribuudid, mitte elemendid
 +  * Dokumendi numbrid Directos on //integer// tüüpi, mis tähendab, et suurim võimalik number on //​2147483647//​
 +  * Üks XML liidese postitus ei tohi olla suurem kui 10Mb
 +
 +=====Liidestele ligipääs=====
 +
 +Liidesele ligipääs käib POST meetodil, form/​urlencoded all toodud liidese URL'​ide suhtes.
 +Ligipääsu tagamiseks tuleb kasutada appkey'​d. Demobaasil on appkey: 2852DD553B767B463C807ADB36B5BB2F.
 +Appkey tuleb POST meetodil muutujas KEY (sarnaselt siis html vormi postitamisele) ​ saata antud URL'i pihta tulemuse saamiseks. Ebakorrektse või valesti saadetud appkey korral on vastus <code xml> <result type="​5"​ desc="​Unauthorized"/>​ </​code>​
 +
 +Näide ​ käsurealt cURL kasutamisel:​
 +<​code>​
 +curl -v -d "​key=2852DD553B767B463C807ADB36B5BB2F&​what=item&​get=1&​ts=01.01.2021&​code=000001"​ -H "​Content-Type:​ application/​x-www-form-urlencoded"​ -X POST "​https://​login.directo.ee/​xmlcore/​demo_ee/​xmlcore.asp"​
 +</​code>​
  
 =====Näited===== =====Näited=====
Rida 21: Rida 33:
   * Vastussõnumid   * Vastussõnumid
   * Võtmed   * Võtmed
 +
 +Testimiseks kasutage seda vormi: https://​login.directo.ee/​xmlcore/​demo_ee/​webupload.html
  
 ====Andmete pärimine Directost ehk väljund==== ====Andmete pärimine Directost ehk väljund====
  
-GET päringu korral on alati täidetud vähemalt kolm parameetrit:​+Andmete pärimine käib POST meetodil ​GET parameetriga ning alati on täidetud vähemalt kolm parameetrit:​
   * ''​get=1''​   * ''​get=1''​
   * ''​what=ANDMELIIK''​   * ''​what=ANDMELIIK''​
-  * ''​key=PREDEFINEDKEY''​+  * ''​appkey=PREDEFINEDKEY''​
  
 ja võimalikud lisaparameetrid. Kasutusel olevad andmeliikide verbid, võtme väärtused ja andmeliigipõhised lisaparameetrid lepitakse kokku iga konkreetse installatsiooni käigus. ja võimalikud lisaparameetrid. Kasutusel olevad andmeliikide verbid, võtme väärtused ja andmeliigipõhised lisaparameetrid lepitakse kokku iga konkreetse installatsiooni käigus.
 +XML’ist jäetakse alati välja koos nimega sellised väljad, mille sisu baasis on NULL (tühi).
  
-===Praktiline näide ​- artiklite väljund=== + 
-Seda tüüpi ​väljundit ​kasutab tihti näiteks veebipood, et toodete ja nende saadavuse infot Directost poodi laadida.+ 
 +===Praktiline näide=== 
 +Seda tüüpi ​väljundeid ​kasutab tihti näiteks veebipood, et klientide, ​toodete ja toodete ​saadavuse infot Directost poodi laadida.
  
 <wrap important>​Käesolevas näites toodud URLid on mõeldud ainult võimaliku päringuformaadi illustreerimiseks. Ühelgi juhul ei ole tagatud, et need URLid päringule ka reaalselt vastavad. Juhul, kui päringu tulemuseks on andmed, on need 100% fiktiivsed ja pole seotud ühegi reaalse äriühingu andmetega.</​wrap>​ <wrap important>​Käesolevas näites toodud URLid on mõeldud ainult võimaliku päringuformaadi illustreerimiseks. Ühelgi juhul ei ole tagatud, et need URLid päringule ka reaalselt vastavad. Juhul, kui päringu tulemuseks on andmed, on need 100% fiktiivsed ja pole seotud ühegi reaalse äriühingu andmetega.</​wrap>​
  
-Antud näiteks kasutatakse verbi ''​what=item''​ ja võtme väärtus on ''​20DAF3F822B782AF12D1198C23F45604''​. ​Soovi korral võib tutvuda ​struktuuri ​kirjeldava schemaga {{:et:​ws_artiklid.xsd|}}+==Artiklite väljund:​== 
 +Antud näiteks kasutatakse verbi ''​what=item''​ ja ''​get=1''​. 
 +Kõik filtrid on võimalikud,​ juhul kui vastav väli on skeemis olemas. Näiteks: 
 +"​class","​code","​barcode","​supplier","​supplieritem","​closed","​ts"​ 
 +Artiklite ​struktuuri ​kirjeldav skeem ​[[https://​login.directo.ee/​xmlcore/​demo_ee/​ws_artiklid.xsd]] 
 + 
 +Artklite päring muudatuste kohta (ts=Time stamp): 
 +https://​login.directo.ee/​xmlcore/​demo_ee/​xmlcore.asp?​what=item&​get=1&​ts=01.01.2021 
 + 
 +Aja filtris võib kasutada ka kellaaega sellisel kujul: &​ts=01.03.2021 12:30 / &​ts=01.03.2021%2012:​30
  
 Terve tootebaasi päring: Terve tootebaasi päring:
-https://​directo.gate.ee/​xmlcore/​demo_ee/​xmlcore.asp?​get=1&​what=item&​key=20DAF3F822B782AF12D1198C23F45604+https://login.directo.ee/​xmlcore/​demo_ee/​xmlcore.asp?​get=1&​what=item
  
 Üksiku toote päring, toote koodi järgi, lisaparameeter ''​code=0000'':​ Üksiku toote päring, toote koodi järgi, lisaparameeter ''​code=0000'':​
-https://directo.gate.ee/​xmlcore/​demo_ee/​xmlcore.asp?​get=1&​what=item&​code=0000&​key=20DAF3F822B782AF12D1198C23F45604+https://login.directo.ee/​xmlcore/​demo_ee/​xmlcore.asp?​get=1&​what=item&​code=0000 
 + 
 +==Klientide väljund:​== 
 +https://​login.directo.ee/​xmlcore/​demo_ee/​xmlcore.asp?​get=1&what=customer&​ts=01.01.2021 
 + 
 +Näidis filtrite võimalused:​ "​code","​loyaltycard","​regno","​email","​phone","​closed","​ts"​ 
 +Klientide struktuuri kirjeldav skeem: ​ [[https://​login.directo.ee/​xmlcore/​demo_ee/​ws_kliendid.xsd]] 
 + 
 +==Laoseisude väljund:​== 
 +https://​login.directo.ee/​xmlcore/​demo_ee/​xmlcore.asp?​get=1&​what=stocklevel 
 + 
 +Näidis filtrite võimalused:"​code","​stock"​ 
 +Laoseisude struktuuri kirjeldav skeem: ​ [[https://​login.directo.ee/​xmlcore/​demo_ee/​ws_laoseis.xsd]]
  
 ====Andmete saatmine Directosse ehk sisend==== ====Andmete saatmine Directosse ehk sisend====
Rida 52: Rida 90:
   * ''​xmldata=<?​xml version="​1.0"​ encoding="​utf-8"?><​PAYLOAD>''​   * ''​xmldata=<?​xml version="​1.0"​ encoding="​utf-8"?><​PAYLOAD>''​
  
-===Praktiline näide - müügiarvete sisend=== +Sisendliideses tuleb XML postitata aadressile:​ 
-Seda tüüpi sisendit kasutatakse näiteks ​sellisel ​puhul, kui mingis välises süsteemis genereeritakse müügiarveid,​ mida on vaja Directos kajastada.+https://​login.directo.ee/​xmlcore/​demo_ee/​xmlcore.asp 
 +POST muutujatega „put=1“, „key=[appkey väärtus]“,​ „what=order“ ( või „what=customer“ või „what=item“ )  ja „xmldata=[XML'i sisu]“ 
 +Sisend xml peab vastama skeemile. 
 +Palun vältida tühja sisuga väljade saatmist ​sellisel ​kujul: customer_code=""​.
  
-<wrap important>​Käesolevas näites toodud URLid ja XML sõnumid ​on täiesti fiktiivsed ja pole teenuse testimiseks kasutatavadTestimine toimub alati reaalse installatsiooni suhtes.</​wrap>​+===Praktiline näide=== 
 +Seda tüüpi sisendit kasutatakse näiteks sellisel puhul, kui mingis välises süsteemis genereeritakse müügi tellimusi, mida on vaja Directos kajastadaLisaks on ka Klientide skeemi kirjeldus
  
-Oletame, et liidese URL on antud juhul https://​directo.gate.ee/xmlcore/​this_is_the_worlds_greatest_company/​xmlcore.asp+<wrap important>​Käesolevas näites toodud URLid ja XML sõnumid ​on täiesti fiktiivsed ja pole teenuse testimiseks kasutatavadTestimine toimub alati reaalse installatsiooni suhtes.</wrap>
  
-Andmeid kirjeldab ​schema {{:et:​xml_in_arved.xsd|}}+==Müügitellimuse sisend liides:== 
 +Andmeid kirjeldab ​skeem [[https://​login.directo.ee/​xmlcore/​demo_ee/​xml_IN_tellimused.xsd]] 
  
-Schemale ​vastav, aga sugugi mitte kõiki võimalikke atribuute kasutab XML võib välja näha näiteks selline:+Skeemile ​vastav, aga sugugi mitte kõiki võimalikke atribuute kasutab XML võib välja näha näiteks selline:
 <code xml> <code xml>
 <?xml version="​1.0"​ encoding="​utf-8"?>​ <?xml version="​1.0"​ encoding="​utf-8"?>​
-<invoices+<orders
-  <invoice AppKey="1234567879012345678790" ​InvoiceNr="123" ​ +  <order number="1" ​customercode="customercode1" ​customername="customername1" ​date="1900-01-01T01:​01:​01+02:​00">​ 
- InvoiceDate="2015-06-07" ​CustomerCode="CUST001">​ +    <rows
-    <lines+      <row item="item1" ​description="description1" ​price="1" quantity="​1"​ sum="​1"​ rn="1" /> 
-      <line ProductID="KILLERPRODUCT" ​Quantity="3" ​UnitPriceWoVAT="123.45"/>​ +      <row item="item2" ​description="​description2"​ price="​0"​ quantity="​1" ​sum="0" rn="2" /> 
-      <line ProductID="FREESAMPLE" ​Quantity="​1" ​UnitPriceWoVAT="0.00"/>​ +    </rows
-    </lines+  </order
-  </invoice+ </orders>
-</invoices>+
  
 </​code>​ </​code>​
Rida 78: Rida 120:
 Postitusele vastab liides sünkroonse XML sõnumiga, kust saab teada, mis juhtus. ​ Postitusele vastab liides sünkroonse XML sõnumiga, kust saab teada, mis juhtus. ​
  
-Näide, postitus oli edukas ja Directosse võeti vastu müügiarve ​number ​123:+Näide, postitus oli edukas ja Directosse võeti vastu müügitellimuse ​number ​1:
 <code xml> <code xml>
 <?xml version="​1.0"​ encoding="​UTF-8"​ ?>  <?xml version="​1.0"​ encoding="​UTF-8"​ ?> 
 <​results>​ <​results>​
-  <Result Type="​0"​ Desc="​OK"​ docid="​123" doctype="​INVOICE" submit="​Invoices" /> +  <Result Type="​0"​ Desc="​OK"​ docid="​1" doctype="​ORDER" submit="​Orders" /> 
 </​results>​ </​results>​
 </​code>​ </​code>​
Rida 88: Rida 130:
 Kui ''​Result''​ elemendi ''​Type''​ atribuudi väärtus pole 0, siis on tegemist mingi veaga ja sel juhul ütleb atribuut ''​Desc''​ lähemalt, mis häda oli. Kui ''​Result''​ elemendi ''​Type''​ atribuudi väärtus pole 0, siis on tegemist mingi veaga ja sel juhul ütleb atribuut ''​Desc''​ lähemalt, mis häda oli.
  
-Näide, ​arve number ​123 vastuvõtmisest keelduti, kuna sellise numbriga ​arve oli Directos juba olemas:+Näide, ​tellimuse ​number ​vastuvõtmisest keelduti, kuna sellise numbriga ​tellimus ​oli Directos juba olemas:
 <code xml> <code xml>
 <?xml version="​1.0"​ encoding="​UTF-8"​ ?>  <?xml version="​1.0"​ encoding="​UTF-8"​ ?> 
 <​results>​ <​results>​
-  <Result Type="​1"​ Desc="​Duplicate"​ docid="​123" doctype="​INVOICE" submit="​Invoices" /> +  <Result Type="​1"​ Desc="​Duplicate"​ docid="​1" doctype="​ORDER" submit="​Orders" /> 
 </​results>​ </​results>​
 </​code>​ </​code>​
  
-Ühest pakis võib olla korraga ka mitu arvet, igaühe kohta tuleb omaette ''​Result'':​+Ühest pakis võib olla korraga ka mitu tellimust, igaühe kohta tuleb omaette ''​Result'':​
 <code xml> <code xml>
 <?xml version="​1.0"​ encoding="​UTF-8"​ ?>  <?xml version="​1.0"​ encoding="​UTF-8"​ ?> 
 <​results>​ <​results>​
-  <Result Type="​1"​ Desc="​Duplicate"​ docid="​123" doctype="​INVOICE" submit="​Invoices" />  +  <Result Type="​1"​ Desc="​Duplicate"​ docid="​1" doctype="​ORDER" submit="​Orders" />  
-  <Result Type="​0"​ Desc="​OK"​ docid="​124" doctype="​INVOICE" submit="​Invoices" /> +  <Result Type="​0"​ Desc="​OK"​ docid="​2" doctype="​ORDER" submit="​Orders" /> 
 </​results>​ </​results>​
 </​code>​ </​code>​
  
 Vastussõnumi töötlemine on oluline, juhul kui pole õnnestunud saada edukat vastuvõttu tähistavat sõnumit, tuleb saatmine ebaedukaks lugeda ja mingi intervalli järel (mitte vähem kui 60s) uuesti proovida. Vastussõnumi töötlemine on oluline, juhul kui pole õnnestunud saada edukat vastuvõttu tähistavat sõnumit, tuleb saatmine ebaedukaks lugeda ja mingi intervalli järel (mitte vähem kui 60s) uuesti proovida.
 +
 +==Klientide sisend liides:==
 +Andmeid kirjeldab skeem [[https://​login.directo.ee/​xmlcore/​demo_ee/​xml_IN_kliendid.xsd]]. Andmete postitamine käib sama moodi nagu tellimuste postitamine.
 +Skeemile vastav, aga sugugi mitte kõiki võimalikke atribuute kasutab XML võib välja näha näiteks selline:
 +<code xml>
 +<?xml version="​1.0"​ encoding="​utf-8"?>​
 +<​customers>​
 +  <​customer code="​Kliendikood1"​ name="​Nimi"​ address1="​address11"​ address2="​address21"​ address3="​address31"​ email="​email1"​ regno="​regno1"​ class="​class1"​ type="​1"​ >
 +  </​customer>​
 + </​customers>​
 +</​code>​
  
  
Rida 111: Rida 164:
 ===Väljund=== ===Väljund===
 <code php> <code php>
-$url = '​https://​directo.gate.ee/​xmlcore/​demo_ee/​xmlcore.asp?​get=1&​what=item&​key=20DAF3F822B782AF12D1198C23F45604';​ 
  
 +$url = '​https://​login.directo.ee/​xmlcore/​demo_ee/​xmlcore.asp';​
 +$key = '​2852DD553B767B463C807ADB36B5BB2F';​
 $ch = curl_init();​ $ch = curl_init();​
 curl_setopt($ch,​ CURLOPT_HEADER,​ 0); curl_setopt($ch,​ CURLOPT_HEADER,​ 0);
 curl_setopt($ch,​ CURLOPT_RETURNTRANSFER,​ true); curl_setopt($ch,​ CURLOPT_RETURNTRANSFER,​ true);
 +curl_setopt($ch,​ CURLOPT_FOLLOWLOCATION,​ true);
 curl_setopt($ch,​ CURLOPT_URL,​ $url ); curl_setopt($ch,​ CURLOPT_URL,​ $url );
-curl_setopt($ch,​ CURLOPT_POST, ​0);+curl_setopt($ch,​ CURLOPT_POSTFIELDS,​ '​key='​.urlencode($key) . '&​what=item&​get=1&​ts=01.01.2021&​code=000001'​ );  
 +curl_setopt($ch,​ CURLOPT_POST, ​1);
  
 $result = curl_exec($ch);​ $result = curl_exec($ch);​
Rida 128: Rida 184:
  
 print '<​pre>';​ print '<​pre>';​
- +print_r($data);​ 
-foreach ($data->items->item as $item) { +foreach ($data->​item as $item) { 
- print $item['​Code'] . chr(9) .  '<​b>'​ . $item['​Name'] . '</​b>'​ . chr(9) .  $item['​Class'] . '<​br>';​+ print ​'​Code:'​.$item['​code'] . chr(9) .  '<​b>'​ . $item['​name'] . '</​b>'​ . chr(9) .  $item['​class'] . '<​br>​Datafields:​<​br>';​
  foreach ($item->​datafields->​data as $df ) {  foreach ($item->​datafields->​data as $df ) {
  print chr(9) . $df['​code'​] . ':'​ . $df['​content'​] . '<​br>';​  print chr(9) . $df['​code'​] . ':'​ . $df['​content'​] . '<​br>';​
  }  }
 } }
 +
 </​code>​ </​code>​
  
Rida 140: Rida 197:
 ===Sisend=== ===Sisend===
 <code php> <code php>
 +$url = '​https://​login.directo.ee/​xmlcore/​demo_ee/​xmlcore.asp';​
 +$key = '​2852DD553B767B463C807ADB36B5BB2F';​
  
-$xmldata = '<'​.'​?xml version="​1.0"​ encoding="​UTF-8"?>​ +$xmldata = <<<​XML 
-<invoice AppKey="1234567879012345678790" ​InvoiceNr="123" ​ +<?xml version="​1.0"​ encoding="​utf-8"?>​ 
- InvoiceDate="2015-06-07" ​CustomerCode="CUST001">​ +<items> 
-    <lines+  <item code="LMP0001" ​name="Lambikas" ​class="LAMP" ​barcode="123456789"​ salesprice="​11.25"​ description="​See on suur lamp" > 
-      <line ProductID="KILLERPRODUCT" ​Quantity="3" UnitPriceWoVAT="​123.45"/>​ +    <datafields
-      <line ProductID="FREESAMPLE" ​Quantity="1" UnitPriceWoVAT="​0.00"/>​ +      <data code="ART_VARV" ​content="Punane" /> 
-    </lines+      <data code="VEEBIS" ​content="Jah" /> 
-</invoice>';+    </datafields
 +  </item> 
 +</​items>​ 
 +XML;
  
-$url = '​https://​directo.gate.ee/​xmlcore/​this_is_the_worlds_greatest_company/​xmlcore.asp';​ 
  
 $ch = curl_init();​ $ch = curl_init();​
 +
 curl_setopt($ch,​ CURLOPT_HEADER,​ 0); curl_setopt($ch,​ CURLOPT_HEADER,​ 0);
 curl_setopt($ch,​ CURLOPT_RETURNTRANSFER,​ true); curl_setopt($ch,​ CURLOPT_RETURNTRANSFER,​ true);
 +curl_setopt($ch,​ CURLOPT_FOLLOWLOCATION,​ true);
 curl_setopt($ch,​ CURLOPT_URL,​ $url ); curl_setopt($ch,​ CURLOPT_URL,​ $url );
 curl_setopt($ch,​ CURLOPT_POST,​ 1); curl_setopt($ch,​ CURLOPT_POST,​ 1);
 +curl_setopt($ch,​ CURLOPT_POSTFIELDS,​ '​key='​.urlencode($key).'&​xmldata='​.urlencode($xmldata).'&​put=1&​what=item'​ );
  
-curl_setopt($ch,​ CURLOPT_POSTFIELDS,​ '​xmldata='​.urlencode($xmldata).'&​put=1&​what=invoice'​ );  
 $result = curl_exec($ch);​ $result = curl_exec($ch);​
 +curl_close($ch);​
  
-print '<textarea cols=80 rows=10>'​ . $result . '</​textarea>';+echo '<pre>';
  
-curl_close($ch);+print '</​pre><​textarea cols=80 rows=10>'​ . $result . '</​textarea>'​;
 </​code>​ </​code>​
 +
 +===Postman===
 +Väljund ja Sisend [[https://​www.postman.com/​|Postman]] keskkonna jaoks saab alla laadida ​
 +{{:​et:​directo.demo.postman_collection.json|siit}} ning siis importida Collectionina Postmani ning seal testida
 +
et/xmlcore.1440571104.txt.gz · Viimati muutnud: 2015/08/26 09:38 persoon ott