Atjaunots 16. decembris 2025

Kādā veidā jānoformē API pieprasījumi?

REST API – v2.0 (sākot ar programmas versiju 8.4)

1. Drošība

API izmanto lietotāja piekļuves tiesības.
Lietotājam jābūt spējīgam parastajā klientā atvērt konkrēto reģistru — tas nozīmē, ka viņam jābūt piekļuvei gan modulim, kurā reģistrs atrodas, gan pašam reģistram.
Reģistriem, kuri nav pieejami nevienā modulī (piemēram, RHistVc, MailVc), ir nepieciešama pielāgošana, lai tie tiktu pievienoti kādam modulim.
Lietotājam jāautentificējas, izmantojot OAuth.

• Pēc noklusējuma HAL funkcijas ir izslēgtas
• Pēc noklusējuma piekļuve API prasa pieslēgšanos
• Pārējiem resursiem piekļuve ir publiska

Ja lietotājam ir ierobežotas tiesības redzēt noteiktus reģistra laukus, piemēram, „Rādīt pašizmaksu”, tad, izmantojot API, viņš joprojām varētu nolasīt šos laukus, un tāpēc viņam šādai piekļuvei nevajadzētu būt. Tas darbojas tāpat kā eksportēšanas gadījumā.

2. Priekšnosacījumi

1. Sistēmā ir jānorāda web ports. To var paveikt modulī Tehniskie parametri > Reģistri > Programmas statuss > WWW:

Web ports ir nepieciešams, lai nodrošinātu komunikāciju, izmantojot HTTP vai HTTPS protokolus.
Tie nav jājauc ar Hansa portu, kas tiek izmantots saziņai starp klienta programmu un serveri.
Web portu var mainīt, neietekmējot pārējās programmas darbības.
Tāpat ir jāpārliecinās, ka izmantotais ports ir atvērts serverī — ugunsmūri parasti atļauj datu plūsmu tikai caur noteiktiem portiem, un ne visi ir publiski pieejami.
Ir svarīgi pārliecināties, ka izvēlētais ports jau netiek izmantots citā servera procesā.

Svarīgi! Sertifikātus Excellent serverī instalē Excellent administrators. Ja vēlaties pieprasījumus novirzīt no sava domēna, jums ir jāuzticas mums un jānodrošina attiecīgie sertifikāti (tostarp privātā atslēga).

2. API iestatījumi var tikt aizsargāti ar moduļa Tehniskie parametri > Iestatījumi > Piekļuve funkcijām caur tīmekli, līdz ar to klientam jābūt aktivizētam šim modulim. Iestatījumā nepieciešams manuāli izveidot sekojošu ierakstu:

Funkcija: API
Publisks: Pieslēdzies lietotājs
SSL: Jā
Sesija: Nē
Atļautie IP: ir jāaizpilda gadījumā, ja vēlaties atļaut veikt API pieprasījumus tikai noteiktām sistēmām. Ja nepieciešams norādīt vairākas IP adreses, tās varat ievadīt laukā, atdalot ar komatu. Piemērs: 90.191.43.252,213.35.184.82.

3. Sagatavošana un konfigurācija

1. Modulī Sistēma > Iestatījumi > Papildu funkcijas > jāatzīmē izvēles rūtiņa “Web Rest API”, lai API aktivizētu.

2. Lietotājam ir jāpiešķir piekļuves tiesības (Sistēma > Iestatījumi > Personu grupas) darbībai Rest API.

Iesakām nodefinēt atsevišķu Personu grupu tikai API piekļuvei – tas ļaus šīs tiesības piešķirt gan atsevišķiem, speciāli izveidotiem API lietotājiem sistēmā, gan esošiem sistēmas lietotājiem, papildus viņu jau esošajām piekļuves tiesībām.

3. Pēc visu iepriekšminēto iestatījumu veikšanas ir nepieciešams restartēt serveri.

4. Kā jānoformē API pieprasījumi?

