Rest API kasutamine

Seadistamine Standard Booksis

Alates versioonist 8.0 saab HansaWorldi toodetes kasutada Web API päringuid andmete pärimiseks ja kirjutamiseks.

Eeltingimused

Kliendil peab olemas olema moodul:

• Standard ERP puhul - "Veebipood"

• Standard Books puhul - "Veebipood ja CMS"

Veebipordid

Seadistatud peab olema veebi port. Veebiport on võimalik seadistada - moodul Tehnika > Programmiseadistus > Veebiport

Veebipordid programmis

Veebipordid on vajalikud, et oleks võimalik suhtlus üle HTTP või HTTPS protokolli. Neid mitte sassi ajada Hansa pordiga, millega käib suhtlus klientprogrammi ja serveri vahel.

Veebiporti saab muuta ilma programmi muud tööd segamata.

Tuleb veenduda ka selles, et kasutatav port on serveris avatud - tulemüürid lubavad suhtlust vaid teatud portidel, kõik ei ole enamasti maailmale lahti.

Tuleb veenduda, et samas serveris ei ole kasutusele võetav port juba kasutusel.

NB: Excellent serveris paigaldab sertifikaadid Excellenti administaator. Kui soovite teha redirecti oma domeenilt, siis peate meile usaldama oma sertifikaadid (sh private key).

Ligipääs funktsioonidele veebist

Programmis sees. Moodul "Veebipood ja CMS"/“Veebipood“ seadistus Ligipääs funktsioonidele Veebist tuleb lisada rida (või read) käsitsi selliselt:

Funktsioon: API

Avalik: Sisselogitud kasutaja

SSL: Jah

Sessioon: Ei

Näide, kus API seadistatud SSLiga:

Väli Lubatud IP-d tuleb täita, kui on soov lubada ainult konkreetsetel süsteemidel teha Rest-API päringuid. Kui väljale on vaja lisada mitu aadressi, siis tuleb need eraldada komaga. Näide: 90.191.43.252,213.35.184.82

Kasutajagrupid

Moodul Üldine > Seadistused > Kasutajagrupid

Kasutajagrupile tuleb lisada õigusi lubav rida toimingule Rest API

Moodul Üldine > Isikud - Kasutajal peab olema peal kasutajagrupp, millel on antud õigus > Toiming Rest API > Täis

• Moodulitele, registritele ja seadistusele, mida soovite, et Rest API kasutaja peab saama lugeda (GET), peab olema antud vähemalt Vaata õigus.

• Kui soovite, et Rest API kasutajaga saaks andmeid ka kirjutada (POST) ja muuta (PATCH), peab olema antud vastava registri Täielik õigus.

• Kui Registri pihta, millele puudub Täielik õigus tehakse andmete kirjutamise päring, on vastus staatusega 200 kuid tühi.

Sisenemise paroolid tulevad Isiku kaardi õigustest.

On rangelt soovitatav kasutada MyStandardis valideeritud emaili sisse logimiseks. Uue isiku ja sealhulgas valideerimise juhend on siin: Kuidas lisada uut kasutajat?

Kasutajagrupil REST API

Valikulised võimalused

Moodul Üldine > Seadistused > Valikulised võimalused.

Märgitud peavad olema järgnevad valikud:

• Web Rest API

• Allow Basic HTTP Authentication

Valikulised Võimalused

Kasutamine

• Lugeda saab kõiki hansa registreid ja andme-blokke, sealhulgas HALiga tehtud registreid, seadistusi, muudatusi olemasolevatel kaartidel.

• Päringuga on kasutatav otsimine ja filtreerimine (käitub nagu aruanne)

• Jätame meelde eelmise päringu ja saame väljastada vahepeal muutunud andmeid

• Kasutajanimi, parool töötavad. Samuti kontrollitakse andmete lugemise õigust kasutajagruppidest

• Saab määrata väljade nimekirja kaardil, mida väljastada. Näide: varem oli üks üherealine müügiarve ca 350 XML rida pikk, siis nüüd saan lasta endale saata vaid näiteks 5 rida per arve.

URL’I kasutamine

Andmed päritakse URLiga ehk inimkeeli - klient ütleb Hansa serverile aadressi, mille põhjal Hansa server väljastab vastava info.

