Kaip skaityti BSS API metodus ir jų grąžinamus duomenis

Kaip skaityti BSS API metodus ir jų grąžinamus duomenis

BSS API dokumentacijoje prie kiekvieno metodo pateikiamas techninis užklausos žymėjimas – GET, POST, PUT arba DELETE – ir metodo pavadinimas, paaiškinantis, kokį veiksmą metodas atlieka. Renkantis metodą svarbu vertinti abu. Vien POST žymėjimas nereiškia, kad metodas kuria naują objektą – BSS API POST taip pat naudojamas paieškai, duomenų keitimui, failų įkėlimui, veiksmų inicijavimui ir kitoms operacijoms.

Ką reiškia GET, POST, PUT ir DELETE?

Metodo pavadinimas pasako, ką metodas daro

Po GET, POST, PUT ar DELETE žymėjimo pateikiamas pats metodo pavadinimas. Būtent jis yra svarbiausias renkantis, kokį veiksmą norite atlikti.

Kodėl gali būti keli panašūs GET metodai?

Tam pačiam BSS objektui gali būti keli GET metodai, nes objektą galima surasti pagal skirtingą turimą identifikatorių. Tokiu atveju pasirenkamas tas metodas, kuris atitinka jūsų turimus duomenis. Pavyzdžiui, darbuotojo informaciją galima gauti: pagal employee ID – vidinį BSS darbuotojo identifikatorių, pagal timeboard number – tabelio numerį arba pagal staff code – darbuotojo kortelės numerį. Visais šiais atvejais ieškomas konkretus darbuotojas, tik naudojama skirtinga jį identifikuojanti reikšmė. Tą patį principą galima matyti ir kituose BSS objektuose – pavyzdžiui, dokumentą galima gauti pagal dokumento ID arba dokumento numerį, projektą – pagal projekto ID arba projekto numerį. Todėl renkantis GET metodą pirmiausia pasižiūrėkite, kokį objekto identifikatorių turite.

Kuo skiriasi GET ir SEARCH?

GET naudojamas tada, kai konkretus objektas jau žinomas ir turite jo identifikavimo reikšmę. GET metodas paprastai grąžina gerokai daugiau ir detalesnės objekto informacijos nei SEARCH. Kurį GET metodą pasirinkti, priklauso nuo to, kokią identifikavimo reikšmę turite – pavyzdžiui, ID, numerį ar kodą.

SEARCH dažniausiai naudojamas objektams surasti pagal pasirinktus kriterijus ir gauti jų identifikavimo informaciją – pavyzdžiui, ID, numerį, kodą ar kitą reikšmę, pagal kurią vėliau galima kreiptis į konkretų GET metodą. SEARCH rezultatų struktūra paprastai yra mažesnė ir skirta paieškai bei reikiamo objekto identifikavimui.

Ką metodas gali grąžinti?

Priklausomai nuo metodo, BSS API gali grąžinti vieną objektą, objektų sąrašą, puslapiuotą sąrašą arba tik užklausos rezultatą be papildomų duomenų.

Laukų tipai ir jų reikšmės

Prie lauko dokumentacijoje nurodytas tipas padeda suprasti, kokio pobūdžio reikšmė gali būti grąžinta. Duomenų tipas pats savaime nepaaiškina lauko verslo prasmės. Pavyzdžiui, sveikasis skaičius gali reikšti kiekį, objekto identifikatorių arba pasirinktą sąrašo reikšmę.

Lentelėje pateikti pavyzdžiai skirti tipams paaiškinti. Konkretaus lauko paskirtį ir galimas reikšmes tikrinkite metodo apraše.

Tekstas ir skaičiai

Tekstas JSON atsakyme rašomas dvigubose kabutėse, o skaičiai – be kabučių. Vien tai, kad reikšmė sudaryta iš skaitmenų, dar nereiškia, kad jos tipas yra skaičius. Pavyzdžiui, kodas "00125" yra tekstinė reikšmė, kurioje svarbūs ir pradžioje esantys nuliai.

Skaičiai gali reikšti sumas, kiekius, procentus, koeficientus ar identifikatorius. Trupmeninė dalis JSON formate atskiriama tašku, pavyzdžiui, 125.50. Matavimo vienetą ir reikšmės paskirtį nustatykite pagal lauko aprašymą bei susijusius laukus.

Loginės reikšmės: true ir false

