Redaguoti

Pradžia Internetiniai moduliai Rivile API v2 (REST web servisai) Rivile API v2 naudojimo pagrindai

Rivile API v2 naudojimo pagrindai

1. Įvadas

Aprašyme pateikiama bendra Rivile API v2 (REST web service) naudojimo logika bei galimybės. Tai apima 3 dalis :

Bendra API v2 (REST web service) naudojimo informacija.
Informacijos nuskaitymas iš Rivile GAMA.
Informacijos įkėlimas į Rivile GAMA.

2. Bendra API v2 (REST web service) naudojimo informacija

2.1. Informacijos pateikimas pavyzdžiais

Visuose žemiau pateiktuose pavyzdžiuose vizualumo ir aiškumo dėlei atsakymai yra sutrumpinami, t.y. paliekama tik ta dalis, kuri yra aktuali. Realūs atsakymai iš web servisų būtų kur kas išsamesni.

Pavyzdžiui, likučių atsakymas pagal kelias prekes būtų toks:

<RET_DOK>
    <I17>
        <Row_number>1</Row_number>
        <I17_KODAS_PS> PREKE01     </I17_KODAS_PS>
        <I17_KODAS_US>VNT         </I17_KODAS_US>
        <I17_KODAS_US_A>VNT         </I17_KODAS_US_A>
        <I17_KODAS_IS>           </I17_KODAS_IS>
        <I17_KODAS_OS>           </I17_KODAS_OS>
        <I17_SERIJA></I17_SERIJA>
        <I17_FRAKCIJA>1</I17_FRAKCIJA>
        <KIEKIS>200</KIEKIS>
        <des_likutis_us>200.0000</des_likutis_us>
        <des_likutis_us_a>200.0000</des_likutis_us_a>
        <N37_BAR_KODAS>000000000002</N37_BAR_KODAS>
    </I17>
    <I17>
        <Row_number>2</Row_number>
        <I17_KODAS_PS> PREKE02     </I17_KODAS_PS>
        <I17_KODAS_US>DEZ_12      </I17_KODAS_US>
        <I17_KODAS_US_A>DEZ_12      </I17_KODAS_US_A>
        <I17_KODAS_IS>           </I17_KODAS_IS>
        <I17_KODAS_OS>           </I17_KODAS_OS>
        <I17_SERIJA></I17_SERIJA>
        <I17_FRAKCIJA>12</I17_FRAKCIJA>
        <KIEKIS>235</KIEKIS>
        <des_likutis_us>19.5833</des_likutis_us>
        <des_likutis_us_a>19.5833</des_likutis_us_a>
        <N37_BAR_KODAS>000000000022</N37_BAR_KODAS>
    </I17>
</RET_DOK>

Pateikiant informaciją, aprašymuose naudojam tik dalis, kuri reikalinga suvokti logikai. Atitinkamai, pagal aukščiau pateiktą pavyzdį:

<I17>
        <N37_BAR_KODAS>000000000002</N37_BAR_KODAS>
        <I17_KODAS_PS>PREKE01     </I17_KODAS_PS>
        <I17_KODAS_US>VNT         </I17_KODAS_US>
        <I17_KODAS_US_A>VNT         </I17_KODAS_US_A>
        <des_likutis_us>200.0000</des_likutis_us>
        <des_likutis_us_a>200.0000</des_likutis_us_a>
    </I17>

2.2. Formatai

Šiame dokumente visi pavyzdžiai pateikiami XML formate, tačiau duomenų pasikeitime galima naudoti ir json formatą.

Siunčiant užklausą json formatu, nurodomas header Content-Type: application/json
Gaunamai informacijai json formatu, nurodomas header Accept: application/json

2.3 Datos ir skaičių formatas

Datos formatas sistemoje yra YYYY-MM-DD, pavyzdžiui: 2020-12-31
Datos ir laiko formatas sistemoje yra YYYY-MM-DD HH:MM:SS, pavyzdžiui: 2020-12-31 12:59:59 arba 2020-12-31T12:59:59
Dešimtainės dalies skaičiaus skyriklis yra taškas, pavyzdžiui: 21.00

2.4 Užklausų formavimas

Užklausose nurodoma koks metodas bus naudojamas. Priešdėlis GET ar EDIT atitinkamai reiškia informacijos nuskaitymą arba informacijos koregavimą (įkėlimą, koregavimą, trynimą).

GET funkcijose naudojama sekcija („tag‘as“) , kuriame galima formuoti pateikiamos informacijos filtravimo sąlygas. Šiame dokumente pateiktos užklausos užpildytos rekomenduojamomis filtravimo sąlygomis, tačiau esant specifiniams poreikiams, jas galima prisitaikyti.

Šiame dokumente pateiktuose pavyzdžiuose naudojama reikšmė 'DATA' reiškia, kad perduodamas parametras yra šios dienos data formatu YYYY-MM-DD

Pavyzdžiui:

<body>
    <method>GET_I33_LIST</method>
    <params>
        <list>H</list>
        <pagenumber>1</pagenumber>
        <fil>i33_kodas_ps IN  (select n17_kodas_ps FROM n17_prod where (N17_POZ_DATE=0 OR 'DATA' BETWEEN n17_beg_date AND n17_end_date))</fil>
    </params>
</body>

turi būti užpildoma taip:

