Kasos kvitai iš Jūsų sistemos

Šiame puslapyje aprašyta, kaip Jūsų sistema (sandėlio valdymas, CRM, užsakymų valdymas) perduoda pardavimą grynaisiais į JARS Apskaita. Pardavimas tampa kvito juodraščiu: kasininkas jį atveria JARS kasos programoje, patikrina ir užregistruoja vienu mygtuku, o programa atspausdina kvitą. Prekių antrą kartą vesti nereikia.

Puslapis skirtas Jūsų sistemos programuotojui: paruoštos jungties nėra, aprašytos užklausos, kurias siunčia Jūsų sistema. Bendra API apžvalga ir raktų valdymas aprašyti puslapyje JARS API, o sąskaitų faktūrų išrašymas — puslapyje Sąskaitų išrašymas iš Jūsų sistemos.

Visi pavyzdžiai naudoja https://app.jars.lt/api ir antraštę Authorization: Bearer jars_sk_….

Seka trumpai

Per API kvitas tik parengiamas. Registravimas VMI ir spausdinimas vyksta kasos programoje, kai kasininkas patvirtina pardavimą.

Prieš pradedant

Vieną kartą paruoškite:

• API raktą — Nustatymai → API raktai. Naujo rakto laukelyje „Rakto tipas“ pasirinkite „Pilna prieiga“: numatytasis tipas „DI asistentas“ veikia tik MCP adresu, o REST API tokį raktą atmeta (403 API_KEY_MCP_SCOPE_ONLY). Raktas veikia su jį sukūrusio naudotojo teisėmis; kaip sumažinti riziką, aprašyta skyriuje API raktas ir teisės.
• Kasos aparatą — Nustatymai → Atsiskaitymo vietos (žr. Kasos aparato sukūrimas). Jūsų sistemai reikės jo kodo (laukas „Kodas“, pvz., K1): jį siųsite lauke registerCode. Aparatas turi būti aktyvus, jo kortelėje turi būti parinkta „Kvitų serija“, o kasos programa turi būti su juo susieta (žr. Įrenginio susiejimas). Fiskaliniams kvitams aparatas turi būti užregistruotas VMI (žr. Registracija VMI (i.EKA)).
• Prekių ir PVM kodus. Prekės (Prekės ir paslaugos) ir PVM kodai (Nustatymai → PVM kodai) turi būti JARS tais kodais, kuriuos siųs Jūsų sistema. Nežinomas kodas nėra spėjamas ir nekeičiamas kitu: toks pardavimas atmetamas.
• Kasos aparato operacijų šabloną — parenkamas kasos aparato kortelėje, žr. toliau. Be jo kasininkas juodraščio užregistruoti negalės.

Kasos aparato operacijų šablonas

Kvito juodraštis operacijų šabloną gauna iš kasos aparato, kuriam jis skirtas. Šabloną parinkite vieną kartą kiekvienam kasos aparatui, jo kortelėje: Nustatymai → Atsiskaitymo vietos → atverkite kasos aparatą → laukas „Per API gaunamų kvitų šablonas“ → „Išsaugoti“. Sąraše siūlomi aktyvūs kasos pardavimo šablonai; standartinis turi kodą CASH_SALE.

• Šablonas nurodo, į kurias apskaitos sąskaitas įtraukiamas pardavimas. Jei įmonė kasos pardavimams naudoja savo šabloną, parinkite jį: visi šablonai matomi Nustatymai → Operacijų šablonai.
• Šis nustatymas taikomas tik per API perduotiems kvitams. Kasos programoje ir apskaitos programos kasos orderio kortelėje šablonas parenkamas pačiame dokumente.
• Kol šablonas neparinktas, juodraščiai sukuriami be jo. Toks juodraštis kasos programoje atveriamas tik peržiūrai, su pranešimu „Šio orderio čia atidaryti negalima — trūksta operacijų šablono“, ir mygtuko jam užregistruoti nėra. Užklausa POST /api/cash-orders/{id}/post tokiam juodraščiui atsako 400 TEMPLATE_REQUIRED, kai kvitas turi būti įtrauktas į apskaitą žurnalo įrašu. Jau sukurtam juodraščiui šabloną galima parinkti apskaitos programoje: Kasa → atverti juodraštį → laukas „Šablonas“ → išsaugoti.
• Jei kortelėje po šiuo lauku rašoma, kad nurodytas šablonas nebeegzistuoja arba nėra kasos šablonas, parinkite kitą. Kol to nepadaryta, šiam kasos aparatui perduodami pardavimai atmetami (OPERATION_TEMPLATE_NOT_FOUND arba OPERATION_TEMPLATE_NOT_CASH).

