WIP - HansaWorld Standard ERP REST API

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

Uzstadīšana

Sistēma → Iestatījumi → Papildus funkcijas Atķeksēt iestatījumus: ☑ Web REST API un, ja izmanto HTTP, ☑ Atļaut HTTP autentifikāciju.
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
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 attiecīgi 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:

Atgriezīs visus reģistra datus, kārtojot pēc MainKey.

<?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&#363;r&#275;js SIA</Addr0>
  <Addr1>Daugavgr&#299;vas iela 5</Addr1>
  <Addr2>R&#299;ga, LV-1022</Addr2>
  <Addr3>LATVIJA</Addr3>
  <OurContact></OurContact>
  <ClientContact>J&#257;nis Cirp&#275;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.

Burti ar diakritiskajām zīmēm tiek aizstāti ar HTML simbolu kodiem. ā → ā

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

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

GET

Atbildes uz visiem pieprasījumiem varam formatēt, izmantojot GET papildu parametrus:

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.

sort

Nosaka secību, pēc kura lauka atbildi kārtot. Ja laukam nav indekss pēc, kā kārtot, atgriezīs kļūdas paziņojumu.

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

range

Š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: - ">=" 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;
sort=CustCode&range=10100:10105 - atgriezīs rēķinus no 10100 līdz 10105;

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

fields

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.

Ja reģistra ierakstā ir lauks un matricas kolonna ar vienādu nosaukumu, piem., ORVc reģistrā Location, tad norādot to, atgriezīs gan ieraksta, gan rindas Noliktavas

filter

Atgriež ierakstus, kas atbilst filtram, 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 sagaida lielu atbildi, 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

in progress

deletes_after

in progress

Lai dabūtu ierakstu pēc SerNr vai jebkāda cita reģistra MainKey lauka, jāizmanto range, vienīgi šajā gadījumā pie sort jānorāda lauka nosaukums: sort=SerNr&range=23001

POST

PATCH

Datu rakstīšana ar REST API

JTE TODOs:

updates_after and deletes_after
Pārbaudīt GET fields funkcionalitāti uz tabulu
POST komandas
kā POST un PATCH spēj tikt galā ar diakritiskajām zīmēm vai arī saprast, kādu charsetu Hansa izmanto, vai arī saprast, kā pareizi pieprasījumā norādīt to
PATCH komandas - 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