Erinevused

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

--- et:xmlcore [2015/08/26 09:38] – ott
+++ et:xmlcore [2025/09/02 09:03] (Hetkel kehtiv) – [Üldine] 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.
+Directo võimaldab igale kliendibaasile seadistada andmevahetusliidese, mis tagab turvalise ja kahepoolse andmeliikluse Directo ning väliste süsteemide vahel.
+Oluline on arvestada, et liidesed ei kuulu vaikimisi komplekti, vaid konfigureeritakse igale projektile individuaalselt vastavalt vajadustele.
+Liidese loomine, seadistamine ja arendamine on tasuline teenus, mille hind sõltub andmete mahu ja tüübi eripärast. Täpsemad tasud on toodud Directo avalikus [[https://directo.ee/hinnad#Liidesed| hinnakirjas ]]. Enne tööde alustamist tuleb kliendil pöörduda Directo projektijuhi poole, et täpsustada nõuded ning kooskõlastada tööde ulatus ja maksumus.
+Directo pakub lisaks kliendipõhistele lahendustele ka mitmeid **valmisliideseid**, mida saab kasutada kiiresti ja kuluefektiivselt:
+  * **[[et:wms_direct|WMS Direct ]]** – laojuhtimise liides (Warehouse Management System)
+  * **[[et:xml_direct|XML Direct]]** – andmevahetus XML-formaadis
+  * **[[et:bi_direct|BI Direct]]** – äristatistika ja aruandluse liides (Business Intelligence)
+  * **[[et:property_direct|Property Management Direct ]]** – kinnisvarahaldusliides
+Lisaks on saadaval veel teisigi valmisliideseid, mis katavad laialdase valiku kasutusstsenaariumeid.
+**Millal kasutada valmisliideseid ja millal kliendipõhiseid lahendusi?**
+**Valmisliidesed** sobivad hästi olukorras, kus:
+  * äriprotsess vastab juba olemasoleva lahenduse loogikale;
+  * soovitakse kiiret kasutuselevõttu ilma eriarendusteta;
+  * oluline on kuluefektiivsus ja standardlahenduse stabiilsus.
+**Kliendipõhised** liidesed sobivad juhul, kui:
+  * ettevõttel on spetsiifilised tööprotsessid või unikaalsed andmevahetuse nõuded;
+  * standardlahendus ei kata kõiki vajalikke andmetüüpe või töövooge;
+  * on vaja siduda Directo väga eripäraste või majasiseste süsteemidega.
+Sageli on praktiline lähenemine kombineeritud — kasutada olemasolevat valmisliidest standardsete funktsioonide jaoks ning täiendada seda kliendile kohandatud arendustega, et katta erivajadused.
 Sõltumata konkreetse liidestusprojekti spetsiifikast on teatud printsiibid, millega peab igal juhul arvestama.
@@ Rida 8: / Rida 34: @@
   * 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 64: @@
   * 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 75: @@
 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://directo.gate.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://directo.gate.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 156: @@
   * ''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="".
+===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
 <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>
-Oletame, et liidese URL on antud juhul https://directo.gate.ee/xmlcore/this_is_the_worlds_greatest_company/xmlcore.asp
+==Müügitellimuse sisend liides:==
+Andmeid kirjeldab skeem [[https://login.directo.ee/xmlcore/demo_ee/xml_IN_tellimused.xsd]]
-Andmeid kirjeldab schema {{:et:xml_in_arved.xsd|}}
+Skeemile vastav, aga sugugi mitte kõiki võimalikke atribuute kasutab XML võib välja näha näiteks selline:
-Schemale 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 186: @@
 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 196: @@
 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 230: @@
 ===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);
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+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 128: / Rida 250: @@
 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 140: / Rida 263: @@
 ===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);
+curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
 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