<body>
    <method>GET_I33_LIST</method>
    <params>
        <list>H</list>
        <pagenumber>1</pagenumber>
        <fil>i33_kodas_ps IN  (select n17_kodas_ps FROM n17_prod where (N17_POZ_DATE=0 OR '2020-04-01' BETWEEN n17_beg_date AND n17_end_date))</fil>
    </params>
</body>

2.5 Užklausų skaičiavimo metodika

Rivile API v2 (REST web servisai) užklausa traktuojamas duomenų užklausimas (kreipimasis į Rivile API v2 REST web service serverį), nepriklausomai nuo atsakymo rezultatų.

Atsakymai pateikiami dalimis po 100 įrašų. Apmokestinama remiantis užklausų kiekiu. Pavyzdžiui:

Turint 150 klientų, jų sąrašui gauti reikalingos 2 užklausos, kur kiekviena užklausa gauna iki 100 įrašų.
Įkeliant pardavimą su 5 prekėmis ir 1 pristatymo paslauga vienu kartu – viena užklausa.
Įkeliant pardavimą su 5 prekėmis ir 1 pristatymo paslauga, atskirai kuriant dokumentą bei atskirai įkeliant po vieną prekę ir paslaugą – 7 užklausos.

2.6 Prekių / paslaugų apibrėžimas

Rivile sistemoje prekės ir paslaugos laikomos toje pačioje lentelėje N17_PROD. Jos atskiriamos pagal požymį N17_TIPAS: 1-prekės, 2-paslauga.

Loginis skirtumas tarp prekės ir paslaugos yra tai, kad prekė padalinyje turi kiekinį likutį, o paslauga likučio neturi.

2.7 Prekės identifikatorius

Ne visos įmonės prekių aprašymui naudoja barkodus. Tokiu atveju, unikalumas gaunamas pagal prekės kodą ir matavimo vienetą. Tai reiškia, kad :

barkodas = prekės kodas + mato vienetas

2.8 Matavimo vienetai

Rivile GAMA sistemoje prekė gali turėti kelis skirtingus mato vienetus. Vienas iš jų pagrindinis, kiti –papildomi (alternatyvūs). Aprašant alternatyvius mato vienetus, visada nurodomas jų santykis su pagrindiniu. Pvz., jeigu pagrindinis mato vienetas yra VNT, o papildomas – DEZ, kuriame telpa 12 vienetų, tai santykis yra 12.

Mato vienetas gali būti dalinamas į smulkesnes dalis – frakcijas. Jeigu dėžė, kurioje yra 12 VNT bus parduodama smulkinant dalimis, tai mato vieneto DEZ frakcija turi būti 12.

Jei KG (kilogramas) dalinamas į 1000 dalių , tai frakcija bus 1000. Reiškia, kiekius bus galima vesti 3 skaičių po kablelio tikslumu. Pvz., 1.5 KG (pusantro kilogramo) arba 1.005 KG (kilogramas ir 5 gramai).

Remiantis frakcijomis, galima matyti į kiek smulkių dalių gali būti skaidomas parduodamos prekės mato vienetas.

Kiti mato vieneto panaudojimo pavyzdžiai: prekiaujant apranga, mato vienetas gali apibrėžti dydžius S, M, L, XL ir pan., prekiaujant batais – batų dydžius 37, 38, 39, 40 ir t.t.

Pastaba: Jei kuriamoje sistemoje dirbama su sveriamais produktais, tai, teikiant sveriamų produktų užsakymus, būtų galima naudoti vidutinio svorio sąvoką. Vidutinis svoris gali būti nurodomas prekės mato vieneto aprašymo lauke n37_turis. Remiantis šia reikšme, kuriama sistema galėtų apvalinti pateiktą kiekį (pavyzdžiui, kad klientas nepateiktų užsakymo: 5 gramai arbūzo).

Pastaba: Šiame dokumente kiekiai pateikiami dešimtaine išraiška

2.9 Naudojami kodai

Bet kurie sistemoje naudojami sąrašiniai kodai yra char(12) UPPER case kodai. Tarpai po kodo neturi reikšmės. Tarpai prieš kodą turi reikšmę. Pavyzdžiui: ’A01’ = ’A01 ’, bet ’A01’ ≠ ’ A01’. Rekomenduojama:

tarpų prieš kodus nenaudoti,
tarpais kodų neatskirti,
nenaudoti jokių spec. simbolių (neskaitant – ir _) ar lietuviškų raidžių.

2.10 Sąrašų ryšiai / ryšiai tarp lentelių

Sistemos laukai susideda iš kelių loginių dalių:

lentelės identifikatorius (pvz., I17 – likučių sąrašas)
loginė reikšmė (pvz., KODAS)
sąrašo kodas, kuriame ši informacija kaupiama (pvz., IS – padalinių sąrašas)

Tokiu principu gaunamas laukas I17_KODAS_IS, kuris reiškia padalinio kodą likučių sąraše.

Pagrindiniai, dažniausiai naudojami, sąrašai:

PS – prekės, paslaugos
US – matavimo vienetai
IS – padaliniai
KS – klientai (pirkėjai, tiekėjai)
GS – grupės (tiek klientų, tiek prekių).

2.11 Atsakymų puslapiavimas

Standartiškai Rivile web servisai grąžina atsakymus puslapiais po 100 įrašų. Todėl, norint nuskaityti visą informaciją, reikia užklausas siųsti cikle. Parametras, nurodantis puslapio numerį yra pagenumber. Pavyzdžiui, antras puslapis iš klientų sąrašo atrodytų taip:

