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 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:
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:
Kliendipõhised liidesed sobivad juhul, kui:
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.
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
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=1what=ANDMELIIKkey=PREDEFINEDKEYja 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=1what=ANDMELIIKxmldata=<?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>';