Tą patį galima padaryti per API, jei kasos aparatus paruošia Jūsų sistema. Šablono _id paimkite iš šablonų sąrašo. Standartinis pardavimo per kasą šablonas turi kodą CASH_SALE ir sourceType: "CASH":

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://app.jars.lt/api/templates?code=CASH_SALE"

Kasos aparato _id raskite kasos aparatų sąraše pagal lauką code:

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://app.jars.lt/api/cash-registers"

Tada įrašykite šabloną kasos aparatui. Siunčiamas tik keičiamas laukas:

curl -s -X PUT \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationTemplateId": "<šablono _id>" }' \
  "https://app.jars.lt/api/cash-registers/<kasos aparato _id>"

_id nukopijuokite iš atsakymo, nerašykite ranka. Jei toks šablonas įmonėje neegzistuoja, atsakoma 400 OPERATION_TEMPLATE_NOT_FOUND, o jei jis nėra kasos šablonas (sourceType ne CASH) — 400 OPERATION_TEMPLATE_NOT_CASH. Kasos aparatas lieka nepakeistas.

1. Pardavimo perdavimas

curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "externalCode": "ORDER-2026-0042",
        "registerCode": "K1",
        "date": "2026-10-10",
        "amountTendered": 6050,
        "lines": [
          {
            "productCode": "FILTRAS-10",
            "quantity": 1,
            "unitPrice": 5000,
            "vatCode": "PVM21"
          }
        ]
      }
    ]
  }' \
  "https://app.jars.lt/api/sales/receipts"

Atsakymas visada 200, su vienu rezultatu kiekvienam pardavimui, ta pačia tvarka kaip užklausoje:

{
  "results": [
    { "status": "created", "externalCode": "ORDER-2026-0042", "id": "<kvito _id>", "autoPost": false }
  ]
}

Vienoje užklausoje galima siųsti iki 500 pardavimų. Didesnė užklausa atmetama visa (400 BATCH_TOO_LARGE), nė vienas pardavimas neapdorojamas. Atsakymo laukas autoPost registravimo nekeičia: kiekvienas sukurtas kvitas lieka juodraščiu, kol jį užregistruoja kasininkas.

Oficialiame TypeScript SDK (@jars-lt/jars-app-sdk) tą pačią užklausą siunčia metodas salesReceipts.ingest(items).

Pardavimo laukai

Eilutės laukai:

Kelios taisyklės:

• Kainos rašomos centais ir be PVM. "unitPrice": 5000 reiškia 50,00 € be PVM; su 21 % PVM eilutės suma yra 60,50 €. Tai skiriasi nuo sąskaitų faktūrų, kur eilutės kaina rašoma eurais. Kasos aparato nustatymas „Kainos vedamos su PVM“ keičia tik tai, ką kasininkas veda kasos programoje, o ne tai, ką priima API: atsiuntus kainą su PVM, PVM būtų priskaičiuotas dar kartą.
• PVM JARS apskaičiuoja pats pagal PVM kodo tarifą: eilutės suma be PVM yra kiekis × kaina, suapvalinta iki cento, o PVM skaičiuojamas nuo jos.
• amountTendered privalomas kasos aparatui su i.EKA: gauta pinigų suma yra privalomas fiskalinio kvito rekvizitas. Ji negali būti mažesnė už mokėtiną sumą. Kai kasos aparate įjungtas nustatymas „Apvalinti grynųjų sumas iki 5 centų“, mokėtina suma yra suapvalinta: 18,98 € kvitui reikia bent 1900. Jei tikroji gauta suma siuntimo metu dar nežinoma, siųskite mokėtiną sumą: laukelį „Gauta“ kasininkas pataisys kasoje.
• Kasos aparatas su i.EKA registruoja tik atsiskaitymus grynaisiais. Pardavimas su paymentMethod CARD, ONLINE ar TRANSFER tokiam aparatui atmetamas (NON_CASH_NOT_SUPPORTED).
• Įmonė, taikanti smulkiojo verslo schemą, savo kvituose PVM neskaičiuoja: eilutė su PVM kodu, kurio tarifas ne 0 %, atmetama (SVS_RECEIPT_VAT_NOT_ALLOWED).
• Kasos aparatas turi būti aktyvus. Deaktyvuotam aparatui skirtas pardavimas atmetamas (CASH_REGISTER_INACTIVE).

