XML andmevahetusliidese üldine kirjeldus

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 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.

• Andmete formaat on XML
• Andmete kodeering on UTF-8
• Transpordiprotokoll on HTTPS (avalikult tunnustatud sertifikaadiga)
• Liidesele ligipääsuks 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

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

 <result type="5" desc="Unauthorized"/> 

Näide käsurealt cURL kasutamisel:

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'

Allpooltoodud näiteid tuleb käsitleda ainult umbkaudsete juhistena ja arvestada, et konkreetses loodavas liideses on peaaegu kindlasti kasutusel näites toodutest erinevad

• schemad
• URLid
• Parameetrid, piirangud
• Vastussõnumid
• Võtmed

Testimiseks kasutage seda vormi: https://login.directo.ee/xmlcore/demo_ee/webupload.html

Andmete pärimine käib POST meetodil GET parameetriga ning alati on täidetud vähemalt kolm parameetrit:

• get=1
• what=ANDMELIIK
• key=PREDEFINEDKEY

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).

Seda tüüpi väljundeid kasutab tihti näiteks veebipood, et klientide, toodete ja toodete saadavuse infot Directost poodi laadida.

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.

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):

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'

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:

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' \

Üksiku toote päring, toote koodi järgi, lisaparameeter code=0000:

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'

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'

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

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' \

Näidis filtrite võimalused:„code“,„stock“ Laoseisude struktuuri kirjeldav skeem: https://login.directo.ee/xmlcore/demo_ee/ws_laoseis.xsd

Andmete saatmine käib POST meetodil, form/urlencoded liidese URLi suhtes.

Täidetud on kolm vormimuutujat:

• put=1
• what=ANDMELIIK
• xmldata=<?xml version=„1.0“ encoding=„utf-8“?><PAYLOAD>

Sisendliideses tuleb XML postitata aadressile: 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=„“.

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

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.

Andmeid kirjeldab skeem https://login.directo.ee/xmlcore/demo_ee/xml_IN_tellimused.xsd

Skeemile vastav, aga sugugi mitte kõiki võimalikke atribuute kasutab XML võib välja näha näiteks selline:

<?xml version="1.0" encoding="utf-8"?>
<orders>
  <order number="1" customercode="customercode1" customername="customername1" date="1900-01-01T01:01:01+02:00">
    <rows>
      <row item="item1" description="description1" price="1" quantity="1" sum="1" rn="1" />
      <row item="item2" description="description2" price="0" quantity="1" sum="0" rn="2" />
    </rows>
  </order>
 </orders>

Postitusele vastab liides sünkroonse XML sõnumiga, kust saab teada, mis juhtus.

Näide, postitus oli edukas ja Directosse võeti vastu müügitellimuse number 1:

<?xml version="1.0" encoding="UTF-8" ?> 
<results>
  <Result Type="0" Desc="OK" docid="1" doctype="ORDER" submit="Orders" /> 
</results>

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, tellimuse number 1 vastuvõtmisest keelduti, kuna sellise numbriga tellimus oli Directos juba olemas:

<?xml version="1.0" encoding="UTF-8" ?> 
<results>
  <Result Type="1" Desc="Duplicate" docid="1" doctype="ORDER" submit="Orders" /> 
</results>

Ühest pakis võib olla korraga ka mitu tellimust, igaühe kohta tuleb omaette Result:

<?xml version="1.0" encoding="UTF-8" ?> 
<results>
  <Result Type="1" Desc="Duplicate" docid="1" doctype="ORDER" submit="Orders" /> 
  <Result Type="0" Desc="OK" docid="2" doctype="ORDER" submit="Orders" /> 
</results>

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.

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:

<?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>

$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_POSTFIELDS, 'key='.urlencode($key) . '&what=item&get=1&ts=01.01.2021&code=000001' ); 
curl_setopt($ch, CURLOPT_POST, 1);
 
$result = curl_exec($ch);
 
header('Content-Type: text/html; charset=utf-8');
 
print '<textarea cols=80 rows=10>' . $result . '</textarea>';
 
$data = new SimpleXMLElement($result);
 
print '<pre>';
print_r($data);
foreach ($data->item as $item) {
	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>';
	}
}

$url = 'https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp';
$key = '2852DD553B767B463C807ADB36B5BB2F';
 
$xmldata = <<<XML
<?xml version="1.0" encoding="utf-8"?>
<items>
  <item code="LMP0001" name="Lambikas" class="LAMP" barcode="123456789" salesprice="11.25" description="See on suur lamp" >
    <datafields>
      <data code="ART_VARV" content="Punane" />
      <data code="VEEBIS" content="Jah" />
    </datafields>
  </item>
</items>
XML;
 
 
$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' );
 
$result = curl_exec($ch);
curl_close($ch);
 
echo '<pre>';
 
print '</pre><textarea cols=80 rows=10>' . $result . '</textarea>';

Väljund ja Sisend Postman keskkonna jaoks saab alla laadida siit ning siis importida Collectionina Postmani ning seal testida