Eraldajad:

• ? - Sisestatakse peale Registri defineerimist, et kirjeldada filtreid.

• & - Sisestatakse erineva tüübiga filtreeringute vahele.

Näidis URL:

Vastus:

See väljastab arved kliendilt 105. Arve pole täielik, vaid on ainult väljad number, Kinnita linnuke, aadressi esimene rida, artiklikood, kliendikood, arve kuupäev, kande kuupäev, objektid.

Päringu vormistamine

http://username:password@hostname:port/api/1/IVVc

See on kõige lihtsam näidis päring kindlast ettevõttest ja kindlast registrist, kus

• "username" on kasutajanimi Isikute registrist;

• "password" on isikule määratud salasõna

• "api" on kohustuslik päringu osa stringina;

• "1" on ettevõtte kood ettevõtete registrist;

• "IVVc" on registri nimi.

See päring tõmbab kõik müügiarved ettevõttest 1. Kui soovid sarnaselt saada infot näiteks baasvaluutade kohta, siis pead kasutama päringut:

http://username:password@hostname:port/api/1/BaseCurBlock

Auth info ehk kasutaja/salasõna päringuga saatmine

Standard Books toetab "Basic access authentication" funktsionaalsust.

Kuidas kasutajanime ja parooli päringu tegemisel seadistada, sõltub sellest, mis tarkvaraga te päringut teete.

• Veebibrauseri ja curliga on lihtne viis panna kasutajanimi ja salasõna otse URLi sisse: http://username:password@hostname:port/api/1/IVVc

• Curliga saab auth info kohe kaasa anda ka headeris, näiteks:

curl --location --request GET 'https://mars.excellent.ee:3702/api/080/ObjVc' --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='

• Kui kasutate Microsofti tooteid, siis Power Query seadistatakse kasutajanimi ja salasõna vastavas seadistuses.

• Kõikides muudes tarkvarades on kasutajanime ja salasõna kasutamine erinev, tutvuge tarkvara dokumentatsiooniga.

Andmete formaat

Päringute andmeformaadid ja kättesaadud andmete formaadid on samad ning kindlalt fikseeritud:

• komakoha eraldajaks tuleb kasutada "." (punkt);

• tuhandete eraldajat ei tohi olla;

• kuupäevad on ISO formaadis YYYY-MM-DD (ehk aasta-kuu-päev)

Parameetrid

Reaalsed parameetri väärtused, mida päringutes kasutatakse (näiteks kasutatud võti/ID ja vahemik, serveri versioon jm.), esitatakse tulemustes andmeväljade atribuutidena("data tag"). Järgnevalt näited parameetritest.

sort - sorteerimise parameeter sorteerib saadud kaardid määratud andmevälja järgi. Indeksi nimi, mida kasutati, väljastatakse samuti päringu tulemuses. Sorteerida saab ainult kaardi päise väljade järgi. Võimalik on sorteerida ainult ühe välja järgi korraga, ja eeldusel, et selle jaoks on olemas sobiv indeks. Kui sobiv indeks puudub, siis päring tulemust ei väljasta. Välja nime puhul on olulised suured ja väikesed tähed. Näide (päring müügiarvete registrist, sorteerituna kliendikoodi järgi):

http://username:@hostname/api/1/IVVc?sort=CustCode

range - vahemiku parameetri kasutamiseks tuleb kasutada ka sorteerimise parameetrit. Vahemik pärib ainult need kaardid, kus sorteeritava välja väärtus langeb määratud vahemikku. Väärtused, mis võrduvad vahemiku alguse ja lõpuga, kaastakse tulemusse. Vahemiku alguse ja lõpu väärtused eraldatakse ":" (kooloniga). On lubatud ka päringud, kus määratud on ainult vahemiku alguse või ainult lõpu väärtus. Kui päringus kasutatakse ainult ühte kindlat väärtust (ilma koolonita), siis väljastatakse ainult kaardid, mis vastavad sellele konkreetsele väärtusele.

Näide 1 (väljastab müügiarved, kus kliendikoodid on vahemikus 10101 kuni 10104):

http://username:@hostname/api/1/IVVc?sort=CustCode&range=10101:10104