Loginis laukas pateikia vieną iš dviejų reikšmių: true arba false. Jos rašomos be kabučių. Šias reikšmes skaitykite kartu su lauko pavadinimu ir aprašu. Pavyzdžiui, jei laukas nurodo, ar įrašas ištrintas, true reiškia, kad ištrynimo požymis įjungtas, o false – kad neįjungtas. false yra konkreti reikšmė, o ne tuščias laukas.

Datos ir laikas

Data pateikiama formatu YYYY-MM-DD: pirmiausia metai, tada mėnuo ir diena. Pavyzdžiui, "2026-10-12" reiškia 2026 m. spalio 12 d. Datos ir laiko reikšmėje abi dalys atskiriamos raide T. Pavyzdžiui, "2026-10-12T14:30:00" nurodo datą ir laiką – 14 val. 30 min. Laiko dalyje gali būti pateikiamos ir sekundės dalys.

Tuščia reikšmė ir nepateiktas laukas

API atsakyme laukas gali turėti tuščią reikšmę arba būti nepateiktas. Tuščios reikšmės nepainiokite su nuliu ar false – jų prasmė skiriasi.

Objektai ir jų laukai

Objektas yra kelių susijusių laukų grupė. JSON atsakyme jis žymimas riestiniais skliaustais {}. Objekto viduje gali būti tekstinių, skaitinių ir kitų reikšmių, taip pat kitų objektų ar masyvų. Toliau pateiktas iliustracinis pavyzdys:

{
  "data": {
    "name": "Prekė A",
    "price": 125.50,
    "isActive": true
  }
}

Šiame pavyzdyje data yra vienas objektas. Jo viduje pateikti trys laukai: name, price ir isActive. Įdėtinį lauką skaitykite kartu su objektu, kuriam jis priklauso. Vienodai pavadinti laukai skirtinguose objektuose gali turėti skirtingą paskirtį.

Kur rasti konfigūracinio sąrašo reikšmes?

Kai kuriuose API laukuose grąžinamas pasirinkto BSS konfigūracinio sąrašo įrašo identifikatorius. Norint sužinoti, kokią reikšmę jis žymi, reikia gauti atitinkamą sąrašą. Prie tokio lauko dokumentacijoje pateikiama žyma Config index. Pavyzdžiui, Config index: WeightUnit nurodo matavimo vienetų sąrašą.

• Prie lauko dokumentacijoje raskite Config index.
• Skiltyje Global pasirinkite metodą Get configuration data by index ir perduokite nurodytą indeksą.
• Gautame sąraše raskite įrašą, kurio configurationNumber atitinka jūsų lauko reikšmę.

Sąrašo indeksas nurodo, kurį sąrašą gauti, o configurationNumber – konkretų to sąrašo įrašą. Pavyzdžiui, įrašą, kurio name yra Candidate, identifikuoja configurationNumber: 1. Jei API laukas laukia šio sąrašo įrašo identifikatoriaus, perduokite 1, o ne tekstą Candidate. Lauko privalomumą ir naudojimo taisykles tikrinkite konkretaus metodo apraše.

Kaip suprasti atributo reikšmę?

Atributai leidžia prie BSS objektų saugoti papildomą informaciją. Atributo reikšmė gali būti tekstas, skaičius, data, loginė reikšmė, pasirinkimas iš sąrašo arba nuoroda į sistemos objektą. Atributo aprašas ir konkrečiam objektui priskirta atributo reikšmė yra skirtingi dalykai. Aprašas paaiškina, koks tai atributas ir kokio tipo jo reikšmė. Objekto atributų duomenys pateikia tam objektui priskirtą reikšmę.

Atributo apraše laukas attributeDataTypeCfgNr nurodo jo reikšmės tipą. Šį kodą susiekite su sąrašo AttributeValueType lauku configurationNumber. Lauke name pateikiamas tipo pavadinimas. Tai BSS atributų tipai, todėl jų nepainiokite su bendrais JSON duomenų tipais.

Atributo tipo kodas nurodo, kaip suprasti reikšmę, o ne pačią atributo reikšmę. Pavyzdžiui, attributeDataTypeCfgNr: 4 reiškia, kad atributas yra sąrašo tipo, tačiau pasirinktą sąrašo įrašą nurodo jo value.

Trumpai duomenų skaitymo seka tokia: Gaukite konkretaus objekto atributų reikšmes → pasiimkite attributeNr → metodu GetAttribute (Attributes/{AttributeNr}) gaukite atributo aprašą → pagal attributeDataTypeCfgNr nustatykite tipą → pagal šį tipą interpretuokite atributo reikšmę.

Sąrašo tipo atributai