<body>
<method>GET_N08_LIST</method>
<params>
    <fil></fil>
    <pagenumber>2</pagenumber>
</params>
</body>

2.12 Vartotojo vardas Rivile GAMA sistemoje

Web service jungiasi prie Rivile GAMA sistemos ir veikia kaip vartotojas. Todėl yra naudojamas vartotojo vardas, kuris pateikiamas kartu su API raktu, ir yra rakto dalis.

Pavyzdžiui, rakte: XW3CDDX.BfnjvrurjygzujRtJLlXORuYcT5JhjGSH2F2z5tL , vartotojo vardas yra pirmoji rakto dalis iki taško, t.y. XW3CDDX

Pastaba: Rivile GAMA programoje šio vartotojo kurti nereikia.

2.13 Internetinis padalinys

Dažniausiai prekės ar paslaugos parduodamos iš atskiro, internetinei prekybai skirto padalinio. Padalinio kodas aprašomas vartotojo papildomai susikurtame parametre EP_PAD - internetinis padalinys . Parametre nurodytame padalinyje aprašomos prekių pardavimo kainos bei akcijos. (Detaliai apie parametrus aprašyta parametrai ).

2.14 Prekių kainos ir PVM

Dažniausiai, B2C scenarijuje naudojamos kainos su PVM, B2B – kainos be PVM. Kur ir kokios kainos vedamos, suderinama tarp kliento ir kuriamos sistemos diegėjo.

Rivile GAMA sistemoje tai nurodoma padalinio aprašyme. Padalinio aprašyme esantis požymis „Pardavimo kainos su PVM“ nustato kaip aprašomos kainos - su PVM ar be PVM.

2.15 Pilna informacija apie funkcijas

Pilnas užklausų aprašymas ir rezultatai pateikti : internetiniai_moduliai/api_rest.

3. Informacijos nuskaitymas iš Rivile GAMA

3.1 Bendra informacija

Įrašų nuskaitymo funkcijų pavadinimai prasideda GET_<ID> , pilnas jų sąrašas bei funkcionalumai pateikiami : internetiniai_moduliai/api_rest

Šiame aprašyme pateikiami tik keletas pavyzdžių.

Rivile GAMA sistemoje nėra galimybės gauti tik informacijos pasikeitimus. Informacijos pasikeitimai saugomi priskiriant koregavimo datą, tačiau išmetimo atveju informacija yra fiziškai ištrinama. Todėl tokia informacija tiesiog nepatektų, pasiimant iš sistemos tik pasikeitimus. Vienintelį, prekių likučių sąrašą, galima pasiimti, atsižvelgiant tik į koregavimo datą (išskyrus labai retus atvejus, kada iš prekių likučių sąrašo išvalomos pozicijos su nuliniais kiekiais).

Dėl šios priežasties, visa informacija nedidelėmis dalimis arba visa iškart turėtų būti pilnai sinchronizuojama. Rekomenduojama:

Prekių sąrašus, klientų, kainas, akcijas ar matavimo vienetų aprašymus sinchronizuoti bent kartą per dieną.
Likučių sąrašas ir dokumentų apmokėjimo statusai gali būtų sinchronizuoti kas valandą. Likučių pasikeitimai gali būti traukiami ir dažniau.

3.2 Prekių atsargų likučiai

3.2.1 Prekių likučiai įmonės mastu.

Kokius padalinius vertinti, apsprendžia Rivile GAMA sisteminis parametras SS_FIL_IS . Jame web service vartotojui priskiriama padalinių filtravimo lentelė. Jei parametras neaprašytas, informacija bus imama iš visų padalinių. (Detaliai apie parametrus aprašyta parametrai ).

Užklausa:

<body>
    <method>GET_I17_LIST</method>
    <params>
        <group></group>
        <pagenumber>1</pagenumber>
    </params>
</body>

Atsakymas:

<I17>
        <N37_BAR_KODAS>000000000001</N37_BAR_KODAS>         --- barkodas
        <I17_KODAS_PS>PREKE01     </I17_KODAS_PS>           --- prekės kodas
        <I17_KODAS_US>VNT         </I17_KODAS_US>           --- pagrindinio matavimo vieneto kodas
        <I17_KODAS_US_A>DEZ         </I17_KODAS_US_A>       --- alternatyvaus matavimo vieneto kodas
        <des_likutis_us>120.0000</des_likutis_us>           --- kiekis pagrindiniu mato vienetu
        <des_likutis_us_a>10.0000</des_likutis_us_a>        --- kiekis alternatyviu mato vienetu
</I17>

3.2.2 Prekių likučiai pagal padalinius

Užklausa:

<body>
    <method>GET_I17_LIST</method>
    <params>
        <group>IS</group>
        <pagenumber>1</pagenumber>
    </params>
</body>

Atsakymas:

    <I17>
        <N37_BAR_KODAS>000000000001</N37_BAR_KODAS>         --- barkodas
        <I17_KODAS_PS>PREKE01     </I17_KODAS_PS>           --- prekės kodas
        <I17_KODAS_US>VNT         </I17_KODAS_US>           --- pagrindinio matavimo vieneto kodas
        <I17_KODAS_US_A>DEZ         </I17_KODAS_US_A>       --- alternatyvaus matavimo vieneto kodas
        <I17_KODAS_IS>01          </I17_KODAS_IS>           --- padalinio (sandėlio) kodas
        <des_likutis_us>120.0000</des_likutis_us>           --- kiekis pagrindiniu mato vienetu
        <des_likutis_us_a>10.0000</des_likutis_us_a>        --- kiekis alternatyviu mato vienetu
    </I17>

