Sąskaitų išrašymas iš Jūsų sistemos

Šiame puslapyje aprašyta visa seka, kuria Jūsų sistema (CRM, užsakymų valdymas, el. parduotuvė) išrašo pardavimo sąskaitą JARS Apskaita ir gauna jos PDF, kurį galima siųsti klientui. Tą pačią seką naudojame ir patys, kai išrašome sąskaitas iš savo paslaugų parduotuvių. Bendra API apžvalga ir raktų valdymas aprašyti puslapyje JARS API.

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

Seka trumpai

Prieš pradedant

Vieną kartą paruoškite:

• API raktą — Nustatymai → API raktai. Svarbu, kas jį kuria: žr. toliau skyrių „API raktas ir teisės“.
• Numeracijos seriją — Nustatymai → Įmonės nustatymai → Numeracija. Jos prefiksą siųsite lauke series (pardavimo sąskaitoms numatytoji serija yra SF). Oficialų numerį JARS suteikia pats, tvirtinant sąskaitą.
• PVM kodo _id — GET /api/vat-codes.
• Operacijų šablono _id — GET /api/templates, šablonas su sourceType: "SALES_INVOICE", tinkantis kliento šaliai (Lietuva, ES, ne ES).

PVM kodų ir šablonų sąrašai keičiasi retai: gaukite juos vieną kartą ir laikykite savo sistemoje.

1. Klientas

Pirmiausia ieškokite kliento pagal savo sistemos identifikatorių, laikomą lauke externalCode:

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://app.jars.lt/api/partners?externalCode=CRM-12345"

Atsakymas yra masyvas. Jei jis tuščias, sukurkite klientą:

curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "UAB Klientas",
    "type": "CUSTOMER",
    "externalCode": "CRM-12345",
    "companyCode": "<įmonės kodas>",
    "vatCode": "<PVM kodas, jei yra>",
    "country": "LT",
    "billingEmail": "buhalterija@klientas.example",
    "correspondenceLanguage": "lt"
  }' \
  "https://app.jars.lt/api/partners"

correspondenceLanguage (lt, en arba ru) lemia sąskaitos PDF kalbą ir numatytojo laiško kalbą. Jį nustatykite kuriant klientą.

2. Sąskaitos juodraštis

curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SALES",
    "externalCode": "ORDER-2026-0042",
    "series": "SF",
    "date": "2026-10-06",
    "dueDate": "2026-10-20",
    "partnerId": "<kliento _id>",
    "operationTemplateId": "<šablono _id>",
    "currency": "EUR",
    "exchangeRate": 1,
    "lines": [
      {
        "lineNo": 1,
        "description": "Konsultacija",
        "quantity": 1,
        "unitPrice": 99.00,
        "unitCode": "vnt",
        "discountPercent": 0,
        "lineSubtotal": 99.0000,
        "vatCodeId": "<PVM kodo _id>",
        "vatRate": 21,
        "vatAmount": 20.79,
        "lineTotal": 119.79
      }
    ],
    "subtotal": 9900,
    "vatTotal": 2079,
    "total": 11979,
    "notes": "Ačiū, kad renkatės mus"
  }' \
  "https://app.jars.lt/api/invoices"

Atsakymas (201) yra sukurta sąskaita su _id ir internalNumber. Kelios taisyklės:

• Pinigų vienetai skiriasi. Eilutės sumos (unitPrice, lineSubtotal, vatAmount, lineTotal) rašomos eurais su kableliu (iki 4 skaitmenų), o dokumento sumos (subtotal, vatTotal, total) — centais. 99,00 € eilutė duoda "subtotal": 9900. Klaida čia — dažniausia: suma bus šimtą kartų per didelė arba per maža.
• Sąskaitos numerio nesiųskite. Pardavimo sąskaitai number suteikiamas iš series tvirtinant. internalNumber (SF-2026-00001) yra vidinis registracijos numeris, jis spausdinamoje sąskaitoje nerodomas.
• PVM suvestinė (vatSummary) apskaičiuojama pati, jos siųsti nebūtina.
• Lauką externalCode visada nurodykite — jis padaro užklausą saugiai kartojamą (žr. toliau).
• Sąskaitą galima keisti (PUT /api/invoices/{id}), kol ji yra DRAFT.

