Integracijos principai:

• Duomenų formatas XML;
• Duomenų koduotė UTF-8;
• Metodas informacijai pasiekti HTTPS (sertifikatas viešai pripažįstamas);
• GET metodas naudojamas duomenims gauti;
• POST metodas yra naudojamas duomenis išsiųsti;
• Duomenų apsikeitimą visuomet inicijuoja išorinė šalis, nepriklausomai nuo apsikeitimo krypties;
• Į POST užklausą atsakoma sinchronizuotu XML pranešimu, kurio apdorojimas gali daryti įtaką sėkmingam procesui;
• Duomenų struktūra turi atitikti paruoštą XSD schemą. Pageidaujama reikšmes siųsti atributuose.

• Endpoint URL: https://login.directo.ee/xmlcore/demo_lt_153/xmlcore.asp (Jūsų sukurtam servisui pasikeis tik „demo_lt_153“ dalis).

GET metodo atveju bent 3 parametrai turi būti nurodyti:

• get=1
• what=SERVISO_KODAS
• key=SUGENERUOTAS_RAKTAS

Papildomi parametrai yra derinami individualiai pagal poreikį, integracijos derinimo metu.

Šio pavyzdžio atveju yra naudjamas what = „item“ ir key reikšmė yra „20DAF3F822B782AF12D1198C23F45604“. Esant poreikiui, galite peržiūrėti šio pavyzdinio serviso XSD schemą: ws_artiklid.xsd.

Užklausos pavyzdys, norint gauti visų prekių sąrašą:

https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp?get=1&what=item&key=20DAF3F822B782AF12D1198C23F45604

Užklausos pavyzdys, norint gauti konkrečios prekės informaciją:

https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp?get=1&what=item&code=0000&key=20DAF3F822B782AF12D1198C23F45604

Duomenys siunčiami naudojant POST metodą.

Užpildomi trys formos kintamieji:

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

Šis siuntimas naudojamas, pavyzdžiui, kai pardavimo sąskaita yra sugeneruojama išorinėje sistemoje, kurią reikia perduoti į „Directo“.

Šiame pavyzdyje nurodyti URL ir XML pvz. yra visiškai išgalvoti ir negali būti naudojami testavimui. Testavimas visada atliekamas realiame procese.

Tarkime, kad šiuo atveju URL pvz. https://login.directo.ee/xmlcore/this_is_the_worlds_greatest_company/xmlcore.asp

Pavyzdinio serviso XSD schemą: xml_in_arved.xsd.

Pavyzdinis XML:

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

Servisas sinchroninškai grąžins XML atsakymą su pranešimu kas įvyko.

Pavyzdžiui įkėlimas buvo sėkmingas ir Directo sąskaitos dokumentui priskyrė numerį 123:

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

Jeigu atributo „Type“ reikšmė nėra „0“, tuomet įkėlimo metu įvyko klaida. Tokiu atveju klaidos patikslinimas yra aprašytas atribute „Desc“.

Pavyzdžiui sąskaita numeriu 123 buvo atmesta, nes Directo sistemoje jau egzistavo sąskaitos dokumentas tokiu numeriu:

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

Vienu siuntimu galima įkelti kelias sąskaitas iš karto. Tokiu atveju rezultatas turi būti grąžinamas kiekvienai sąskaitai:

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

Svarbu sulaukti atsakymo apie sėkmingą įkėlimą. Jeigu tokio rezultato nesulaukiama arba yra gaunama klaida, siuntimą reikia pakartoti ne anksčiau kaip po minutės.

Parametrai, kuriuos reikia nurodyti:

• What – webserviso pavadinimas. Pvz.: “invoice” jei tai sąskaitos dokumentas.
• Put – statinis. Visada „1“ jei tai importas į Directo.
• Get - statinis. Visada „1“ jei tai eksportas iš Directo.
• Xmldata – dinaminis. Laukus reiktų derinti, kadangi servisas būtų programuojamas individualiai pagal poreikį.

Pavyzdinė užsakymo forma:

<form method="POST" action="https://login.directo.ee/xmlcore/demo_lt_153/xmlcore.asp">

	<input name="what" value="order">

	<input name="put" value="1">

	<textarea name="xmldata" rows="10"><orders><order key="asdf12345678" order_time="31.01.2018" number="111222" customer_code="FA" customer_name="TEST TEST pirkejas" customer_order="PORD11111" deliverydate="31.01.2018" paymentterm="10" customer_contact="customer contact" phone="phone" email="email@test.com <mailto:email@test.com> " email_notification="email notification" fax="fax" regno="regno" VATno="vatno" comment="comment" address1="Address1" address2="Address2" address3="Address3" deliveryaddress1="DAddress1" deliveryaddress2="DAddress2" deliveryaddress3="DAddress2" order_type="otype" order_status="ostatus"><line item="109819-0001" variant="Dydziai_a" price="100" discount="15" qty="10" unit="unit" description="item description" comment="comment" supplier="supp" rn="1"></line><line barcode="8714554972899" price="100" discount="15" qty="10" unit="unit" description="item description" comment="comment" supplier="supp" rn="2"></line></order></orders></textarea>

	<input TYPE="submit">

</form>

Į servisą kreiptis gali bet kokia kalba, jeigu ta programavimo kalba yra galimybė padaryti https request‘ą, pateikiame pavyzdį PHP kalba:

OUT

$url = 'https://login.directo.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_FOLLOWLOCATION, 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>';
      }
}

IN

$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://login.directo.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, 'xmldata='.urlencode($xmldata).'&put=1&what=invoice' ); 
$result = curl_exec($ch);
 
print '<textarea cols=80 rows=10>' . $result . '</textarea>';
 
curl_close($ch);