3.2.3 Konkrečios vienos prekės pozicijos likutis

Užklausa:

<body>
    <method>GET_I17_LIST</method>
    <params>
        <group></group>
        <pagenumber>1</pagenumber>
        <fil>i17_kodas_ps='PREKE01'</fil>
    </params>
</body>

Atsakymas:

<I17>
        <N37_BAR_KODAS>000000000001</N37_BAR_KODAS>         --- barkodas
        <I17_KODAS_PS>PREKE01     </I17_KODAS_PS>           --- prekės kodas
        <I17_KODAS_US>VNT         </I17_KODAS_US>           --- pagrindinio matavimo vieneto kodas
        <I17_KODAS_US_A>DEZ         </I17_KODAS_US_A>       --- alternatyvaus matavimo vieneto kodas
        <des_likutis_us>120.0000</des_likutis_us>           --- kiekis pagrindiniu mato vienetu
        <des_likutis_us_a>10.0000</des_likutis_us_a>        --- kiekis alternatyviu mato vienetu
</I17>

3.2.4 Prekių likučių pagal padalinius pasikeitimai nuo tam tikros datos ir tik toms prekėms, kurios yra aktyvios bei kurioms aprašytos kainos padalinyje.

Padalinio kodas nurodomas vartotojo sukurtame parametre EP_PAD. (Detaliai apie parametrus aprašyta parametrai ).

Minimizuojant užklausų kiekį bei atsinaujinimo tankį, prekių likučių sąrašo traukimą galima vykdyti remiantis paskutine koregavimo/pasikeitimo data. Prekių likučių sąraše išlieka ir nuliniai likučiai (išskyrus labai retus atvejus, kada iš prekių likučių sąrašo išvalomos pozicijos su nuliniais kiekiais).

Užklausa:

<body>
    <method>GET_I17_LIST</method>
    <params>
        <group>IS</group>
        <pagenumber>1</pagenumber>
        <fil>I17_R_DATE >= 'DATA IR LAIKAS' AND i17_kodas_is IN (SELECT n23_reiksme1 FROM N23_PRMD WHERE n23_kodas_pr='EP_PAD') and i17_kodas_ps NOT IN  (select n17_kodas_ps FROM n17_prod where N17_TIPAS=2 OR  NOT (N17_POZ_DATE=0 OR 'DATA' BETWEEN n17_beg_date AND n17_end_date))</fil>
    </params>
</body>

Atsakymas:

    <I17>
        <N37_BAR_KODAS>000000000001</N37_BAR_KODAS>         --- barkodas
        <I17_KODAS_PS>PREKE01     </I17_KODAS_PS>           --- prekės kodas
        <I17_KODAS_US>VNT         </I17_KODAS_US>           --- pagrindinio matavimo vieneto kodas
        <I17_KODAS_US_A>DEZ         </I17_KODAS_US_A>       --- alternatyvaus matavimo vieneto kodas
        <I17_KODAS_IS>01          </I17_KODAS_IS>           --- padalinio (sandėlio) kodas
        <des_likutis_us>120.0000</des_likutis_us>           --- kiekis pagrindiniu mato vienetu
        <des_likutis_us_a>10.0000</des_likutis_us_a>        --- kiekis alternatyviu mato vienetu
    </I17>

3.3 Prekių barkodų / matavimo vienetų sąrašas

Pateikiamas sąrašas prekių, kurioms Rivile GAMA sistemoje yra aprašytos kainos ir priskirtos konkrečiam padaliniui, bei pačių prekių kortelių aprašymai yra galiojantys. Padalinys Rivile GAMA sistemoje nurodomas vartotojo sukurtame parametre EP_PAD. (Detaliai apie parametrus aprašyta parametrai ).

Užklausa:

<body>
    <method>GET_N37_LIST</method>
    <params>
        <list>H</list>
        <pagenumber>1</pagenumber>
        <fil>n37_kodas_ps NOT IN  (select n17_kodas_ps FROM n17_prod where NOT (N17_POZ_DATE=0 OR 'DATA' BETWEEN n17_beg_date AND n17_end_date)) AND  N37_KODAS_PS IN (SELECT i33_kodas_ps FROM I33_PKAI inner join N23_PRMD on i33_kodas_is=n23_reiksme1 and n23_kodas_pr='EP_PAD' WHERE i33_kaina>0)</fil>
    </params>
</body

Atsakymas:

