Izmantotā SERP versija ir 8.5 2019-06-05 build 85310221, testēts, izmantojot Postman.

Uzstadīšana

1. Sistēma → Iestatījumi → Papildus funkcijas Atķeksēt iestatījumus: ☑ Web REST API un, ja izmanto HTTP, ☑ Atļaut HTTP autentifikāciju.

2. REST API lietotājam (Sistēma → Reģistri → Personas laukā Personu grupas) izveido jaunu vai piešķirt kādu esošo Personu grupu (Sistēma → Iestatījumi → Personu grupas) ar tiesībām:

   Darbība	Rest API	Pilns	0

3. API pieprasījumi tiek sūtīti uz http://localhost:8085/api/1/IVVc , kur:

   1. localhost:8085 ir links uz SERPu, ja manuāli norādām portu - izmantojam HTTP vai HTTPS;

   2. api/ norāda, ka izmantos REST API;

   3. 1/ norāda uz kompānijas kodu no kompāniju iestatījumiem;

   4. IVVc šajā gadījumā ir Rēķinu reģistrs, bet tur var norādīt jebkuru, arī custom vai block reģistru, ar kuru vēlas strādāt;

Postman sadaļā Authorization izvēlēties opciju Basic Auth un ievadīt tās Personas datus, kura ir Personu grupā ar Rest API tiesībām (2. punkts):

Lietošana

Laikā, kad top raksts, Hansa apgalvo, ka atbalsta GET, POST un PATCH REST API komandas.

• GET iegūst no datubāzes kādus noteiktus datus
• POST var izveidot jaunus ierakstus
• PATCH - labo esošos ierakstus.

API atbildes uz pieprasījumiem izskatās šādi:

<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<data register="IVVc" sequence="16784" systemversion="8.5.28.1014">
 <IVVc>
  <SerNr>23001</SerNr>
  <InvDate>2003-10-20</InvDate>
  <CustCode>10101</CustCode>
  <Math></Math>
  <PayDate>2003-10-30</PayDate>
  <Addr0>Dūrējs SIA</Addr0>
  <Addr1>Daugavgrīvas iela 5</Addr1>
  <Addr2>Rīga, LV-1022</Addr2>
  <Addr3>LATVIJA</Addr3>
  <OurContact></OurContact>
  <ClientContact>Jānis Cirpējs</ClientContact>
  <ExportFlag>0</ExportFlag>
  <PayDeal>10</PayDeal>
  <OrderNr>23003</OrderNr>
  <Prntdf>1</Prntdf>
  <OKFlag>1</OKFlag>
  [..]
  <rows>
   <row rownumber="0">
    <stp>1</stp>
    <ArtCode>1065941I</ArtCode>
    <Quant>2</Quant>
    <Price>17.53</Price>
    <Sum>35.06</Sum>
    <vRebate></vRebate>
    <SalesAcc>6110</SalesAcc>
    <Objects>10</Objects>
    [..]
   </row>
   [..]
  </rows>
 </IVVc>
 [..]
</data>

Piemērā, tika izmantots vienkāršs GET pieprasījums - http://localhost:8085/api/1/IVVc , kas atgrieza visus rēķinus.

Visām atbildēm būs līdzīgs headeris ar <xml> tagu un visi dati tiks iekļauti <data> tagos.

Vietas taupīšanas nolūkā dati ir izņemti.

Pieprasījumiem iespējams norādīt papildus parametrus:

Piem., http://localhost:8085/api/1/IVVc?sort=CustCode&fields=SerNr,CustCode,Addr0

Datu iegūšana

GET

Atbildes uz visiem pieprasījumiem varam formatēt, izmantojot GET papildu parametrus, kurus savā starpā var brīvi kombinēt:

• sort - nosaka secību;
• range - var izvēlēties kādu ierakstu diapozonu pēc izvēlētā sort parametra skatīt;
• fields - nosaka laukus, kurus iekļaut atbildē;
• filter - atgriež ierakstus, kuri atbilst filtram;
• offset un limit - var sadalīt API atbildi;
• updates_after - atgriež ierakstus, kas ir mainīti pēc dotā sekvences skaitļa;
• deletes_after - atgriež ierakstus, kas ir dzēsti pēc dotā sekvences skaitļa.

GET metode strādā arī uz custom laukiem.

sort

Nosaka secību, pēc kura indeksa kārtot. MainKey indekss ir lauka nosaukums.

Piem., http://localhost:8085/api/1/IVVc?sort=CustCode 

range