Pamatpieprasījuma piemērs izskatās šādi:

https:hostname:port/api/1/IVVc

• hostname — servera IP adrese vai domēna nosaukums;
• port — servera ports (HTTPS);
• api — obligāta daļa URL (vienmēr “api”);
• 1 — kompānijas kods Kompāniju reģistrā (šajā gadījumā — kompānija ar kodu 1);
• IVVc — reģistra nosaukums (dotajā piemērā: “Realizācijas rēķini”).

Šis konkrētais pieprasījums iegūst visus Realizācijas rēķinus no kompānijas ar kodu 1. Ja vēlaties līdzīgā veidā iegūt informāciju, piemēram, par bāzes valūtām, tad ir jāizmanto pieprasījums:

https://hostname:port/api/1/BaseCurBlock

5. Datu formāts

Pieprasījumu datu formāti un saņemto datu formāti ir vienādi un stingri fiksēti:

• kā decimāldaļas atdalītājs ir jāizmanto “.” (punkts);
• tūkstošu atdalītājs netiek izmantots;
• datumi ir ISO formātā GGGG-MM-DD (gads, mēnesis, diena);
• ? (jautājuma zīme) tiek ievadīta pēc reģistra definēšanas, ja ir vēlēšanās precizēt filtrus;
• & tiek izmantots starp dažādiem filtriem.

6. Parametri, ko vari norādīt API pieprasījumā

Reālās parametru vērtības, kas tiek izmantotas pieprasījumos (piemēram, izmantotā atslēga/ID un diapazons, servera versija u.c.), rezultātos tiek uzrādītas kā datu lauku atribūti (“data tag”). Tālāk ir sniegti parametru piemēri.

sort – šķirošanas parametrs sakārto saņemtās kartes pēc norādītā datu lauka. Pieprasījuma rezultātos tiek atspoguļots arī izmantotā indeksa nosaukums. Šķirošanu ir iespējams veikt tikai pēc kartes galvenes laukiem. Vienlaicīgi ir iespējams veikt šķirošanu tikai pēc viena lauka pie nosacījuma, ka šim nolūkam ir piemērots indekss. Ja piemērota indeksa nav, tad pieprasījums rezultātus nesniedz. Lauka nosaukuma gadījumā ir svarīgi lielie un mazie burti. Piemērs (pieprasījums no Realizācijas rēķinu reģistra, šķirošana veikta pēc klienta koda):
https://hostname/api/1/IVVc?sort=CustCode

range – diapazona parametra izmantošanai ir jāizmanto arī šķirošanas parametrs. Diapazons veic pieprasījumu tikai attiecībā uz tām kartēm, kurās šķirojamā lauka vērtība ietilpst norādītajā diapazonā. Rezultātos tiek iekļautas arī tās vērtības, kas vienādas ar diapazona sākuma un beigu vērtībām. Diapazona sākuma un beigu vērtības atdala ar “:” (kolu). Ir atļauti arī tādi pieprasījumi, kuros ir norādīta tikai diapazona sākuma vai beigu vērtība. Ja pieprasījumā tiek izmantota tikai viena konkrēta vērtība (bez kola), tad tiek izsniegtas tikai tās kartes, kas atbilst šai konkrētajai vērtībai.

1. piemērs (tiek izsniegti Realizācijas rēķini, kuros klientu kodi ir diapazonā no 10101 līdz 10104):
   https://hostname/api/1/IVVc?sort=CustCode&range=10101:10104
2. piemērs (tiek izsniegti Realizācijas rēķini, kuros klientu kodi ir diapazonā no 10104 līdz pēdējam klientam):
   https://hostname/api/1/IVVc?sort=CustCode&range=10104:
3. piemērs (tiek izsniegti pārdošanas rēķini, kuros ir tikai klienta kods 10104):
   https://hostname/api/1/IVVc?sort=CustCode&range=10104

Diapazona parametrs ir ātrs, jo tas izmanto indeksu.