<N37>
        <N37_BAR_KODAS>000000000001</N37_BAR_KODAS>     --- prekės matavimo vieneto barkodas
        <N37_KODAS_PS>TEST01      </N37_KODAS_PS>       --- prekės kodas
        <N37_KODAS_US>DEZ         </N37_KODAS_US>       --- prekės matavimo vienetas (alternatyvus arba pagrindinis. Pagrindinis nurodomas prie prekės kortelės N17_KODAS_US)
        <N37_PAV>Pavadinimas test 01         </N37_PAV> --- pavadinimas
        <N37_TRUM_PAV>Pavadinimas test</N37_TRUM_PAV>   --- trumpas pavadinimas
        <N37_FRAKCIJA_A>1</N37_FRAKCIJA_A>              --- matavimo vieneto frakcija
        <N37_FRAKCIJA>1</N37_FRAKCIJA>                  --- pagrindinio matavimo vieneto frakcija 
        <N37_KOEFICI>12</N37_KOEFICI>                   --- alternatyvaus mato vieneto ir pagrindinio mato perskaičiavimo koeficientas
        <N37_NETTO>0.000</N37_NETTO>                    --- prekės netto svoris (pagal matavimo vienetą)
        <N37_BRUTTO>0.000</N37_BRUTTO>                  --- prekės brutto svoris (pagal matavimo vienetą)
        <N37_TURIS>0.0000000000</N37_TURIS>             --- prekės tūris
        <N37_ILGIS>0.000</N37_ILGIS>                    --- prekės ilgis
        <N37_PLOTIS>0.000</N37_PLOTIS>                  --- prekės plotis
        <N37_AUKSTIS>0.000</N37_AUKSTIS>                --- prekės aukštis
</N37>

3.4 Kliento spec. kaina

B2B atveju, kaina gali būti išskaičiuojama pakankamai sudėtingai – vertinant padalinio kainas, objekto kainas, kainynus, sutartis, nuolaidų grupes ar kitas kainas, galiojančias tik tam tikru metu. Tokiu atveju, kainos nustatymui naudojama funkcija GET_PS_KAIN.

Platesnis funkcijos aprašymas: api_rest/get_ps_kain.

3.5 Pritaikytos specializuotos užklausos

Rivile GAMA duomenų bazėje galima aprašyti specializuotą duomenų nuskaitymo sakinį („SQL View“), kuris leistų surinkti ir agreguoti duomenis iš kelių skirtingų lentelių pagal kliento vedamų duomenų specifiką. Šis metodas taip pat gali būti taikomas mažinant duomenų užklausų kiekius, kad viena užklausa būtų galima nuskaityti kaip įmanoma daugiau duomenų apie tam tikrą informacijos vienetą.

Pavyzdžiui, viename užklausos atsakyme galima būtų pateikti duomenis apie parduotą prekę, jos grupę, subgrupę, prekei priskirtus logistikos kodus (požymius), papildomus laukus, pagrindinį tiekėją, kainą padalinyje, taip pat klientui galiojančią pardavimo sutartį, vėluojamos apmokėti skolos likutį ir pan.

Naudojant SQL View taip pat galima pateikti duomenis iš tam tikrų apskaitoje registruojamų ir per standartines web service priemones nepasiekiamų operacijų, tokias kaip darbuotojų darbo kalendorius, tabeliai ar pan.

Platesnis aprašymas: api_rest/get_views_list

Šio funkcionalumui ypatumai:

SQL View sukuriamas Rivile GAMA duomenų bazėje. Juos kuria arba pats klientas, arba Rivile GAMA konsultantas.
SQL View pavadinimo pradžia v_RGI_... , pavyzdžiui: v_RGI_skolos.
Iškvietimui naudojama web servise metodas GET_VIEWS_LIST.
Iškvietimui reikia žinoti SQL View pavadinimą bei atsakyme esančių duomenų logiką.

3.6 Sugeneruoto PDF dokumento (sąskaitos faktūros ar išankstinės sąskaitos) gavimas

PDF dokumentas generuojamas Rivile GAMA sistemoje ir prisegamas prie pardavimo operacijos. Prisegama rankiniu būdu pridedant PDF dokumentą arba automatiškai, patvirtinus (perkėlus) pardavimo važtaraštį. Integruojant su išorine sistema, pastaroji gali pasiimti šį prisegtą dokumentą naudojantis web service funkcija.

Veiksmai Rivile GAMA pusėje:

3.6.1 Dokumento prisegimas.

Rivile GAMA sistemoje yra galimybė prie bet kurios operacijos prikabinti dokumentą. Dokumentas prikabinamas tos operacijos koregavimo lange pasinaudojant mygtuku „Dokumentas“. Prikabinti galima bet kokio tipo dokumentą: PDF, DOC, XLSX, BMP, PNG ir pan.
Šis mygtukas pagal nutylėjimą nėra matomas, todėl lange, kuriame planuojama šį funkcionalumą naudoti, užprogramuojamas lango INIT metodas: thisform.dokumentas=.T.
Detaliai apie dokumentų prisegimą aprašyta dokumentų prisegimas .

pagr1

3.6.2 Dokumento generavimas ir automatinis prisegimas perkeliant operaciją.

Rivile GAMA sistemoje yra galimybė naudoti papildomą funkcionalumą, kad perkėlimo metu (ar atskiru sutarimu suderinus kitą veiksmą – pavyzdžiui būsenos keitimą) susiformuotų PDF dokumentas pagal operacijoje nurodytą „WEB apsikeitimo“ ataskaitos formą. Sąskaitos faktūros forma derinama atskiru sutarimu ir sukuriama paties kliento arba Rivile GAMA konsultanto.

Papildomam dokumento sugeneravimo funkcionalumui reikalinga funkcija x_ro_perk_pdf

pagr2

Detalus funkcijos aprašymas pateiktas : x_ro_perk_pdf

Pardavimo dokumento aprašyme nurodoma ataskaitos forma : pagr3

Veiksmai web service:

3.6.3 Ataskaitos (sąskaitos faktūros formos) nustatymas