2. Juodraščio numeris

Kvito numeris iš kasos aparato kvitų serijos suteikiamas iškart, kuriant juodraštį, o ne tada, kai kasininkas jį užregistruoja. Perskaitykite jį:

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://app.jars.lt/api/cash-orders/<kvito _id>"

Atsakyme number yra kvito numeris (pvz., KV-00023), status — DRAFT, amount, subtotal ir vatTotal — JARS apskaičiuotos sumos centais. Numerį parodykite savo sistemoje tam, kas siunčia pirkėją prie kasos: pagal jį kasininkas randa juodraštį.

Ištrynus juodraštį, jo numeris lieka nepanaudotas, ir serijoje atsiranda tarpas. Numeris panaudojamas ir tada, kai pardavimo nepavyksta išsaugoti (SAVE_FAILED, pvz., dėl neperskaitomos datos). Todėl siųskite tik tuos pardavimus, kurie tikrai bus užregistruoti, o klaidingą juodraštį geriau pataisyti kasoje, negu ištrinti ir siųsti iš naujo.

3. Kasininko darbas kasoje

Kvitą užregistruoja kasininkas JARS kasos programoje (stalinė programa, žr. Kasininko darbo vieta → Pardavimo apiforminimas). Kasos programa pati juodraščių nekuria, bet parengtus atveria.

1. Juodraščio radimas. Skiltyje Kvitai, sąraše „Šiandienos operacijos“, juodraštis rodomas su savo numeriu, suma ir žyma „Juodraštis“. Sąrašas atnaujinamas paleidus programą ir užbaigus dokumentą, todėl ką tik atsiųsto juodraščio jame gali dar nebūti. Kasos aparate su i.EKA virš sąrašo yra paieškos laukelis: kasininkas įveda kvito numerį (arba jo pabaigą, pvz., -00023) ir spaudžia „Ieškoti“, o vienintelis rastas kvitas atveriamas iškart.
2. Patikrinimas. Juodraštis atveriamas toje pačioje pardavimo formoje kaip ir naujas pardavimas: matomos eilutės, sumos „Be PVM“, „PVM“ ir „Viso“, o laukelyje „Gauta“ įrašyta Jūsų atsiųsta suma. Kasininkas gali pataisyti kiekį, kainą, pridėti ar pašalinti eilutę ir įrašyti tikrąją gautą sumą.
3. Registravimas. Paspaudus „Užbaigti pardavimą“, kvitas išsaugomas toks, koks matomas formoje, užregistruojamas VMI per i.EKA ir atspausdinamas (arba išsiunčiamas pirkėjui el. paštu, jei kasininkas įvedė adresą). Kvito būsena tampa „Registruota“.

Ką verta žinoti iš anksto:

• Užregistruojama tai, ką patvirtino kasininkas. Jei jis pakeitė eilutes, kvite bus pakeistos eilutės ir sumos. Kvito data tampa registravimo diena, kad ir kokią date atsiuntėte.
• Sumas forma perskaičiuoja pati. Kai kasos aparate įjungta „Kainos vedamos su PVM“, eilutės suma skaičiuojama nuo kainos su PVM, todėl retais atvejais ji vienu centu skiriasi nuo sumos, kurią matėte 2 žingsnyje.
• Mygtukas „Atšaukti“ juodraščio neištrina. Kasos aparate su i.EKA suformuojamas nefiskalinis kvito panaikinimo dokumentas, o juodraštis lieka su būsena „Anuliuota“ ir savo numeriu (žr. Prekių grąžinimas ir kvito panaikinimas).
• Naršyklėje fiskalinis kvitas neregistruojamas: apskaitos programoje (Kasa) juodraštis matomas, bet kasos aparato su i.EKA kvito ten užregistruoti negalima, rodoma „Fiskalinės operacijos galimos tik darbalaukio programoje“. Kasos aparato be i.EKA juodraštį galima užregistruoti ir ten, mygtuku „Registruoti“.
• Per API juodraščio neregistruokite. Užklausa POST /api/cash-orders/{id}/post kvito neatspausdina ir pirkėjui jo neišduoda; tai atlieka kasos programa.

