Erinevused

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

--- et:xmlcore [2020/10/02 08:33] – [Praktiline näide - artiklite väljund] ott
+++ et:xmlcore [2024/04/16 09:19] (Hetkel kehtiv) – [Andmete pärimine Directost ehk väljund] toomas
@@ Rida 1: / Rida 1: @@
 ======XML andmevahetusliidese üldine kirjeldus======
 =====Ü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äälestustasuga, mille 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 tasuline, vastavalt [[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.
@@ Rida 8: / Rida 8: @@
   * Andmete kodeering on UTF-8
   * 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
   * 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
+  * 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 --location 'https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data-urlencode 'key=2852DD553B767B463C807ADB36B5BB2F' \
+--data-urlencode 'get=1' \
+--data-urlencode 'what=item' \
+--data-urlencode 'ts=01.01.2024'
+</code>
 =====Näited=====
@@ Rida 21: / Rida 38: @@
   * Vastussõnumid
   * Võtmed
+Testimiseks kasutage seda vormi: https://login.directo.ee/xmlcore/demo_ee/webupload.html
 ====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''
   * ''what=ANDMELIIK''
@@ Rida 30: / Rida 49: @@
 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>
-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):
+<code>
+curl --location 'https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data-urlencode 'key=2852DD553B767B463C807ADB36B5BB2F' \
+--data-urlencode 'get=1' \
+--data-urlencode 'what=item' \
+--data-urlencode 'ts=01.01.2024'
+</code>
+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:
-https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp?get=1&what=item&key=20DAF3F822B782AF12D1198C23F45604
+<code>
+curl --location 'https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data-urlencode 'key=2852DD553B767B463C807ADB36B5BB2F' \
+--data-urlencode 'get=1' \
+--data-urlencode 'what=item' \
+</code>
 Üksiku toote päring, toote koodi järgi, lisaparameeter ''code=0000'':
-https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp?get=1&what=item&code=0000&key=20DAF3F822B782AF12D1198C23F45604
+<code>
+curl --location 'https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data-urlencode 'key=2852DD553B767B463C807ADB36B5BB2F' \
+--data-urlencode 'get=1' \
+--data-urlencode 'what=item' \
+--data-urlencode 'code=0000'
+</code>
+==Klientide väljund:==
+<code>
+curl --location 'https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data-urlencode 'key=2852DD553B767B463C807ADB36B5BB2F' \
+--data-urlencode 'get=1' \
+--data-urlencode 'what=customer' \
+--data-urlencode 'ts=01.01.2024'
+</code>
+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:==
+<code>
+curl --location 'https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data-urlencode 'key=2852DD553B767B463C807ADB36B5BB2F' \
+--data-urlencode 'get=1' \
+--data-urlencode 'what=stocklevel' \
+</code>
+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====
@@ Rida 52: / Rida 130: @@
   * ''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 kasutatavad. Testimine 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 kajastada. Lisaks 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 kasutatavad. Testimine 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>
 <?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>
@@ Rida 78: / Rida 160: @@
 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>
 <?xml version="1.0" encoding="UTF-8" ?>
 <results>
-  <Result Type="0" Desc="OK" docid="123" doctype="INVOICE" submit="Invoices" />
+  <Result Type="0" Desc="OK" docid="1" doctype="ORDER" submit="Orders" />
 </results>
 </code>
@@ Rida 88: / Rida 170: @@
 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 1 vastuvõtmisest keelduti, kuna sellise numbriga tellimus oli Directos juba olemas:
 <code xml>
 <?xml version="1.0" encoding="UTF-8" ?>
 <results>
-  <Result Type="1" Desc="Duplicate" docid="123" doctype="INVOICE" submit="Invoices" />
+  <Result Type="1" Desc="Duplicate" docid="1" doctype="ORDER" submit="Orders" />
 </results>
 </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>
 <?xml version="1.0" encoding="UTF-8" ?>
 <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>
 </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.
+==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 204: @@
 ===Väljund===
 <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();
 curl_setopt($ch, CURLOPT_HEADER, 0);
@@ Rida 118: / Rida 212: @@
 curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
 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);
@@ Rida 129: / Rida 224: @@
 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 ) {
 		print chr(9) . $df['code'] . ':' . $df['content'] . '<br>';
 	}
 }
 </code>
@@ Rida 141: / Rida 237: @@
 ===Sisend===
 <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();
 curl_setopt($ch, CURLOPT_HEADER, 0);
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
@@ Rida 159: / Rida 260: @@
 curl_setopt($ch, CURLOPT_URL, $url );
 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);
+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>
+===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