Sąskaitos faktūros (ar išankstinio mokėjimo sąskaitos) forma kuriama ir priderinama pagal kiekvieno kliento pageidavimą. web service kuriant pardavimo dokumentą, nurodomas šios sukurtos ataskaitos formos numeris, pavyzdžiui, P12.

Užklausa kuriant pardavimo užsakymą:

<body>
    <method>EDIT_I06_FULL</method>
    <params>
        <oper>I</oper>
    </params>
    <data>
         <I06>
           <I06_OP_TIP>51</I06_OP_TIP>
           <I06_DOK_REG>UZS_123456</I06_DOK_REG>
           <I06_OP_DATA>2020-03-05</I06_OP_DATA>
           <I06_DOK_DATA>2020-03-05</I06_DOK_DATA>
           <I06_KODAS_KS>023456789</I06_KODAS_KS>
           <I06_PAV>UAB "7 Nykštukai"</I06_PAV>
           <I06_WEB_ATAS>P12</I06_WEB_ATAS>     -- Nurodomas ataskaitos formos kodas
...
         </I06>
    </data>
</body>

3.6.4 Prisegto dokumento gavimas

web service realizuota funkcija GET_I06_DOC , leidžianti pasiimti prisegtą dokumentą.

Užklausa :

<body>
    <method>GET_I06_DOC</method>
    <params>
        <kodas_po>010000001252</kodas_po>   -- nurodomas pardavimo operacijos numeris (I06_KODAS_PO)
    </params>
</body>

Atsakymas (dokumentas grąžinamas BINARY BASE64 koduotėje):

<RET_DOK>
    <I06>
        <KODAS_PO>010000001252</KODAS_PO>
        <DOC>JVBERi0xLjQNCiXi48/TvvjQNDQolZ2VuZXJhdGVkIGJ5IFhGUlgsIChjKSAyMDA1IHd3dy5lcWV 1cy5jb20NCjUgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAyIDAgUg0KL01lZGlhQm94IFswIDAgNTk1IDg0Ml0NCi9Bbm5vdHMgOCAwIFINCi9SZXNvdXJjZXMgPDwNCi9Gb2...
        </DOC>
        <EXT>.PDF</EXT>
    </I06>
</RET_DOK>

4. Informacijos įkėlimas į Rivile GAMA

4.1 Bendra informacija

Visų įrašų įkėlimo ar koregavimo funkcijų pavadinimai prasideda EDIT_<ID> , pilnas jų sąrašas bei funkcionalumai pateikiami gide: internetiniai_moduliai/api_rest

Šiame aprašyme pateikiami tik keletas pavyzdžių.

4.2 Klientai

4.2.1 Kliento patikrinimas

Klientas pagal unikalų raktą ieškomas Rivile GAMA sistemoje, tik neradus šio kliento – kuriamas naujas.

Mažinant šių užklausų kiekį, rekomenduojama savo kuriamoje sistemoje išsaugoti Rivile duomenų bazės kliento kodą. Tada bus galima iškart jį naudoti, nereikės formuoti užklausos kliento kodui gauti.

Nesant tokios galimybės, kliento unikalų identifikatorių savo kuriamoje sistemoje (ID ar el. pašto adresą) galima talpinti į Rivile sistemą, tam panaudojant lauką N08_REZERVAS - „Trumpas įmonės pavadinimas“, ir vėliau jį naudoti ieškant kliento kodo.

Kliento paieška pagal savo kuriamos sistemos vartotojo ID. Užklausa:

<body>
    <method>GET_N08_LIST</method>
    <params>
        <list>H</list>
        <pagenumber>1</pagenumber>
        <fil>N08_REZERVAS='ID' and N08_RUSIS IN (1,3)</fil>
    </params>
</body>

Atsakymas:

<N08>
            <N08_KODAS_KS>023456789</N08_KODAS_KS>      --- Kliento kodas
            <N08_PAV>UAB "7 Nykštukai"</N08_PAV>        --- Kliento pavadinimas / vardas pavardė
            <N08_IM_KODAS>023456789</N08_IM_KODAS>      --- Įmonės kodas
            <N08_PVM_KODAS>LT023456789</N08_PVM_KODAS>  --- PVM kodas
            <N08_KODAS_XS_P>EP_PVM_LT</N08_KODAS_XS_P>  --- Mokesčių lentelės kodas
            <N08_KODAS_DS>EP_KLIENTAS</N08_KODAS_DS>    --- Sąskaitų ryšio lentelės kodas
            <N08_ADR>Adresas</N08_ADR>                  --- Adresas
            <N08_PASTAS>LT123456</N08_PASTAS>           --- Pašto kodas
            <N08_ATSTOVAS>Jonas T.</N08_ATSTOVAS>       --- Atstovo vardas pavardė
            <N08_E_MAIL>info@7n.lt</N08_E_MAIL>         --- E. pašto adresas
            <N08_TEL>+3705123456</N08_TEL>              --- Telefono nr.
            <N08_MOB_TEL>+370468123456</N08_MOB_TEL>    --- Mobilaus tel. nr.
            <N08_PVM_SKOL_P>1</N08_PVM_SKOL_P>          --- Pagal nutylėjimą ar traukti PVM mokestį į kliento skolą (1 - taip, 0 - ne)
</N08>

Užklausa pagal įmonės kodą:

<body>
    <method>GET_N08_LIST</method>
    <params>
        <list>H</list>
        <pagenumber>1</pagenumber>
        <fil>N08_IM_KODAS='ID' and N08_RUSIS IN (1,3)</fil>
    </params>