4. Rezultato patikrinimas

JARS apie užregistravimą Jūsų sistemai nepraneša. Būseną sužinosite perskaitę kvitą ta pačia užklausa kaip 2 žingsnyje:

Atsakymas 404 reiškia, kad juodraštis ištrintas.

Kartojimas po klaidos

Tinklas nutrūksta, atsakymas neatkeliauja. Tokiu atveju siųskite tą pačią užklausą dar kartą: pardavimas atpažįstamas pagal externalCode, ir antro kvito nebus.

• Pakartotas pardavimas grąžinamas kaip duplicate, su esamo kvito _id ir tuo pačiu HTTP 200. Atskirai tikrinti, ar pardavimas jau perduotas, nereikia.
• duplicate grąžinamas, kad ir kokia esamo kvito būsena: juodraštis, užregistruotas ar anuliuotas. Jei kasininkas kvitą atšaukė, tas pats externalCode naujo juodraščio nebesukurs. Pardavimą, kuris vis dėlto vyksta, siųskite su nauju externalCode.
• Ištrynus juodraštį, jo externalCode vėl laisvas: pakartotas siuntimas sukurs naują juodraštį su nauju numeriu.
• Atmestas pardavimas (error) externalCode neužima. Pašalinkite priežastį ir siųskite tą patį pardavimą su tuo pačiu externalCode.
• Vienoje užklausoje externalCode negali kartotis: antrasis toks pardavimas atmetamas (DUPLICATE_IN_BATCH).
• Siųstame pardavime pakeitimų nebepriimama. Pakartotas siuntimas su tuo pačiu externalCode esamo juodraščio nekeičia, net jei eilutės kitos. Juodraštį taiso kasininkas kasoje arba buhalteris apskaitos programoje (Kasa).

Savo sistemoje išsaugokite kvito _id ir numerį, kai tik juos gaunate.

Išbandymas demo aplinkoje

Visą seką galima išbandyti su kasos aparatu, užregistruotu VMI demo aplinkoje, nesiunčiant nieko į tikrąją aplinką. Tokį aparatą užregistruojate patys: kasos aparato kortelėje paspauskite „Registruoti i.EKA“ ir pasirinkite aplinką „Demo“ (žr. Registracija VMI (i.EKA)). API užklausos, juodraščio atvėrimas kasoje ir registravimas veikia taip pat kaip tikrojoje aplinkoje, tik dokumentai siunčiami į VMI bandomąją paslaugą.

• Demo aplinkoje užregistruoto aparato operacijos į apskaitą neįtraukiamos, o kvitų antraštėje spausdinama „DEMONSTRACINĖ APLINKA“ ir „Dokumentas pirkėjui neišduodamas“. Išimtis — testinės įmonės, kuriose tokios operacijos įtraukiamos kaip įprastos.
• Kasos aparatas registruojamas vieną kartą, todėl tikrajai aplinkai skirtas aparatas yra kita kortelė su kitu kodu. Pereidami pakeiskite registerCode ir naujam aparatui taip pat parinkite „Kvitų seriją“ bei nustatykite operacijų šabloną.
• Kaip kasos aparatas registruojamas tikrojoje aplinkoje ir kiek tai kainuoja, aprašyta puslapyje app.jars.lt/ieka.

Klaidų kodai

Pardavimo klaidos grąžinamos jo rezultate (status: "error"), o visa užklausa vis tiek atsako 200. Lauke message yra paaiškinimas anglų kalba, kuriame nurodytas kodas arba eilutės numeris.

Atsakymai, kai atmetama visa užklausa:

Jei kasininkui nepavyksta užregistruoti kvito kasoje, priežastis rodoma kasos programoje; dažniausios aprašytos skyriuje Klaidos ir gedimai.

Visi užklausų laukai ir schemos pateikti API nuorodoje.