fields – lauku parametrs nosaka, kuri lauki tiek iekļauti rezultātā. Laukus atdala ar komatiem. Ja parametrs nav norādīts, tad rezultātos tiek ņemta informācija no visiem laukiem. Ja kartes/dokumenta galvenē un rindās ir tāda paša nosaukuma lauks, tad rezultātos tiek iekļauta informācija no abiem. Ja netiek pieprasīts neviens rindu lauks, tad rezultātos netiek atspoguļota nekāda rindu informācija (rindu numuri u.tml.).
Piemērs (tiek izsniegti Realizācijas rēķini tikai ar rēķina numuru:
https://hostname/api/1/IVVc? fields=SerNr

filter – Datus var filtrēt, izmantojot šo parametru. Filtrs ir ievērojami lēnāks nekā diapazons, jo tas neizmanto indeksus un veic meklēšanu visās kartēs. Izmantojot diapazona parametru, filtrs iziet cauri tikai tām kartēm, kuras atrodas diapazonā. Tāpēc ir ieteicams izmantot pēc iespējas precīzāku diapazona iestatījumu un citus filtrus.
Piemērs:
https://hostname/api/1/IVVc?filter.CustCode=10104

• Uz katru lauku drīkst izmantot tikai vienu filtru
• Izmantojot dažādus laukus, var izmantot vairākus filtrus
• Līdzīgā veidā filtri var izmantot vērtību diapazonus, arī tad, ja ir noteikts tikai diapazona sākums vai beigas.
• Filtri darbojas tikai ar karšu/dokumentu galvenes datu laukiem.
• Filtrēšana saraksta laukos (piemēram, Objektu gadījumā) tiek veikta visas simbolu virknes apmērā. Piemēram: filtrs.Objects = AB neietvers rezultātu “AB, D10101”

Piemērs (tiek izsniegti rēķini, kuru gala summa ir diapazonā no 100 līdz 1000 un kuros klientu kodi ir diapazonā no 10100 līdz 10200):
https://hostname/api/1/IVVc?filter.CustCode=10100:10200&Sum4=100:1000

offset and limit – ja pieprasījuma rezultāts ir lielāks nekā API lietotājs var apstrādāt viena pieprasījuma ietvarā, tad rezultātus var sadalīt mazākās daļās. “offset” izlaiž pieprasījuma rezultātos noteiktu skaitu dokumentu. “limit” ierobežo kopējo skaitu pieprasījuma rezultātos.

Piemērs (tiek izsniegti pirmie 15 Realizācijas rēķini ar 3 dažādiem pieprasījumiem):
https://hostname/api/1/IVVc?offset=0&limit=5
https://hostname/api/1/IVVc?offset=5&limit=5
https://hostname/api/1/IVVc?offset=10&limit=5

“offset” un “limit” var izmantot kopā ar visiem citiem parametriem.

updates_after – izsniedz visas kartes/dokumentus, kas ir atjaunoti pēc noteiktā kārtas numura. Kārtas numurs tiek izsniegts katra pieprasījuma gadījumā (sequence=”x”), un vēlāk to var izmantot ar parametru “updates_after”.
Piemērs:
https://hostname/api/1/IVVc?updates_after=5000
deletes_after – izsniedz visus ierakstis, kas ir dzēsti pēc noteiktā kārtas numura. Kārtas numurs tiek izsniegts katra pieprasījuma gadījumā, un vēlāk to var izmantot ar parametru “deletes_after”.
Piemērs:
https://hostname/api/1/IVVc?deletes_after=5000

7. Kad un kā izmantot parametrus?

• Ja interesē vienkārši saņemt visu reģistra saturu — izmanto pamatpieprasījumu bez parametriem.
• Ja vēlaties tikai vienu konkrētu ierakstu, vai ierobežotu ierakstu kopu — lietojiet filter, range vai fields.
• Ja rezultātu kopa ir liela un gribat pārlūkot pa gabaliem — lietojiet offset un limit.
• Ja gribat saņemt tikai izmaiņas kopš pēdējā pieprasījuma — updates_after vai deletes_after.

8. Datu rakstīšana datu bāzē (API POST)

Funkcionāli tiek izsaukta darbība RecordNew, pēc tam secīgi tiek izsauktas visas set komandas ar attiecīgajām loga darbībām (piemēram, lai aizpildītu klienta nosaukumu vai maksājumu nosacījumus). Pēc tam ieraksts tiek ievietots sistēmā, izpildot tās pašas pārbaudes un darbības, it kā lietotājs to veidotu manuāli no klienta programmas.

Set komandu skaits nav ierobežots — tās var atrasties gan URL, gan POST datu sadaļā. Atbildē tiks atgriezti tikai tie lauki, kuriem ir nenoklusētās (ne-tukšas) vērtības.

Piezīme: parametrs “url” viennozīmīgi identificē izveidoto ierakstu.
Ja galvenā atslēga sastāv no vairākiem laukiem, tie URL tiks atdalīti ar “/”.
Ja atslēgā ir speciālie simboli, tie tiks URL kodēti.

Ja lietotājs klienta programmā ievadot šos datus saņemtu kļūdas vai brīdinājumus, tie paši ziņojumi tiks atgriezti arī API atbildē šādā formātā:
<message description=’message_text’></message>

Kļūdas gadījumā (ievietojot vai atjauninot ierakstu) API atgriezīs:
<error code=’error_code’ description=’error description’ row=’row_no’ field=’field_name’></error>

9. Jaunu ierakstu izveide ar POST

Lai izveidotu jaunus ierakstus, jānosūta POST pieprasījums uz attiecīgo reģistru.
Pieejamie parametri:

• set_field – nosūta vērtību galvenes laukam.
• set_row_field – nosūta vērtību rindas laukam. Parametrā jāiekļauj rindas numurs (rindu numerācija sākas no 0).

Piemērs:

curl -X POST ‘http://SJ:@127.0.0.1:8080/api/1/IVVc?set_field.CustCode=001&set_row_field.0.ArtCode=10101&set_row_field.0.Quant=3’

Atbilde būs šādā formātā:

<data register=”IVVc” sequence=”9693″ url=”/api/1/IVVc/10000014″ systemversion=”8.5.38.66″>
<IVVc>
<SerNr>10000010</SerNr>
<InvDate>2021-05-30</InvDate>
<CustCode>001</CustCode>
…
<rows>
<row rownumber=”0″>
<stp>1</stp>
<ArtCode>10101</ArtCode>
<Quant>3</Quant>
<Price>25.00</Price>
<Sum>71.25</Sum>
…
</row>
</rows>
</IVVc>
</data>

Šis pieprasījums izveidos jaunu rēķinu klientam 001, pievienojot vienu rindu ar preci 10101 un daudzumu 3.

10. Speciālo simbolu izmantošana testēšanā

Ja nepieciešams nosūtīt speciālus vai ne-burtciparu simbolus, izmantojiet ASCII kodēšanu.

Piemērs:

curl -X POST ‘http://SJ:@127.0.0.1:8080/api/1/CUVc?set_field.Code=301&set_field.Name=Test%20%26%20Co’
Tas izveidos jaunu kontaktu ar kodu 301 un nosaukumu Test & Co.

Alternatīvi:

curl -X POST –data-urlencode “set_field.Name=Test & Co” ‘http://SJ:@127.0.0.1:8080/api/1/CUVc?set_field.Code=301’

11. PATCH – esoša ieraksta labošana

Lai atjauninātu jau esošu ierakstu, tiek izmantots PATCH uz URL, kas tika atgriezts POST pieprasījumā.
Set komandu sintakse un darbība ir tāda pati kā POST gadījumā.

Piemērs:

curl -X PATCH ‘http://SJ:@127.0.0.1:8080/api/1/IVVc/10000014?set_row_field.0.Quant=100’
Atbilde būs tādā pašā formātā kā POST:

<data register=”IVVc” sequence=”9729″ url=”/api/1/IVVc/10000014″ systemversion=”8.5.38.66″>
<IVVc>
…
<rows>
<row rownumber=”0″>
<stp>1</stp>
<ArtCode>10101</ArtCode>
<Quant>100</Quant>
<Price>25.00</Price>
<Sum>2375.00</Sum>
</row>
</rows>
</IVVc>
</data>
Šis piemērs labo pirmās rindas daudzumu uz 100.

12. OAuth autentifikācija

Lai trešās puses lietotne varētu izmantot OAuth kopā ar REST API, jāveic šādas darbības:

1. solis: izveidot Developer Credentials MyStandard portālā

Dodieties uz MyStandard → More → Developer Credentials,
un izveidojiet jaunu ierakstu savam StandardID.

2. solis: norādīt Allowed Redirects

Jaunajā ierakstā laukā Allowed Redirects jānorāda URL, uz kuru tiks novirzīts lietotājs pēc pieteikšanās (callback URL).
Trešās puses lietotnei autorizācijas pieprasīšanai jānovirza lietotājs uz https://standard-id.hansaworld.com/oauth-authorize ar šādiem GET parametriem:

• client_id – jūsu Client ID no MyStandard
• redirect_uri – jūsu lietotnes callback URL
• access_type = offline
• response_type = code

3. solis: lietotājs piesakās ar StandardID

Pēc novirzīšanas lietotājam jāautentificējas ar savu StandardID un paroli.

4. solis: saņemts autorizācijas kods

Ja pieteikšanās veiksmīga, lietotājs tiek novirzīts uz jūsu redirect_uri ar GET parametru:
code – autorizācijas kods

5. solis: autorizācijas koda apmaiņa pret OAuth tokenu

Jūsu lietotnei jāizsauc https://standard-id.hansaworld.com/oauth-token ar POST parametriem:

• client_id
• client_secret
• redirect_uri
• code – no 4. soļa
• grant_type = authorization_code

6. solis: veiksmīga atbilde ar tokeniem

Atbilde būs JSON formātā:

{
“access_token”: [access token],
“token_type”: “bearer”,
“expires_in”: 3600,
“refresh_token”: [refresh token]
}

7. solis: kļūdu gadījumā

Ja pieprasījums nav veiksmīgs, tiks atgriezts:
error = server_error

8. solis: API pieprasījumu veikšana ar tokenu

Katram turpmākajam API pieprasījumam jābūt header:

Authorization: Bearer [access_token]

13. OAuth testēšana ar Google Developers Playground

Ja vēlaties testēt OAuth, varat izmantot Google Developers Playground.

Konfigurācija

1. solis:
MyStandard iestatījumos Allowed Redirects jābūt:

https://developers.google.com/oauthplayground

2. solis:
Atverietm OAuth 2.0 Playground

3. solis:
Iestatiet

OAuth flow = Server-side
OAuth endpoints = Custom
Authorization endpoint =
https://standard-id.hansaworld.com/oauth-authorize
Token endpoint =
https://standard-id.hansaworld.com/oauth-token
Access Token Location = Authorization Header w/ Bearer prefix
OAuth Client ID – no MyStandard
OAuth Client Secret – no MyStandard

4. solis:
Sadaļā Select & Authorize APIs ievadiet jebkādu tekstu un nospiediet Authorize APIs.

5. solis:
Notiks novirzīšana uz StandardID pieteikšanās lapu — piesakieties.

6. solis:
Tiksiet novirzīti uz 2. soli ar aizpildītu autorizācijas kodu; nospiediet Exchange authorization code for tokens.

7. solis:
Pāriesiet uz 3. soli, kur varēsiet veikt GET, POST un PATCH API pieprasījumus ar OAuth pret Standard ERP.