</body>

4.2.2 Kliento sukūrimas

Privalomi laukai ir jų užpildymas:

Tipas: 1 – juridinis asmuo, 2 – fizinis asmuo.
Rūšis: 1 – pirkėjas, 3 – pirkėjas/tiekėjas.
Mokesčių lentelė: PVM (konkretų kodą ar kodo parinkimo algoritmą derinti tiesiogiai su užsakovu).
Sąskaitų ryšys: PT001 (konkretų kodą ar kodo parinkimo algoritmą derinti tiesiogiai su užsakovu).
Jeigu klientai yra juridiniai asmenys, rekomenduojama nurodyti kliento kodą (N08_KODAS_KS) , lygų įmonės kodui.
Nenurodžius kliento kodo (N08_KODAS_KS), sistema pati suteiks unikalų numerį pagal Rivile GAMA sistemoje aprašytą skaitliuką. Priskirta unikali reikšmė bus grąžinta atsakyme.
Neperdavus tam tikrų sistemos laukų, jie bus automatiškai užpildomi pagal nustatytas reikšmes pagal nutylėjimą. Tai taip pat galioja ir kliento kodui.

Užklausa įmonei sukurti:

<body>
    <method>EDIT_N08</method>
    <params>
        <oper>I</oper>
    </params>
    <data>
    <N08>
            <N08_KODAS_KS>023456789</N08_KODAS_KS> 
            <N08_PAV>UAB "7 Nykštukai"</N08_PAV> 
            <N08_IM_KODAS>023456789</N08_IM_KODAS>  
            <N08_PVM_KODAS>LT023456789</N08_PVM_KODAS> 
            <N08_TIPAS>1</N08_TIPAS>
            <N08_RUSIS>1</N08_RUSIS>
            <N08_KODAS_XS_P>PVM</N08_KODAS_XS_P> 
            <N08_KODAS_DS>PT001</N08_KODAS_DS> 
            <N08_ADR>Adresas</N08_ADR>
            <N08_PASTAS>LT123456</N08_PASTAS>   
            <N08_ATSTOVAS>Jonas T.</N08_ATSTOVAS> 
            <N08_E_MAIL>info@7n.lt</N08_E_MAIL> 
            <N08_TEL>+3705123456</N08_TEL>
            <N08_MOB_TEL>+370468123456</N08_MOB_TEL>
    </N08>
    </data>
</body>

Atsakymas:

    <N08>
            <N08_KODAS_KS>023456789</N08_KODAS_KS> 
...
    </N08>

4.3 Pardavimo pasiūlymas

Pardavimo pasiūlymo dokumento sukūrimas :

Dokumento numeris bus sugeneruotas pagal Rivile GAMA vidinę sistemą. Kuriamos sistemos užsakymo numeris talpinamas lauke I06_DOK_REG. Šis užsakymo numeris visuose dokumento etapuose (verčiant rezervavimu, važtaraščiu ir pan. ), turi būti rišamoji grandis ir išlikti I06_DOK_REG lauke.
Pildant pardavimo dokumentą, padalinio galima nenurodyti- tokiu atveju jis bus priskiriamas pagal nutylėjimą. Jei planuojama dokumentą automatiškai konvertuoti į rezervavimą ar važtaraštį, padalinį nurodyti būtina, taip pat būtina paskirstyti užsakomą prekių kiekį pagal padalinius.

Užklausa (dvi prekės ir pristatymo paslauga):

