API naudojimo būdai

Ši dokumentacija skirta padėti vartotojams suprasti ir naudotis Rivile ERP API sąsaja, pateikiant pagrindines naudojimo taisykles, užklausų struktūrą ir funkcinius reikalavimus.

OpenAPI specifikaciją galite rasti čia: RIVILE ERP_API(Swagger UI)

Norint pradėti naudotis API jums reikės

  1. API raktas (API Key):
    • API raktą galima sukurti Rivile ERP sistemoje. Daugiau informacijos, kaip tai padaryti, rasite API Key dokumentacijoje.
  2. Autentifikacija:
    • Kiekvienoje API užklausoje privaloma naudoti „X-SessionToken“ antraštę su API rakto reikšme. Tai būtina autentifikacijai.

API naudojimo specifika

  • GET užklausų rezultatų gražinimas limituojamas iki 100 įrašų per užklausą.
  • POST ir PUT užklausos dydis ribojamas iki 5MB
  • Max atsakymo trukmė 5 min. (vėliau gražinama "Read TimeOut" klaida)

API funkciniai reikalavimai

  • GET užklausose galima pridėti kombinuotus filtrus
  • POST metoduose užklausos payload'e galima vietoje "ID" reikšmių perduoti "CODE"
    • naudojant ID (pvz."clientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" gali būti unikalus kliento identifikatorius (ID));
    • naudojant kodą (pvz. "clientCode": "string" gali būti kliento unikalus kodas).
    • Perduodant "Code", sistema validuos ir pati susiras ID reikšmę, todėl užklausa bus vykdoma šiek tiek lėčiau.

    • Nurodžius abi identifikavimo reikšmes užklausoje, bus naudojama ID reikšmė, nes taip užklausa veiks greičiau.

  • Yra ribojamas eilučių kūrimas vienoje užklausoje. Kuriant ERP dokumentą (sąskaitą, užsakymą ar operaciją) kartu su dokumento eilutėmis, eilučių kiekis turi būti <= 100. Jei reikia dokumente sukurti daugiau eilučių, jas reikia sukurti papildomomis eilutės pridėjimo užklausomis.

Privalomi / Neprivalomi laukai kuriant įrašus

Kuriant įrašus dauguma laukų gali būti nepildomi, nes Rivile ERP automatiškai užpildys pagal ERP parametruose aprašytus nustatymus. Tačiau yra tam tikrų privalomų laukų, kuriuos būtina užpildyti reikšmėmis, kad įrašas būtų sėkmingai sukurtas. Privalomų laukų užpildymas priklauso nuo konkretaus įrašo tipo.

Sąskaitos ar užsakymo sukūrimo pavyzdys

{
  "clientCode": "000005",
  "lines": [
    {
      "itemCode": "000002",
      "uomAltCode": "VNT",
      "qtyAlt": 1,
      "departmentCode": "demo"
    }
  ]
}

Privalomi Laukai:

  • clientId arba clientCode: Kliento ID arba kodas, su kuriuo siejama sąskaita ar užsakymas.
  • lines:
    • itemId arba itemCode: Prekės / paslaugos ID arba kodas.
    • uomAltId arba uomAltCode: Mato vieneto ID arba kodas.
    • qtyAlt : kiekis nurodytu mato vienetu.
    • departmentId arba departmentCode: Įmonės padalinio ID arba kodas.

Sistema gavusi šią informaciją automatiškai užpildys: dokumentų numerį (pagal aprašytus skaitliukus), kainą (pagal aprašytą kainyną), datą ir pan., jeigu ji nebus užpildoma API duomenų perdavimo metu.

Duomenų filtravimas GET sąrašiniuose metoduose

GET sąrašiniuose metoduose galimas duomenų filtravimas, kuris leidžia sujungti kelis filtrus naudojant logine funkcija AND .