Näide 2 (väljastab müügiarved, kus kliendikoodid on 10104 kuni viimase kliendini):

http://username:@hostname/api/1/IVVc?sort=CustCode&range=10104:

Näide 3 (väljastab müügiarved, kus on ainult klient koodiga 10104):

http://username:@hostname/api/1/IVVc?sort=CustCode&range=10104

Vahemiku parameeter on kiire, sest kasutab indeksit.

fields - Väljade parameeter määrab, mis väljad tulemusse kaasatakse. Väljad eraldatakse komadega. Kui parameetrit ei ole määratud, siis võetakse tulemusse info kõikidest väljadest. Kui kaardi/dokumendi päises ja ridadel on sama nimega väli, kaasatakse tulemusse mõlemate info. Kui ridadelt ei pärita ühtegi välja, siis mingisugust ridade infot (ridade numbrid vms) ei väljastata tulemustes. Andmeväljade järjekord on alati sama (Booksi standard), Väljade järjestus päringus ei muuda väljade järjestust tulemuses.

Näide (väljastab müügiarved, ainult arve numbriga: 

http://username:@hostname/api/1/IVVc? fields=SerNr

filter - Andmeid saab filtreerida selle parameetri abil. Filter on oluliselt aeglasem kui vahemik, kuna ei kasuta indekseid ja otsib läbi kõik kaardid. Kui kasutad vahemiku parameetrit, siis filter köib läbi ainult need kaardid, mis jäävad vahemikku. Sellepärast on soovitav kasutada võimalikult täpset vahemiku määrangut ja teisi filtreid. NB: Filter väli peab kattuma täielikult otsitava väljaga. Ei saa otsida sisu osa

Näide:

http://username:@hostname/api/1/IVVc?filter.CustCode=10104

• Ühe välja kohta tohib kasutada ainult ühte filtrit

• Erinevate väljade kasutamisel, saab kasutada mitut filtrit

• Filtrid saavad kasutada sarnaselt väärtuste vahemike, k.a. ainult vahemiku alguse või ainult lõpuga määratud.

• Filtrid toimivad ainult kaartide/dokumentide päise andmeväljadega

• Nimekirja väljades filtreerimine (näiteks Objektid) toimub kogu stringi ulatuses.

Näiteks:  filter.Objects=AB ei kaasa tulemust "AB,D10101"

Näide (väljastab müügiarved, mille lõppsumma on vahemikus 100 kuni 1000 ja kus kliendikoodid on vahemikus 10100 kuni 10200):

http://username:@hostname/api/1/IVVc?filter.CustCode=10100:10200&Sum4=100:1000

listfilter - töötab sarnaselt filter parameetriga kuid suudab eristada ühte osa loetelust ehk terve välja sisu ei pea kattuma 100%.

Näide:

teen päringu, kus on parameeter listfilter.Objects=KONTOR

Vastused saan kõikide kaartide kohta, kus vähemalt üheks objektiks on KONTOR:

offset and limit - Kui päringu tulemus on suurem, kui api kasutaja suudab töödelda ühe päringuga, siis saab tulemusi jagada väiksemateks osadeks. "offset" jätab vahele määratud arvu kaarte/dokumente päringu tulemuses. "limit" piirab kaartide koguarvu päringu tulemuses.

Näide (väljastab 15 esimest müügiarvet 3 erineva päringuga):

http://username:@hostname/api/1/IVVc?offset=0&limit=5 

http://username:@hostname/api/1/IVVc?offset=5&limit=5 

http://username:@hostname/api/1/IVVc?offset=10&limit=5

"offset" ja "limit" saab kasutada koos kõikide teiste parameetritega.

updates_after - väljastab kõik kaardid/dokumendid, mida on uuendatud peale määratud järjekorra numbrit. Järjekorra number väljastatakse igas päringus (sequence="x") ning seda saab kasutada hiljem koos parameetriga "updates_after"

NB: et kasutada updates_after ja deletes_after funktsioone peab olema peal seadistus: Moodul Tehnika > Seadistused > Sünkroniseerimise võimalused > Aktiveeri.

Näide:

http://username:@hostname/api/1/IVVc?updates_after=5000

deletes_after - väljastab kõik kaardid/dokumendid, mis on kustutatud peale määratud järjekorra numbrit. Järjekorra number väljastatakse igas päringus ning seda saab kasutada hiljem koos parametriga "deletes_after"

Näide:

http://username:@hostname/api/1/IVVc?deletes_after=5000

NB: Kui kasutate deletes_after või updates_after parameetreid, siis võiks enne andmebaasi eksporti-importi (hooldus, ver uuendus) peale panna Üldine > Seadistused > Valikulised võimalused > linnuke "Ekspordi järjekorranumbrid".Siis säilivad baasis sequence cväärtused. Kui seda peale ei panda, siis hakkavad sequence väärtused uuesti otsast peale jooksma. Mis ei ole suur mure ilmselt, aga on võimalik vältida.

Lisaks:

• Sequence number antakse igale Standard Booksis loodud või muudetud kaardile / andmeblokile (seadistused). Sisuliselt on see andmebaasis tehtud muudatuste järjekorranumber. Ja iga kaardi või seadistuse loomine ja muutmine on andmebaasimuudatus.

• API päringu vastuses antakse kaasa alati viimane andmebaasimuudatusele omistatud sequence number.

• Ajas sequence niisama ei muutu - kui teha päringuid nii, et keegi Standard Booksis ei toimeta, ei muutu ka sequence väärtus API päringu vastuse päises.

• Filter.xxx ja Sort ja Range päringud ei toimi koos updates_afteriga - kui neid kasutada koos, kehtib vaid updates_after. Küll aga saab updates_afteriga koos kasutda fields=xxx parametrit.

Andmete kirjutamine StandardBooksi, > 8.5

Andmete kirjutamisel StandardBooksi kasutatakse funktsiooni "RecordNew" ehk dokumendile kehtivad täpselt samad loomise reeglid, nagu klientprogrammi kasutades (näiteks mis andmed asetatakse dokumendile peale Kontakti koodi valimist; mis on kohustuslikud väljad, mis on Kontakti-põhised andmed dokumendil jms).

Andmete mahu piirangut andmete kirjutamisel ei ole. On võimalik päringu sisu saata kas URLis või POST päringu andmete osas ( --data-raw ).

POST päringu järgselt saadetakse alati tagasi vastus, Standard Booksi XML formaadis. Selleks saab olla kas loodud dokument/kaart või veateade. Loodud dokumendi/kaardiga võib aga ei pruugi vastuses olla ka informatiivseid teateid, hoiatusi. Vastuses on XMLis ainult andmeid sisaldavad read.

Vastuses on alati ka link loodud dokumendile, url parameetris. Näiteks kirjutasime baasi artikli koodiga 2005, siis on url osas sisu: "url="/api/1/INVc/1005"". Kui kirjutatakse korraga mitu dokumenti, on urlis koodid eraldatud "/" märgiga. Kui koodis on täpitähti või muid erilisi tähemärke, on nad url-kodeeritud.

Kõik teated, mis kasutajale tagastatakse, asuvad vastuses message osas, teated luuakse täpselt samadel alustel, nagu klientprogrammi kasutades: <message description='message_text'></message>

Kui andmete kirjutamine toob kaasa veateate, on see Error code parameetri sisus. Seal on viide ka täpsele vea tekkimise asukohale (rea nr ja välja nimi): <error code='error_code' description='error description' row='row_no' field='field_name'></error>

Postitamisel on andmeväljade eraldajaks & märk.

Booksis on enamikul toiminguregistritel (Arve, Ostuarve, Tellimus, Pakkumus, Arve, Laekumine, Tasumine jne) 200 rea piirang. APIga andmeid saates olge tähelepanelik, et te seda ridade arvu ei ületa. Kui ületate, siis veateadet standardis ega hoiatust otseselt ei tagastata, klient võib lõpuks saada vale sisuga dokumendi.

Et täpitähed liiguksid korrektselt, lisa päisesse headeri rida:

POST

Registrisse uue kirje lisamiseks tuleb andmed saata Rest API POST meetodiga, url-formaadis. Iga välja juures tuleb kasutada set käsku.

Andmed võivad olla nii otse URLis, kui --data-raw osas

Näide 1.1, kaherealine arve, kasutame --data-raw: 

Näide 1,2, sama kaherealine arve, sisu otse URLis:

Sellele POSTile saadetakse vastus:

On loodud uus arve nr 1202053623, Kontaktile koodiga 111, arvel on 2x rida.

PATCH

Et muuta olemasolevat kaarti, peate andma täpse registrikaardi URLi ja kaustama PATCH meetodit.

Näide, muudame kliendikoodi ära, 111 asemel 109: 

Vastus on samasugune, nagu POST päringul. sisuks uuenenud andmed:

NB: Kui tegu on registriga, kus sama (põhi) koodiga saab eksisteerida mitmeid kaarte, on kasutusel URL unikaalsete koodide kombinatsiooniga.

Näiteks Ostuartikli Patch url on kujul /api/1/PIVc/[Artiklikood]/[Laokood]/[Tarnijakood]/[TarnijaArtikkel]. Näiteks: https://mars.excellent.ee:4455/api/1/PIVc/002/PL/001/80702

Sama kehtib veel näiteks ka Hindade kohta.

Täpse kaardi PATCH urli lõpu saab kõige paremini kätte POST päringu vastuse teiselt realt, see rida on näiteks selline:

Lihtsad POSTi näited

POST meetodiga saab tekitada uusi dokumente

PATCH meetodiga saab muuta olemasolevaid kaarte (ei pea kaasa saatma kogu kaardi sisu, muudetava dokumendi nr sisaldub URLis)

Koostame kliendi

Saame vastuse:

• astuses vaid need read kontaktikaardilt, mis on täidetud.

• täidetud on ka väljad, mis GUIga kontakti luues automaatselt täidetakse

Koostame artikli

Vastus

Meil on nüüd olemas Klient koodiga "1985" (Kohvimasina Post OÜ) ja artikkel "19.321-127"

Müüme postitatud artikli postitatud kliendile maha.

Koostame arve, kasutame loodud artiklit ja klienti

Vastuseks saime üherealise arve:

Nagu näha, on arvele kandunud korrektselt objektid, kliendi kontaktisikud jms, mida me postitasime algsetele kaartidele.

NB: On oluline ka lisatava info järjekord. Näiteks, kui lisate tasumistingimuse koodi, seejärel kontakti koodi ning sellel kontaktil ei ole Müügi Tasumistingimus täidetud, siis saate veateate, et tasumistingimus on tühi. Õige järjekord antud juhul oleks Kontaktikood, peale seda tasumistingimus. Sama reegel on objektidega - need lisada peale kontakti, ridadel peale Kontot või Artiklit.

Muudame koostatud arvel kogust

Vastuseks on samasugune arve XML, nagu arve postitamisel, vaid kogus on muutunud 3-ks.

Kinnitame arve

tekkis viga, puudu on konto käibemaksukoodi pealt. Saime veateate:

Parandasin vea, seejärel sain tulemuseks OK ning tulemus:

Saadame Booksi firma nime, kus on sees & märk

Nagu olete tähele pannud, siis & märk töötab rea lõpu tähisena. Seega firma nime "Saue & Saku OÜ" kirjutamisel ei saa me kasutada tavapärast kirjakuju:

(Sel juhul tuleks kontakti nimeks vaid "Saue ")

Kodeerime kõik postitatavad andmed kohe URL formaati (kuigi tegelikult tühikuid tühikutena on okei saata):

Manuste pärimine Standard Booksist

Alates 2024 aasta kevade versiooniuuendusest saab Standard Booksist pärida kaartidele lisatud manuseid.

Lihtsaim kasutusjuhtum on see, kui näitek veebipood POSTib arve Standard Booksi, see kinnitatakse, tekib arvele manusesse arve PDF, mis genereeritakse vastavalt Standard Booksi dokumendimallile. Seejärel saab Veebipood enda keskkonda pärida täpselt selle arve PDFi, mille Standard Books on genereerinud. Teine levinud kasutusjuhtum on artiklite piltide, sertifikaatide ja kasutusjuhendite pärimine veebikeskkonda.

Päring koosneb kahest osast:

1. Kaaride seoste päring (saame kätte meid huvitava dokumendi manuste lingid)

2. Manuse enda päring.

Kaartide seoste päring

Kõikides Standard Booksi registrites saab päringule lisada parameetri get_links=1.

Kui link viitab registrile Attach2Vc on tegu manustatud failiga. Kui link viitab mõnele muule registrile (MailVc, ORVc, QTVc jne) on tegu kaartide omavahelise seosega Standard Booksis sees.

Näide ühe arve manuste kohta:

https://mars.excellent.ee:445/api/1/IVVc?get_links=1&filter.SerNr=230008

Ja tulemuses on iga registrikaardi lõpus <links> osa:

Sealt saame manuse päringuks vajaliku Attach2Vc registri kirje numbri (SerNr).

Manuste pärimine

Manuste pärimiseks teme päringu Attach2Vc registri pihta. Eelpool toodud näidet kasutades saame PDFi pärida nii:

https://mars.excellent.ee:445/api/1/Attach2Vc?filter.SerNr=126&get_attachdata=true

Vastuses on metadata ja manuse sisu base64 kodeeringus:

Head tavad Standard Booksi Rest API kasutamiseks

Andmete maht

Enamasti on mõtestatud API kasutamise alustuseks vaja pärida suur hulk baasandmeid (kontaktid, artiklid, kontod, objektid jne) ja pika perioodi toiminguregistrid (arved, laekumised, tellimused, kanded jne). Et seda teha teiste kasutajate suhtes võimalikult väikese mõjuga, siis:

• Üle 100 000 kirjega registrite puhul kasutage andmete pärimiseks öist aega.

• Kui öine ajastamine pole võimalik, pärige andmeid näiteks 1000 kuni 5000 kaupa, kasutades offset and limit parameetreid. Jätke päringute vahele umbes sekundilised pausid, et server saaks vahepeal teenindada klientprogramme

• Kui kasutate suurte andmemahtude korral fields või filter parameetreid, on päringule vastuse koostamine äärmiselt CPU-nõudlik. Päringule vastuse koostamine võtab ca 10x kauem aega, kui pärides toor-andmeid. Antud filtreid on hea kasutada jooksvate päringutega, lühikese perioodi kohta või koos updates_after parameetriga.

Jooksvate päringute tegemine

• Veebipoodide, tootmis- ja laosüsteemide liidestamisel on vajadus pärida Standard Booksist muutunud andmeid. Selleks tegevuseks on parim viis updates_after parameetri kasutamine, mis tagastab vastuses vaid uued ja/või muutunud kaardid päritavas registris alates eelmisest päringust. NB: kui soovite kasutada updates_after parameetrit registris, kus see toetatud pole, siis võtke ühendust Excellenti müügiosakonnaga.

• Ajastage päring mitte sagedamalt, kui 20 minutilise intervalliga. Kui teete sagedamalt, hakkavad Stadard Booksis kuhjuma samaaegsed sisselogimis-sessioonid. 2021 lõpu seisuga on Standard Booksil probleeme suure hulga taoliste sessioonide haldamisega ja varem või hiljem tekivad probleemid klientprogrammide ühendustega.

Testid

Testid on tehtud 2021 aasta lõpus, ver STDBKS_8.5-2021-09-26-0383

• 2- realisi finantskandeid suudab Standard Books tavaolukorras kirjutada 10 tk sekundis.

• 1 realisi arveid koos Kinnita valikuga suudab Standard Books kirjutada 3-4 tk sekundis

• 10 000 kande pärimine toor-andmetega võtab aega ca 10 sekundit (3 sekundit päringu koostamine, 7 sekundit vastuse salvestamine + edastamine). Vastuse suurus 30 MB. Samal ajal ei olnud klientprogrammi kasutamine võimalik.

• 10 000 kande pärimine koos fields parameetri ja 10 väljaga võttis 7 sekundit (5 sekundit päringu koostamine, 2 sekundit vastuse salvestamine + edastamine) Vastuse suurus 4 MB. Samal ajal ei olnud klientprogrammi kasutamine võimalik.

• Kui teha GET päringuid järjest 1 sekundilise vahega, siis on klientprogramm kasutuskõlbmatu peale 25 minuti möödumisel päringute algusest.