Bendras XML duomenų mainų sąsajos aprašymas

Jei pageidaujama, kiekvienoje Directo bazėje galima nustatyti duomenų mainų sąsają, įgalinančią dvipusį duomenų srautą. Svarbu atsiminti, kad sąsaja nėra prieinama pagal numatytuosius nustatymus, tačiau konfigūruojama kiekvienu konkrečiu atveju, atsižvelgiant į konkretaus užduočių rinkinio poreikius. Sąsajos įdiegimas yra apmokamas pagal kainoraštį, o apmokėjimo dydis priklauso nuo kiekviena kryptimi judančių duomenų tipų skaičiaus, todėl prieš pradedant darbą, būtina susisiekti su Directo prekybos atstovu ir susitarti dėl tikslių poreikių bei derinti projekto kainą.

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.
• Directo dokumentų numerių tipas yra integer, tai reiškia, kad didžiausias galimas skaičius yra 2147483647.
• Tuščios (NULL) reikšmės nebus įtraukiamos į XML su lauko pavadinimu. Tą patį darykite ir siųsdami duomenis į Directo - praleiskite laukus, kuriuose turi būti tuščių (NULL) reikšmių. Reikėtų vengti siųsti laukus su tuščia reikšme, kaip pavyzdžiui: customer_code = „“.

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

Serviso nuorodos yra pasiekiamos form/urlencoded POST metodu. Autorizacijai reikalingas raktas turi būti perduodamas POST metodu kintamajame KEY: 2852DD553B767B463C807ADB36B5BB2F siunčiant užklausą. Jei raktas neteisingas arba raktas siunčiamas neteisingu būdu, gaunamas atsakymas:

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

Pavyzdys naudojant cURL:

curl -v -d "key=2852DD553B767B463C807ADB36B5BB2F&what=item&get=1&ts=01.01.2021&code=000001" -H "Content-Type: application/x-www-form-urlencoded" -X POST "https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp"

Toliau pateikti pavyzdžiai turi būti laikomi tik apytiksliais ir svarbu atsiminti, kad konkrečioje kuriamoje sąsajoje beveik tikrai bus naudojamos kitokios schemos, URL, parametrai, apribojimai, žinutės atsakymai ir raktai nei pateiktos pavyzdyje. Jokiu būdu negarantuojama, kad šie URL iš tikrųjų atitiks užklausą. Jei užklausos metu duomenys yra gaunami, jie yra 100% fiktyvūs ir nesusiję su jokių tikrų įmonių duomenimis. Norėdami išbandyti, naudokite šią formą: https://login.directo.ee/xmlcore/demo_ee/webupload.html

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.

Šiame pavyzdyje naudojami what=item ir get=1. Visi filtrai galimi, jei schemoje yra atitinkamas laukas. Pavyzdžiui, „class“, „code“, „barcode“, „supplier“, „supplieritem“, „closed“, „ts“ straipsnių aprašomoji struktūros schema: https://login.directo.ee/xmlcore/demo_ee /ws_artiklid.xsd

Užklausa prekėms pagal išsaugojimo datą (ts = Time stamp): https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp?what=item&get=1&ts=01.01.2021

Laiko filtras taip pat gali naudoti laiką taip: & ts = 01.03.2021 12:30 / & ts = 01.03.2021%2012:30

Užklausos pavyzdys, norint gauti visų prekių sąrašą: https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp?get=1&what=item

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

https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp?get=1&what=customer&ts=01.01.2021

Filtro parinkčių pavyzdžiai: „code“, „loyaltycard“, „regno“, „email“, „phone“, „closed“, „ts“ pirkėjo struktūros schema: https://login.directo.ee/xmlcore/demo_ee/ws_customers.xsd

https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp?get=1&what=stocklevel

Filtro parinkčių pavyzdžius: „code“, „stock“, apibūdinanti sandėlio kiekio schema: https://login.directo.ee/xmlcore/demo_ee/ws_laoseis.xsdt

Duomenys siunčiami naudojant form/urlencoded POST metodą.

Užpildomi formos kintamieji:

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

Įvesties sąsajoje XML turi būti išsiųstas adresu https://login.directo.ee/xmlcore/demo_ee/xmlcore.asp POST su kintamaisiais put = 1, key = [appkey value], what = order (arba what = customer arba what = item) ir xmldata = [XML turinys] XML įvestis turi atitikti schemą.

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

Praktinis pavyzdys

Tokio tipo įvestis naudojama, pavyzdžiui, kai išorinėje sistemoje generuojami pardavimo užsakymai, kurie turi būti atspindėti Directo. Taip pat, pateikiamas pirkėjų schemos aprašymas.

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

Pavyzdinio serviso XSD schemą: http://wiki.directo.ee/_media/et/xml_in_arved.xsd.

Pavyzdinis XML:

<?xml version="1.0" encoding="utf-8"?>
<invoices>
  <invoice 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 sinchroniš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. Reikėtų vengti kelių užklausų siuntimo vienu metu.

Pirkėjo įvesties sąsaja:

Duomenys aprašyti schemoje https://login.directo.ee/xmlcore/demo_ee/xml_IN_kliendid.xsd . Duomenų registravimas yra toks pat kaip užsakymų registravimas. XML, kuris atitinka schemą, bet nenaudoja visų galimų atributų, gali atrodyti taip:

<?xml  version = "1.0"  encoding = "utf-8" ?> 
<customers >
   <customer  code = "Customer  code1 " name = "Name"  address1 = "address11"  address2 = "address21"  address3 = "address31"  email = " email1 "  regno = " regno1 "  class = " class1 "  type = " 1 "  > 
  </ customer >
  </ customers >

Parametrai, kuriuos reikia nurodyti:

• What – web serviso 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.
• Key - web serviso autorizacijos raktas.
• 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/this_is_the_worlds_greatest_company/xmlcore.asp">
 
	<input name="what" value="order">
 
	<input name="put" value="1">
 
	<input name="key" value="2852DD553B767B463C807ADB36B5BB2F">
 
	<textarea name="xmldata" rows="10"><orders><order 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ą galima kreiptis bet kokia kalba, jeigu ta programavimo kalba yra galimybė padaryti https request‘ą, pateikiame pavyzdį PHP kalba:

OUT

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

IN

$url = 'https://login.directo.ee/xmlcore/this_is_the_worlds_greatest_company/xmlcore.asp';
$key = '2852DD553B767B463C807ADB36B5BB2F';
 
$xmldata =  <<<XML
<?xml version="1.0" encoding="utf-8"?>
<invoice 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>
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=invoice' );
 
$result = curl_exec($ch);
curl_close($ch);
 
echo '<pre>';
 
print '</pre><textarea cols=80 rows=10>' . $result . '</textarea>';

Postman aplinkos išvestį ir įvestį galima atsisiųsti čia, tada importuoti kaip kolekciją į Postman ir ten išbandyti.