Sąrašo tipo atributo value nurodo pasirinktą sąrašo įrašą. Norint sužinoti jo pavadinimą, pirmiausia reikia išsiaiškinti, su kuriuo sąrašu atributas susietas. attributeDataTypeCfgNr: 4 reiškia sąrašo tipą. Atributo apraše pateiktas configurationIndexName nurodo reikalingą sąrašą.

• Iš objekto atributo duomenų pasiimkite attributeNr ir value.
• Pagal attributeNr gaukite atributo aprašą.
• Iš aprašo pasiimkite configurationIndexName.
• Skiltyje Global metodu Get configuration data by index pagal šį indeksą gaukite konfigūracinį sąrašą.
• Jame raskite įrašą, kurio configurationNumber atitinka atributo value. Pasirinkto įrašo pavadinimą perskaitykite iš name.

attributeNr identifikuoja patį atributą, o jo value – tam objektui pasirinktą sąrašo reikšmę. Įprastam API laukui reikalingą sąrašą nurodo dokumentacijos žyma Config index, o sąrašo tipo atributui – atributo aprašo laukas configurationIndexName.

Trumpai duomenų skaitymo seka tokia: Pasiimkite atributo attributeNr ir value → metodu GetAttribute gaukite aprašą → patikrinkite attributeDataTypeCfgNr: 4 ir pasiimkite configurationIndexName → metodu Get configuration data by index gaukite šį sąrašą → raskite įrašą, kurio configurationNumber atitinka atributo value → perskaitykite jo name.

Sistemos objekto tipo atributai

Sistemos objekto tipo atributo reikšmė yra nuoroda į konkretų BSS įrašą, pavyzdžiui, projektą, padalinį ir pan. Norint suprasti šią reikšmę, reikia nustatyti du dalykus: kokios srities objektas pasirinktas ir kuris tos srities įrašas nurodytas.

Pavyzdžiui, gavote tokią atributo reikšmę:

{
  "attributeNr": 172,
  "attributeValuePrimaryKeyNr": 5,
  "ownerNr": 236,
  "referencedPrimaryKeyNr": 140,
  "value": "Kamanių avilys"
}

Čia attributeNr: 172 nurodo atributą, referencedPrimaryKeyNr: 140 – pasirinktą BSS įrašą, o value – jo pavadinimą. Iš šio atsakymo vieno dar negalima nustatyti, ar pasirinktas projektas, padalinys ar kitas objektas.

Pagal attributeNr gaukite atributo aprašą. Naudokite metodą GetAttribute (Attributes/{AttributeNr}), šiame pavyzdyje nurodydami 172. Gautame apraše patikrinkite laukus attributeDataTypeCfgNr ir referencedTableCfgNr. Toliau pateikta aktuali atsakymo dalis:

{
  "attributeNr": 172,
  "attributeCategoryName": "EmployeContract",
  "name": "Projektų pasirinkimas",
  "attributeDataTypeCfgNr": 10,
  "referencedTableCfgNr": 12
}

attributeDataTypeCfgNr: 10 reiškia, kad atributo tipas yra SystemObject. Laukas referencedTableCfgNr: 12 nurodo pasirinkto objekto srities kodą.

Išsiaiškinkite, ką reiškia objekto srities kodas. Dokumentacijos skiltyje Global naudokite metodą Get configuration data by index ir kaip indeksą nurodykite GlobalScopes. Gautame configurationItems sąraše raskite įrašą, kurio configurationNumber sutampa su atributo referencedTableCfgNr. Šiame pavyzdyje ieškome reikšmės 12:

{
  "configurationNumber": 12,
  "name": "Project_Project",
  "description": "Project"
}

Šis įrašas parodo, kad kodas 12 reiškia projektų sritį. Todėl pradiniame atributo reikšmės atsakyme referencedPrimaryKeyNr: 140 yra projekto ID, o value: "Kamanių avilys" – pasirinkto projekto pavadinimas.

Jei reikia daugiau pasirinkto objekto duomenų, kreipkitės į jo GET metodą. Šiame pavyzdyje dokumentacijos skiltyje Projects pasirinkite projekto gavimo pagal ID metodą ir perduokite 140. Kitų sistemos objektų atveju pasirinkite nustatytai sričiai skirtą metodą, jei jis pateiktas API dokumentacijoje.

referencedTableCfgNr pasako, kokios srities objekto ieškoti, o referencedPrimaryKeyNr – kurį konkretų tos srities įrašą gauti. Objekto tipo nenustatinėkite vien pagal atributo ar jo reikšmės pavadinimą.