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.

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)
• Andmete pärimisel kasutatakse GET 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

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

GET päringu korral on alati 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.

Seda tüüpi väljundit kasutab tihti näiteks veebipood, et toodete ja nende 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 võtme väärtus on 20DAF3F822B782AF12D1198C23F45604. Soovi korral võib tutvuda struktuuri kirjeldava schemaga ws_artiklid.xsd

Terve tootebaasi päring: https://directo.gate.ee/xmlcore/demo_ee/xmlcore.asp?get=1&what=item&key=20DAF3F822B782AF12D1198C23F45604

Ü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

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>

Seda tüüpi sisendit kasutatakse näiteks sellisel puhul, kui mingis välises süsteemis genereeritakse müügiarveid, mida on vaja Directos kajastada.

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.

Oletame, et liidese URL on antud juhul https://directo.gate.ee/xmlcore/this_is_the_worlds_greatest_company/xmlcore.asp

Andmeid kirjeldab schema xml_in_arved.xsd

Schemale 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"?>
<invoices>
  <invoice AppKey="1234567879012345678790" InvoiceNr="123" 
	InvoiceDate="2015-06-07" CustomerCode="CUST001">
    <lines>
      <line ProductID="KILLERPRODUCT" Quantity="3" UnitPriceWoVAT="123.45"/>
      <line ProductID="FREESAMPLE" Quantity="1" UnitPriceWoVAT="0.00"/>
    </lines>
  </invoice>
</invoices>

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:

<?xml version="1.0" encoding="UTF-8" ?> 
<results>
  <Result Type="0" Desc="OK" docid="123" doctype="INVOICE" submit="Invoices" /> 
</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, arve number 123 vastuvõtmisest keelduti, kuna sellise numbriga arve oli Directos juba olemas:

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

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

<?xml version="1.0" encoding="UTF-8" ?> 
<results>
  <Result Type="1" Desc="Duplicate" docid="123" doctype="INVOICE" submit="Invoices" /> 
  <Result Type="0" Desc="OK" docid="124" doctype="INVOICE" submit="Invoices" /> 
</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.

$url = 'https://directo.gate.ee/xmlcore/demo_ee/xmlcore.asp?get=1&what=item&key=20DAF3F822B782AF12D1198C23F45604';
 
$ch = curl_init();
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL, $url );
curl_setopt($ch, CURLOPT_POST, 0);
 
$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>';
 
foreach ($data->items->item as $item) {
	print $item['Code'] . chr(9) .  '<b>' . $item['Name'] . '</b>' . chr(9) .  $item['Class'] . '<br>';
	foreach ($item->datafields->data as $df ) {
		print chr(9) . $df['code'] . ':' . $df['content'] . '<br>';
	}
}

$xmldata = '<'.'?xml version="1.0" encoding="UTF-8"?>
<invoice AppKey="1234567879012345678790" InvoiceNr="123" 
	InvoiceDate="2015-06-07" CustomerCode="CUST001">
    <lines>
      <line ProductID="KILLERPRODUCT" Quantity="3" UnitPriceWoVAT="123.45"/>
      <line ProductID="FREESAMPLE" Quantity="1" UnitPriceWoVAT="0.00"/>
    </lines>
</invoice>';
 
$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_URL, $url );
curl_setopt($ch, CURLOPT_POST, 1);
 
curl_setopt($ch, CURLOPT_POSTFIELDS, 'xmldata='.urlencode($xmldata).'&put=1&what=invoice' ); 
$result = curl_exec($ch);
 
print '<textarea cols=80 rows=10>' . $result . '</textarea>';
 
curl_close($ch);