Atgriež noteiktu diapozonu ierakstus. Šim parametram obligāti vajag izmantot arī sort parametru, lai noteiktu, kuram indeksam tieši vajag šo diapozonu.

Piem., http://localhost:8085/api/1/IVVc?sort=CustCode&range=10100:10109 atgriezīs visus rēķinus, kuros klientu numuri ir no 10100 līdz 10109, galus ieskaitot.

• sort=CustCode&range=10100:10105 - atgriezīs rēķinus no 10100 līdz 10105;
• sort=CustCode&range=10100: - ">=" ekvivalents, atgriezīs rēķinus, kam klients ir 10100, 10101, 10102 utt.;
• sort=CustCode&range=10100 - atgriezīs tikai tos rēķinus, kam būs norādītais.

Tā kā range izmanto sort indeksus, strādā ļoti ātri.

fields

Katram ierakstam atgriezīs tikai šos laukus. Ja nenorāda, tad atgriež ierakstus ar visiem laukiem.

Piem., http://localhost:8085/api/1/IVVc?fields=SerNr,CustCode,Addr0  atgriezīs visus rēķinus tikai ar rēķina numuru, klienta kodu un nosaukumu.

Var norādīt arī matricas kolonnu nosaukumus.

filter

Atgriež ierakstus, kas atbilst filtra laukiem, var norādīt vairākus.

Piem., http://localhost:8085/api/1/IVVc?filter.CustCode=10100 atgriezīs tikai rēķinus ar šo klientu.

Strādā lēnāk par range, jo neizmanto indeksus.

offset un limit

Ja pēc pieprasījuma sagaidāma liela atbilde, to ir iespējams sadalīt.

• offset norāda pie kura ieraksta sāks veidot atbildi
• limit norāda maksimālo ierakstu skaitu atbildē

Piem., http://localhost:8085/api/1/IVVc?offset=5&limit=5 izlaidīs pirmos 5 un ietvers otros 5 ierakstus no reģistra.

updates_after

Atgriezīs tikai tos ierakstus, kas ir mainīti pēc padotā sekvences numura.

Piem., http://localhost:8085/api/1/IVVc?updates_after=16201

deletes_after

Atgriezīs to ierakstus, kas ir dzēsti pēc padotā sekvences numura. Par sekvences numuriem zemāk.

Piem., http://localhost:8085/api/1/IVVc?updates_after=16213

Datu rakstīšana

Datus rakstīšanai pastāv 2 parametri:

• set_field._______ - norāda lauka vērtību, aiz punkta norāda lauka nosaukumu;
• set_row_field.#._______ - norāda rindas lauka vērtību, aiz punkta norāda rindas numuru (sāk skaitīt no 0), tālāk lauka nosaukumu.

POST

Ar POST metodi var izveidot jaunus ierakstus.

Piem.,  http://localhost:8085/api/1/IVVc?set_field.SerNr=99999&set_field.CustCode=10101&set_row_field.0.ArtCode=10&set_row_field.0.Quant=7 - klientam 10101 izveidos rēķinu Nr. 99999 ar 7 artikuliem Nr.10 pirmajā rindā.

PATCH

Ar PATCH metodi rediģē esošu ierakstu. Esošajam ierakstam piekļūst jau izsaukuma URL norādot MainKey lauka vērtību.

Piem., http://localhost:8085/api/1/IVVc/99999?set_field.CustCode=20202&set_row_field.0.Quant=9 - rēķinam Nr. 99999 nomainīs klientu uz 20202 un pirmās rindas artikulu skaitu uz 9.

Sekvences numuri

Katrs REST API pieprasījums iekš <data> taga atgriež numuru sequence, kuri pieaug kaut kā. To var izmantot, atceroties katra pieprasījuma atbildes sekvenci un, kad no jauna kaut kādi dati jāiegūst, var izmantot šo skaitli inkrementālajam importam.

<data register="ORVc" sequence="16197" sort="SerNr" key="SerNr" systemversion="8.5.31.221">

JTE TODOs:

• updates_after and deletes_after
• kā POST un PATCH tiekt galā ar diakritiskajām zīmēm (NETIEK) vai arī saprast, kādu charsetu Hansa izmanto, vai arī saprast, kā pareizi pieprasījumā norādīt to
• PATCH - interesanti būtu paskatīties, ko API dara ar ierakstiem, kuros jau ir diakritiskās zīmes
• kā PATCH tiek galā ar custom un blokveida reģistriem
• saprast, kā šo var darīt bez Postman