Webhook pranešimai ir apdorojimo rezultatai

Webhook pranešimai ir apdorojimo rezultatai

Kaip veikia Webhook?

Kai BSS įvyksta sukonfigūruotą sritį atitinkantis įvykis, BSS į nurodytą adresą išsiunčia HTTP POST užklausą. Užklausos request body pateikiama informacija apie įvykį.

Vienoje užklausoje gali būti perduodama iki 100 įvykių. Jei perduotinų įvykių yra daugiau, jie siunčiami keliomis užklausomis.

Pavyzdžiui, gavusi informaciją, kad darbo sutartis buvo pakeista, jūsų sistema gali pagal Webhook pateiktą identifikatorių iškviesti atitinkamą BSS API GET metodą ir pasiimti naujausius sutarties duomenis.

Kokius objektus galima stebėti?

Konkrečios sritys, apie kurių pasikeitimus norite gauti Webhook pranešimus, nustatomos BSS ERP programos nustatymų grupėje WebHook application, nustatyme Sritys (Document, Employee, StaffContract, Invoice). Galima nurodyti vieną arba kelias sritis. Jei nurodomos kelios sritys, jų reikšmės atskiriamos kableliais.

Kokius įvykius galima gauti?

Laukas eventType parodo, kas įvyko su objektu arba kaip baigėsi jo apdorojimas.

Kokią informaciją gausite Webhook pranešime?

Vienas Webhook įvykis gali atrodyti taip:

{
  "entityNr": 12345,
  "entityType": "document",
  "eventType": "modified",
  "eventDate": "2025-10-01T23:12:01.987",
  "recordVersion": 1234567890,
  "metadata": {
    "documentNumber": "DOC-00012345"
  }
}

Kaip suprasti entityNr?

entityNr reikšmė priklauso nuo entityType. Pagal šį identifikatorių galima kreiptis į atitinkamą BSS API metodą ir pasiimti detalesnę objekto informaciją.

Kam naudojamas metadata?

metadata pateikia papildomas objekto identifikavimo reikšmes. Jos priklauso nuo entityType ir kai kuriais atvejais nuo eventType.

correlationId galima naudoti Webhook pranešimui susieti su pradine API užklausa. Kai Webhook grąžina pradinėje užklausoje perduotą X-Correlation-ID reikšmę, pagal ją galima nustatyti, su kuria konkrečia užklausa susijęs gautas rezultatas.

Ką daryti gavus warning?

eventType = warning reiškia, kad apdorojimo metu įvyko nekritinė problema, tačiau ji nesustabdė tolimesnio proceso. Todėl vien gavus warning nereikėtų laikyti visos operacijos nepavykusia.

Informaciją apie perspėjimą rasite outcomes masyve. Laukas code nurodo rezultatą, o outcome pateikia detalesnį jo paaiškinimą.

{
  "entityType": "invoice",
  "eventType": "warning",
  "eventDate": "2026-04-21T14:39:38.06",
  "metadata": {
    "correlationId": "FIZNET-00000876",
    "filename": "INV_20260421_143850_FIZNET-00000876.xml",
    "invoiceNumber": "AKV-invoiceTestv35",
    "serialNumber": "AKV"
  },
  "outcomes": [
    {
      "code": "INV6000",
      "outcome": "Failed to resolve budget amount owner: Type [TaxRateType] Code [244111]"
    }
  ]
}

Ką daryti gavus failed?

eventType = failed reiškia, kad atitinkamo objekto apdorojimas nepavyko. Klaidos priežastį pirmiausia tikrinkite outcomes masyve.

[
  {
    "entityType": "invoice",
    "eventType": "failed",
    "eventDate": "2026-04-13T01:05:36.297",
    "metadata": {
      "correlationId": "9999999995555555555",
      "filename": "INV_20260413_010321_9999999995555555555.xml",
      "invoiceNumber": "AKV-invoiceTestv22",
      "serialNumber": "AKV"
    },
    "outcomes": [
      {
        "code": "INV0001",
        "outcome": "Invoice item product code is missing: Row Nr [1]"
      }
    ]
  }
]

Gavę failed, pagal code nustatykite klaidos tipą, o lauke outcome ieškokite detalesnės priežasties. Sąskaitų atveju metadata pateikiamos reikšmės, tokios kaip correlationId, filename, invoiceNumber ar serialNumber, padeda nustatyti, su kuria sąskaita ar pradine užklausa susijusi klaida.

Jei objektas dėl klaidos apskritai nebuvo sukurtas, entityNr ir recordVersion gali būti null. Tokiu atveju objekto identifikavimui naudokite metadata informaciją.

Sąskaitų Webhook klaidų ir perspėjimų kodai

Sąskaitų warning ir failed Webhook pranešimuose outcomes pateikiamas rezultato kodas. Lentelėje nurodyta, su kuriuo eventType šiuo metu grąžinamas kiekvienas kodas.

INV6000 yra perspėjimo kodas. Kiti lentelėje pateikti kodai žymi klaidas. Kodai INV1000–INV1006, INV4000–INV4001 ir INV9999 gali būti grąžinami kartu su detalesne klaidos priežastimi lauke outcome.

Ką jūsų sistema turi atsakyti BSS?

Priėmusi Webhook pranešimą jūsų sistema turi grąžinti:

202 Accepted

Taip BSS patvirtinama, kad Webhook pranešimas buvo sėkmingai priimtas. Jei grąžinamas nesėkmingas HTTP statusas, BSS bandys pranešimą siųsti pakartotinai, kol jis bus sėkmingai patvirtintas.

Kas nutinka, jei Webhook pranešimo nepavyksta pristatyti?

Jei BSS negauna sėkmingo pranešimo gavimo patvirtinimo, Webhook pranešimas siunčiamas pakartotinai. Jei gavėjo servisas laikinai nepasiekiamas, jam vėl pradėjus veikti siunčiami likę nuo paskutinio sėkmingai patvirtinto perdavimo pranešimai.

Kodėl po vieno veiksmo galima gauti kelis pranešimus?

Vienas vartotojo ar API veiksmas nebūtinai reiškia vieną Webhook įvykį. Pavyzdžiui, kuriant sąskaitą gali būti sukuriama pati sąskaita ir su ja susijęs dokumentas. Jei sukonfigūruotos abi sritys, galima gauti atskirą invoice ir atskirą document įvykį.

Sąskaitų atveju Webhook gali būti generuojamas ne tik pakeitus pagrindinę sąskaitos informaciją. Pranešimas taip pat gali būti sukuriamas keičiant su sąskaita susijusius duomenis, pavyzdžiui, pirkėją, pardavėją, mokėtoją, naudos gavėją, sąskaitos eilutes, Lot/Batch/Serial informaciją ar detalizacijas.