<body>
    <method>EDIT_I06_FULL</method>
    <params>
        <oper>I</oper>
    </params>
    <data>
         <I06>
            <I06_OP_TIP>53</I06_OP_TIP>                 --- Operacijos tipas: 51 – važtaraštis, 52 – grąžinimas, 53 – užsakymas, 54 – rezervavimas, 55 - pasiūlymas
           <I06_DOK_REG>UZS_123456</I06_DOK_REG>        --- Dokumento registras. Užsakymo dokumento numeris kuriamoje sistemoje
           <I06_OP_DATA>2020-03-05</I06_OP_DATA>        --- Operacijos data. Užsakymo sukūrimo data
           <I06_DOK_DATA>2020-03-05</I06_DOK_DATA>      --- Dokumento data. Užsakymo sukūrimo data
            <I06_KODAS_KS>023456789</I06_KODAS_KS>      --- Kliento kodas. Kiekvienas registruotas vartotojas turėtų naudoti tą patį kodą. Neregistruotiems vartotojams (kai nėra galimybės identifikuoti) rekomenduojama kiekvieną kartą kurti naują kliento kodą.
            <I06_PAV>UAB "7 Nykštukai"</I06_PAV>        --- Kliento pavadinimas ar vardas/pavardė
            <I06_ATSTOVAS>info@7n.lt</I06_ATSTOVAS>     --- El. pašto adresas
           <I06_ADR> +370468123456</I06_ADR>            --- Mob. tel. nr
           <I06_APRASYMAS1>Pristatymo būdas</I06_APRASYMAS1> --- Pristatymo būdo aprašymas
           <I06_PAV2> Pristatymo būdas</I06_PAV2>       --- Pristatymo būdo aprašymas
           <I06_APRASYMAS2>Pristatymo sąlygos</I06_APRASYMAS2> --- Pristatymo sąlygos
           <I06_ADR2> Pristatymo sąlygos </I06_ADR2>    --- Pristatymo sąlygos
           <I06_KODAS_LS_1>EP_MOK_APM</I06_KODAS_LS_1>
           <I06_KODAS_LS_2>EP_PRIS_ATS</I06_KODAS_LS_2>
           <I07>                            --- Detali prekės eilutė 1
               <BAR_KODAS>000000000002</BAR_KODAS>      --- Barkodas (Arba jei nedirbama su barkodais šioje vietoje gali būti nurodomas prekės tipas, prekės kodas ir prekės alternatyvus matavimo vieneto kodas)
               <KIEKIS_U>1</KIEKIS_U>                   --- Kiekis (dešimtainis)
               <I07_KODAS_IS>02</I07_KODAS_IS>          --- Padalinio kodas. Nenurodžius šio tag‘o, bus priskiriamas padalinys pagal nutylėjimą.
               <I07_KAINA_BE>    10.00</I07_KAINA_BE>   --- Kaina be PVM
               <I07_KAINA_SU>    12.10</I07_KAINA_SU>   --- Kaina su PVM
               <I07_NUOLAIDA>  0.00</I07_NUOLAIDA>      --- Nuolaidos procentas
               <I07_MOKESTIS>1</I07_MOKESTIS>           --- Ar taikomas PVM mokestis: 1-taip, 0-ne
               <I07_MOKESTIS_P> 21.00</I07_MOKESTIS_P>  --- Koks PVM procentas taikomas
               <I07_PVM_SKOL>1</I07_PVM_SKOL>           --- Ar traukti PVM mokestį į kliento skolą (1 - taip, 0 - ne)
               <I07_PVM>     2.10</I07_PVM>             --- PVM suma
               <I07_SUMA>    10.00</I07_SUMA>           --- Suma be PVM
           </I07>
           <I07>                                        --- Detali prekės eilutė 2
               <I07_TIPAS>1</I07_TIPAS>                 --- Prekės tipas: 1 – prekė, 2 – paslauga
               <I07_KODAS>PREK001</I07_KODAS>           --- Prekės kodas
               <I07_KODAS_US_A>VNT</I07_KODAS_US_A>     --- Prekės alternatyvus matavimo vienetas
               <KIEKIS_U>2</KIEKIS_U>                   --- Kiekis (dešimtainis)
               <I07_KODAS_IS>02</I07_KODAS_IS>          --- Padalinio kodas. Nenurodžius šio tag‘o, bus priskiriamas padalinys pagal nutylėjimą.
               <I07_KAINA_BE>    10.00</I07_KAINA_BE>   --- Kaina be PVM
               <I07_KAINA_SU>    12.10</I07_KAINA_SU>   --- Kaina su PVM
               <I07_NUOLAIDA> 10.00</I07_NUOLAIDA>      --- Nuolaidos procentas
               <I07_MOKESTIS>1</I07_MOKESTIS>           --- Ar taikomas PVM mokestis: 1-taip, 0-ne
               <I07_MOKESTIS_P> 21.00</I07_MOKESTIS_P>  --- Koks PVM procentas taikomas
               <I07_PVM_SKOL>1</I07_PVM_SKOL>           --- Ar traukti PVM mokestį į kliento skolą (1 - taip, 0 - ne)
               <I07_PVM>     4.20</I07_PVM>             --- PVM suma
               <I07_SUMA>    20.00</I07_SUMA>           --- Suma be PVM
           </I07>
           <I07>                                        --- Detali pristatymo eilutė 3
               <I07_TIPAS>2</I07_TIPAS>                 --- Prekės tipas: 1 – prekė, 2 – paslauga
               <I07_KODAS>EP_PRIST</I07_KODAS>          --- Paslaugos kodas
               <I07_PAV>Pristatymas per DPD</I07_PAV>   --- Paslaugos pavadinimas. Tam pačiam pristatymo kodui galite nurodyti kitą pavadinimą, detalizuojant koks buvo pasirinktas pristatymo metodas
               <I07_KODAS_US_A>VNT</I07_KODAS_US_A>     --- Paslaugos alternatyvus matavimo vienetas
               <KIEKIS_U>1</KIEKIS_U>                   --- Kiekis (dešimtainis)
               <I07_KAINA_BE> 4.13</I07_KAINA_BE>       --- Kaina be PVM
               <I07_KAINA_SU>5 </I07_KAINA_SU>          --- Kaina su PVM
               <I07_MOKESTIS>1</I07_MOKESTIS>           --- Ar taikomas PVM mokestis: 1-taip, 0-ne
               <I07_MOKESTIS_P>21.00</I07_MOKESTIS_P>   --- Koks PVM procentas taikomas
               <I07_PVM_SKOL>1</I07_PVM_SKOL>           --- Ar traukti PVM mokestį į kliento skolą (1 - taip, 0 - ne)
               <I07_PVM>0.87</I07_PVM>                  --- PVM suma
               <I07_SUMA>4.13</I07_SUMA>                --- Suma be PVM
           </I07>
         </I06>
    </data>
</body>

Atsakymas:

         <I06>
           <I06_DOK_REG>UZS_123456</I06_DOK_REG>        --- Dokumento registras. Užsakymo dokumento numeris kuriamoje sistemoje
           <I06_KODAS_PO>000000000001</ I06_KODAS_PO>   --- Operacijos numeris.
           <I06_DOK_NR>UZS0001</I06_DOK_NR>             --- Užsakymo dokumento numeris.
...
         </I06>