3. Patvirtinimas

curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  "https://app.jars.lt/api/invoices/<sąskaitos _id>/post"

Atsakyme invoice.number yra oficialus numeris (pvz., SF-00001). Po patvirtinimo sąskaita nebekeičiama, išskyrus pastabas ir mokėjimo terminą. Patvirtinimas sukuria žurnalo įrašą; įmonėms, kurios veda supaprastintą apskaitą (individuali veikla, verslo liudijimas), įrašo nėra, tačiau numeris suteikiamas taip pat.

4. PDF

Sąskaitos PDF gaunamas dviem kvietimais:

# 4a. Sugeneruoti PDF (paprastai kelios sekundės)
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  "https://app.jars.lt/api/invoices/<sąskaitos _id>/pdf"
# {"s3Key":"…","sizeBytes":125432}

# 4b. Atsisiųsti failą
curl -s -H "Authorization: Bearer $API_KEY" \
  -o sf-00001.pdf \
  "https://app.jars.lt/api/invoices/<sąskaitos _id>/pdf"

• Pirmiausia POST, paskui GET. Kol PDF nesugeneruotas, GET atsako 404 su pranešimu PDF not yet generated. Atsakyme į POST failo nėra — jį atsiunčia tik GET.
• POST galima kartoti: jis sugeneruoja PDF iš naujo. Užklausos laukimo ribą nustatykite bent 30 sekundžių.
• Kalba imama iš kliento kortelės (correspondenceLanguage). Pakeitus kliento kortelę, PDF reikia sugeneruoti iš naujo.
• Pakeitus patvirtintos sąskaitos pastabas ar mokėjimo terminą, ankstesnis PDF nebelaikomas: GET vėl atsakys 404, kol vėl iškviesite POST.
• PDF failai saugomi metus. Senesnį PDF GET sugeneruoja iš naujo pats, todėl klaidos nebus, bet gausite šiandienos išvaizdos dokumentą.
• Atsisiuntimo failo pavadinimas — Sąskaita <numeris>.pdf (antraštėje Content-Disposition).

5. Išsiuntimas klientui

Yra du būdai.

A. Siunčiate patys. Pasiimkite PDF (4b) ir išsiųskite iš savo pašto sistemos, savo siuntėjo adresu ir savo laišku. Taip daro ir mūsų pačių integracijos: laiško tekstas, siuntėjas ir pakartojimai lieka Jūsų kontrolėje.

B. Siunčia JARS.

curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "buhalterija@klientas.example",
    "subject": "Sąskaita SF-00001",
    "bodyHtml": "<p>Sveiki, siunčiame sąskaitą.</p>"
  }' \
  "https://app.jars.lt/api/invoices/<sąskaitos _id>/send-email"
# {"ok":true,"sentTo":"…","sentAt":"…"}

• Privalomas tik email (vienas gavėjas). subject ir bodyHtml neprivalomi: nenurodžius, JARS parašo standartinį laišką kliento kalba, o tema visada lietuviška (Sąskaita faktūra SF-00001 (Jūsų įmonė)). Nurodytas bodyHtml pakeičia visą laiško tekstą.
• PDF pridedamas automatiškai. Jei jo dar nėra arba jis pasenęs, JARS sugeneruoja jį prieš siųsdamas, todėl 4 žingsnio galima nevykdyti.
• Laiškas siunčiamas iš JARS adreso noreply@jars.lt, o Reply-To — Jūsų įmonės el. paštas iš įmonės nustatymų (Nustatymai → Įmonės nustatymai). Jei jo nėra, klientas neturės kam atsakyti. Pats siuntėjo adresas keičiamas negali. Jei laiškas turi eiti iš Jūsų domeno, rinkitės A būdą.
• Siunčiama tik patvirtinta pardavimo sąskaita. Sėkmingai išsiuntus, sąskaitoje užrašoma, kada ir kam (emailSentAt, emailSentTo), o audito žurnale atsiranda įrašas.
• Pakartotinis kvietimas išsiunčia dar vieną laišką: jokios apsaugos nuo dubliavimo nėra, todėl neautomatizuokite kartojimo „kol nepavyks“ be savo žymos, kad laiškas jau išsiųstas.

