Directo XML datu apmaiņas apraksts

Jebkurai Directo DB ir iespējams konfigurēt datu apmaiņu, kas ļauj nodrošināt abpusēju datu plūsmu. Ir svarīgi ņemt vērā, ka datu apmaiņas saskarne nav standartizēta, bet tiek pielāgota katram gadījumam individuāli, lai atbilstu darba uzdevumā izvirzītajām prasībām.
Datu apmaiņas uzstādīšana ir saistīta ar ikmēneša abonēšanas maksu par xml moduli un izstrādes izmaksām, kas ir atkarīgas no uzdevuma sarežģītības, tāpēc ir vēlams savlaicīgi sazināties ar Directo pārstāvjiem, lai precizētu projekta izmaksas.

Neatkarīgi no projekta specifikas, ir daži principi, kas visos gadījumos ir vienādi:

• Datu formāts ir XML
• Datu kodējums ir UTF-8
• Transporta protokols ir HTTPS
• Informācijas iegūšanai izmanto GET metodi
• Datu ievietošanai izmanto POST metodi
• Datu plūsmu vienmēr iniciē ārējs avots, neatkarīgi no tā, vai dati tiks sūtīti vai pieprasīti
• Datu struktūru nosaka XSD shēma (ja tas ir iespējams, tad labāk lai vērtības būtu atribūtos, nevis elementos)

Dotie piemēri ir veidoti tikai datu apmaiņas pamatprincipu demonstrācijai!

GET pieprasījumam vienmēr ir vismaz trīs parametri:

• Get=1
• What=DATATYPE
• Key=PREDEFINEDKEY

Iespējamie datu tipi, derīgas atslēgas un pārējie parametri tiek noteikti katram uzdevumam individuāli.

Tāda veida izvadi bieži izmanto interneta veikali, piemēram, lai noskaidrotu pieejamos produktus un to atlikumus Directo noliktavā.

Piemērā lietotie URL ir tikai ilustratīvi un pat, ja šāds pieprasījums var rezultēties ar datu iegūšanu, dati ir fiktīvi un nav saistīti ar kāda klienta reālajiem datiem!

Šajā piemērā izmantosim parametru what=item un atslēgu 20DAF3F822B782AF12D1198C23F45604
Ar artikulu xsd shēmu var iepazīties šeit: ws_artiklid.xsd

Informācijas par visiem artikuliem pieprasījums: https://directo.gate.ee/xmlcore/demo_ee/xmlcore.asp?get=1&what=item&key=20DAF3F822B782AF12D1198C23F45604

Lai iegūtu informāciju par kādu konkrētu artikulu, piemēram, pēc artikula koda, mēs norādām papildus parametru code=0000 un tagad pieprasījums izskatīsies šādi: https://directo.gate.ee/xmlcore/demo_ee/xmlcore.asp?get=1&what=item&code=0000&key=20DAF3F822B782AF12D1198C23F45604

Datus sūta, izmantojot POST metodi un norādot vismaz trīs parametrus:

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

Šāda tipa ievade, piemēram, var tikt izmantota, lai replicētu kādu ārējās pārdošanas sistēmas rēķinu Directo.

Piemērā izmantotā adrese un xml saturs ir fiktīvi un nav izmantojami testēšanai, tā vienmēr ir jāveic reālajā konfigurācijā!

Pieņemsim, ka datu apmaiņas URL ir: https://directo.gate.ee/xmlcore/this_is_the_worlds_greatest_company/xmlcore.asp

Un datu struktūra ir šāda: xml_in_arved.xsd

Piemēram, xml var izskatīties šādi (ne visi iespējamie atribūti ir izmantoti):

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

Pieņemsim, ka datu ievietošana ir noritējusi veiksmīgi un atbilde ir šāds sinhronais xml:

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

Ja Result elementa Type atribūts nav vienāds ar 0, tad ir notikusi kāda kļūda un šādā gadījumā Desc parādīsies precizējoša informācija.

Piemēram, ja rēķins ar šādu numuru jau eksistē, tad atbildes ziņojums var būt šāds:

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

Bet ja vienā sūtījumā būtu bijuši vairāki rēķini:

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

Atbildes ziņojuma apstrāde ir būtiska, ja nav saņemts apstiprinājums par veiksmīgu datu ielādi, tad dati nav ievietoti un ir jāveic atkārtots mēģinājums, bet ne ātrāk kā pēc 60s.

$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);