Filtravimui galimi naudoti operatoriai:

  • CONTAINS: Tikrina, ar laukas turi nurodytą tekstą.
  • NOT_CONTAINS: Tikrina, ar laukas neturi nurodyto teksto.
  • EQUAL: Tikrina, ar laukas yra lygus nurodytam tekstui, skaičiui arba loginei reikšmei.
  • NOT_EQUAL: Tikrina, ar laukas nėra lygus nurodytam tekstui arba skaičiui.
  • GREATER_THAN: Tikrina, ar laukas yra didesnis nei nurodytas skaičius.
  • LESS_THAN: Tikrina, ar laukas yra mažesnis nei nurodytas skaičius.
  • GREATER_THAN_OR_EQUAL: Tikrina, ar laukas yra lygus ar didesnis nei nurodytas skaičius.
  • STARTS_WITH: Tikrina, ar laukas prasideda nurodytu tekstu.
  • ENDS_WITH: Tikrina, ar laukas baigiasi nurodytu tekstu.

Pavyzdys:

Užduotis: Vykdyti filtravimą klientų, kurių pavadinime yra fragmentas "Demo" ir jie yra aktyvūs.

API filtrų sąlyga:

  {    "operation": "CONTAINS",    "name": "name",    "value": "Demo"  },
  {    "operation": "EQUAL",    "name": "active",    "value": true  }

Vykdant užklausą filtro JSON reikšmę reikia paversti eilute ir užkoduoti (URL Encode).

API GET užklausa su filtru turėtų atrodyti taip:

GET {{baseUrl}}/v1/clients?size=30&page=0&filter=%7B%22operation%22%3A%22CONTAINS%22%2C%22name%22%3A%22name%22%2C%22value%22%3A%22Demo%22%7D%2C%7B%22operation%22%3A%22EQUAL%22%2C%22name%22%3A%22active%22%2C%22value%22%3Atrue%7D

Filtravime palaikomi datos ir datos su laiku formatai:

Filtruojant pagal datą (date):

  • YYYY-MM-DD - pilnas datos formatas
    • Pavyzdys: 2025-09-01
    • Naudojamas kai reikia filtruoti tik pagal dieną, neprecizuojant laiko
    • Tinka operatoriams: EQUAL, NOT_EQUAL, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL

Filtruojant pagal datą ir laiką (datetime):

  • YYYY-MM-DDTHH:MM:SS.SSSZ - ISO 8601 formatas su laiko zona
    • Pavyzdys: 2025-09-01T00:00:00.000Z
    • T - datos ir laiko skyrybos simbolis
    • HH:MM:SS - laikas 24 valandų formatu (valandos:minutės:sekundės)
    • .SSS - milisekundės (000-999)
    • Z - UTC laiko zona (Zulu time)
    • Naudojamas kai reikia tikslaus laiko momento
    • Tinka operatoriams: EQUAL, NOT_EQUAL, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL

API užklausų atsakymų interpretavimas

  • Sėkmingai įvykdytos užklausos gražina atsakymą su 2xx būsena.
  • Jei užklausos vykdymo metu įvyksta incidentas ar techninė problema, grįžta atsakymas su 5xx būsena.
  • Neteisingai suformuotos užklausos grįžta su 4xx būsena.

Klaidos atsakymo struktūros pavizdys

{
    "code": "error.purchase-invoice.create.lines",
    "values": {
        "path": "createPurchaseInvoiceLine",
        "violations": {
            "lines[0].itemUomAltCode": "ItemUomAlt not found - Metras",
            "lines[3].itemCode": "Item not found - ABC123DEF"
        }
    }
}

violations struktūros paaiškinimas

  • Yra validuojama visa dokumento užklausa su pateiktomis eilutėmis. Todėl atsakyme gali būti ne viena, o kelios validacijos klaidos.
  • Pateikiamas konkretus parametro pilnas kelias (json path) ir reikšmėje nurodomas klaidos kodas, bei jūsų perduota reikšmė.
  • Reikia turėti omenyje, kad klaidose sąrašai (json array) numeruojami nuo 0, kad atitiktų jūsų užklausoje pateiktų elementų indexacijos tvarką.

Kodo pavyzdžiai:

API