Kartojimas po klaidos

Tinklas nutrūksta, procesas užstringa, atsakymas neatkeliauja. Tada svarbiausia neišrašyti antros sąskaitos tam pačiam užsakymui. Seka saugiai kartojama, jei prieš kiekvieną žingsnį pasitikrinate, ar jis jau atliktas:

1. Prieš kurdami juodraštį, ieškokite pagal externalCode: GET /api/invoices?externalCode=ORDER-2026-0042. Radę — tęskite nuo jos. externalCode yra unikalus: jei du procesai kuria vienu metu, antrasis gauna 409 su kodu DUPLICATE_KEY. Tada tiesiog suraskite laimėtojo sąskaitą ir tęskite.
2. Patvirtinimas nėra kartojamas. Antras /post atsako 400 su kodu DOC_NOT_DRAFT. Tai ne klaida: perskaitykite sąskaitą (GET /api/invoices/{id}) ir paimkite number. Jei kitas procesas tvirtina tą pačią sąskaitą šią akimirką, gausite INVOICE_POSTING_IN_PROGRESS: palaukite ir perskaitykite iš naujo.
3. PDF generavimas kartojamas laisvai, nes rezultatas tas pats.
4. Siuntimas — vienintelis žingsnis, kurio kartoti negalima aklai. Pažymėkite savo sistemoje, kad laiškas išsiųstas, o jei naudojate B būdą, pažiūrėkite sąskaitos emailSentAt.

Paprasčiausia schema: kiekvieną kartą pradėkite nuo sąskaitos paieškos pagal externalCode, o toliau žiūrėkite jos būseną (DRAFT ar POSTED) ir ar jau yra PDF. Savo sistemoje išsaugokite sąskaitos _id ir numerį, kai tik juos gaunate, kad kitas bandymas jų nebeieškotų.

API raktas ir teisės

• Raktas susietas su viena įmone ir veikia su jį sukūrusio naudotojo teisėmis. Savininko (OWNER) raktas gali tai, ką savininkas; buhalterio (ACCOUNTANT) raktas — ką buhalteris; stebėtojo (VIEWER) raktas gali tik skaityti, rašymo užklausas JARS atmeta. Rolių lentelė — puslapyje Naudotojai ir rolės.
• Rakto apriboti tik pardavimo sąskaitomis kol kas negalima. Rakto tipai yra du: pilnas (REST API) ir MCP raktas, kuris veikia tik MCP jungtyje ir REST API nepasiekia. Pilnas raktas gali daryti viską, ką leidžia jį sukūrusio naudotojo rolė, įskaitant kitų dokumentų skaitymą ir keitimą.

Kaip sumažinti riziką:

1. Raktą laikykite tik savo serveryje. Vadybininkė dirba Jūsų sistemoje, o ši kreipiasi į JARS. Raktas niekada neturi patekti į naršyklę, kompiuterį ar pašto programą. Tada svarbu tik tai, kokias užklausas siunčia Jūsų serveris, o jos fiksuotos: PVM kodai, partneriai, sąskaitos, PDF.
2. Nenaudokite savininko rakto. Sukurkite atskirą naudotoją su buhalterio role (Nustatymai → Nariai) ir raktą generuokite jam: buhalterio rolė negali kviesti naudotojų, keisti rolių ir šalinti įmonės.
3. Kiekvienai integracijai — atskiras raktas su aiškiu pavadinimu, pvz., „Vadybininkų sąskaitų sistema“. Atšaukus raktą (Nustatymai → API raktai), jis nustoja veikti iškart.
4. Žiūrėkite audito žurnalą (Ataskaitos → Pakeitimų žurnalas): kiekvienas raktu atliktas pakeitimas pažymėtas kaip atliktas per API ir nurodo rakto pavadinimą.
5. Laikotarpis, kurį uždarėte (Periodas uždarytas iki), apsaugotas ir nuo API: į jį sąskaitų įrašyti nepavyks.

Dažniausi atsakymai

Pilnas sąskaitos laukų sąrašas ir klaidų kodai pateikti API nuorodoje.