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, Basic Auth - ☑ Atļaut HTTP autentifikāciju.
HTTPS ieslēdz caur Tehniskie parametri → Iestatījumi → Programmas statuss → sadaļa WWW, pirms tam gan servera mapē jābūt ielinkotai SSL sertifikātu mapei:
1. ieķeksēt ☑ HTTPS
2. norādīt web portu, HTTPS portu
3. Sertifikāts laukā norādīt domēna fullchain.pem failu
4. Privātā atslēga - privkey.pem failu
5. servera restarts
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
Tehniskie parametri (vecākās versijās Tīmekļa veikals) → Iestatījumi → Piekļuve funkcijām caur tīmekli
1. izveido rindiņu, kas izskatās apmēram šādi:
  Image Added
2. piemērā redzamā rindiņa atļaus jebkādus API savienojumus uz SERP sistēmu, kura linka sākums izskatīsies šādi - http://localhost:8085/api/
3. pārējos laukus var izmantot, lai ierobežotu pieeju šim API endpointam, piem., ļaujot tikai SSL savienojumus vai savienojumus no konkrētām IP.
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):

Otro reizi pieķeroties Rest API testēšanai, noskaidroju, ka ar cURL labāk sanāk. Postmanis kaut ko slepus vēl dara ar charsetiem, tādēļ sākotnēji nesanāca POSTot un PATCHot latviešu diakritiskās zīmes.

CURL īsumā

curl -X GET -u AB:Sample99 "http://localhost:8085/api/1/IVVc" -d "sort=SerNr&range=3900001" atgriezīs rēķinu ar numuru 3900001

-X nosaka pieprasījuma metodi;
-u - Basic Auth lietotāju un tā paroli;
pieprasījuma links pēdiņās (der gan ", gan ');
-d - satur linka parametrus arī pēdiņās, iekšā vērtībās var būt atstarpes, katru parametru atdala ar &.

Lietošana

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

...

Code Block

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

...

[..]

...

</

...

data>

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

...

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.

Info
Pēdējā testēšanā custom reģistri vispār nestrādā ja ar rest api. Info sekos

Info
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

sort

...

Nosaka secību, pēc kura lauka atbildi indeksa kārtot. Ja laukam nav indekss pēc, kā kārtot, atgriezīs kļūdas paziņojumu 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 atgriezīs visus rēķinus, kuros klientu numuri ir no 10100 līdz 10109, galus ieskaitot.

...

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

...

fields

Atgriezīs 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 Addr0 atgriezīs visus rēķinus tikai ar rēķina numuru, klienta kodu un nosaukumu.

...

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

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

...

offset un limit

Ja pēc pieprasījuma sagaida lielu atbildisagaidā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 izlaidīs pirmos 5 un ietvers otros 5 ierakstus no reģistra.

Var kombinēt ar sort.

...

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

in progress

deletes_after

in progress

Note
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
POST komandas
kā POST un PATCH spēj tikt 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 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

=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.

Note
Datu rakstīšana nestrādā uz blokveida reģistriem.

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ā.

Ja nepieciešams padot datus, kas satur kādus īpašus simbolus, kas var tikt pārkodēti (piemēram, atstarpe), tad nevar padot šīs vērtības kā URL parametrus, bet gan viss saturs ir padodams kā POST body (ar text/plain satura tipu).

Piemērs ar Postman:

Image Added

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.

Ja reģistra MainKey sastāda vairāku lauku kombinācija, piemēram, SVOSerVc - SerialNr + ItemCode (secībā), tad links būs šāds:

http://localhost:8085/api/1/SVOSerVc/1234/420324?set_field.Comment1=newtest2

Kur 1234 ir SerialNr un 420324 ItemCode.

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

Versions Compared

Old Version 16

New Version Current

Key

Uzstadīšana

CURL īsumā

Lietošana

Datu iegūšana

GET

PATCH

Datu rakstīšana ar REST API

JTE TODOs:

Datu rakstīšana

POST

PATCH

Page Comparison

Versions Compared

Old Version 16

New Version Current

Key

Uzstadīšana

CURL īsumā

Lietošana

Datu iegūšana

GET

PATCH

Datu rakstīšana ar REST API

JTE TODOs:

Datu rakstīšana

POST

PATCH