API dokumentacija

Integruokite Robodam Scan į savo procesus: nusiųskite sąskaitos PDF ir gaukite struktūrizuotus duomenis (JSON), o prireikus — ir apskaitos importo failą (Rivilė .eip arba Centas XML). Tinka „Power Automate", cron, Postman, scenarijams.

Žemiau {BASE} — API adresas https://scan-api.robodam.com (NE programos/prisijungimo adresas scan.robodam.com — jis aptarnauja tik naršyklės sąsają). Stebėsenai: GET {BASE}/health (šakninis kelias, ne po /api/v1) grąžina {"status":"healthy"}.

1. Autentifikacija

Kiekviena užklausa turi turėti jūsų asmeninį „Bearer“ raktą antraštėje. Automatizacijai (Power Automate, cron, skriptai) susikurkite nuolatinį API raktą: Nustatymai → Paskyra → API raktai — raktas (rbs_…) parodomas tik kartą, galioja kol jo neatšauksite. Greitiems rankiniams testams tinka ir viršuje esantis „Testavimo raktas", tačiau jis laikinas (sesijos raktas) — automatiniams srautams jo nenaudokite.

Authorization: Bearer <jūsų-raktas>

2. Sąskaitos nuskaitymas (PDF → JSON)

Sinchroninis nuskaitymas: nusiunčiate PDF ir tame pačiame atsakyme gaunate duomenis (nereikia papildomų užklausų / polling).

Užklausa

multipart/form-data, dokumentas perduodamas lauke file. Priimami formatai: PDF ir nuotraukos (JPG / PNG / HEIC) — nuotraukos serveryje konvertuojamos į PDF automatiškai. Neprivalomi parametrai:

Apribojimai: tik PDF; iki 10 MB; iki 20 puslapių (administratorius gali pakelti konkrečiam klientui; per /extract-direct riba atskira ir žemesnė); 30 užklausų/min. Kelių sąskaitų PDF čia traktuojamas kaip vienas dokumentas (skaidymas vyksta tik per /upload).

Pavyzdys (cURL)

curl -X POST "{BASE}/api/v1/invoices/extract-direct" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@saskaita.pdf"

Atsakymas (200 OK)

{
  "success": true,
  "filename": "saskaita.pdf",
  "confidence_score": 100,        // 0–100, AI pasitikėjimas
  "auto_validated": true,         // true kai confidence_score >= 85
  "validation_warnings": [],      // tekstas žmogui
  "validation_issues": [],        // tas pats mašinai — su kodu (žr. žemiau)
  "risk_flags": [],               // ką verta patikrinti prieš knygojant
  "document_type": "invoice",     // invoice / credit_note / receipt / unknown / ...
  "from_cache": false,
  "duplicate_of": null,
  "extracted_data": { ... },      // sąskaitos laukai (žr. 3 sk.)
  "export": null                  // užpildoma tik su include_export
}

3. Nuskaityti laukai (extracted_data)

Visi laukai neprivalomi — jei sąskaitoje lauko nėra, jis būna null arba praleidžiamas.

{
  "invoice_number": "SF Nr. 70",
  "invoice_date": "2026-05-29",     // YYYY-MM-DD
  "due_date": "2026-06-12",
  "currency": "EUR",
  "subtotal": 1100.0,               // suma be PVM
  "tax_amount": 231.0,              // PVM suma (nėra, kai 0%/be PVM)
  "tax_rate": 21,                   // dokumento PVM %, sveikas sk.
  "total_amount": 1331.0,           // suma su PVM
  "bank_account": "LT74...",
  "document_type": "invoice",
  "vendor": {                       // tiekėjas (pardavėjas)
    "name": "MB Decentrum",
    "company_code": "306265414",    // įmonės kodas
    "tax_id": "306265414",          // PVM kodas (LT... jei PVM mokėtojas)
    "address": "Ceikiniu g. 3, Lietuva"
  },
  "customer": {                     // pirkėjas
    "name": "UAB Robodam",
    "company_code": "...",
    "tax_id": "LT100017242115",
    "address": "Kaunas, Vytauto pr. 27"
  },
  "line_items": [
    {
      "description": "Programavimo paslaugos",
      "quantity": 1.0,
      "unit": "vnt",
      "unit_price": 1100.0,         // vieneto kaina be PVM
      "total": 1100.0,              // eilutės suma be PVM
      "tax_rate": 21,               // eilutės PVM % (jei nėra — dokumento tax_rate)
      "item_number": "..."          // tiekėjo prekės kodas, jei yra
    }
  ],
  "notes": "..."
}

Atsakyme gali būti ir _validation bei _recovery blokai — tai vidiniai diagnostikos duomenys, juos galite ignoruoti.

4. Kokybės signalai

confidence_score pasako, kiek esame tikri. Šie du laukai pasako, kas negerai — ir yra skirti programai, ne akiai. Abu visada yra atsakyme; švariam dokumentui — tušti sąrašai.

validation_issues — ką patikrinom mes

{
  "code": "total_mismatch",       // stabilus, pagal jį galima šakotis
  "field": "total_amount",
  "message": "Total amount (100.0) does not match calculated total (121.00)",
  "severity": "warning",          // warning | error
  "kind": "semantic"              // format | semantic | extraction
}

kind skiria mūsų patikrą (format — formatas, semantic — sumos ir datos) nuo modelio pastabos apie savo paties skaitymą (extraction). Pastarosios yra laisvas tekstas ir kodo neturi — jį prasimanyti reikštų pažadėti kontraktą, kurio nelaikytume. Dažniausi kodai: total_mismatch, line_sum_mismatch, tax_amount_mismatch,date_format, due_before_invoice, iban_checksum.Tekstinis validation_warnings lieka — jis skirtas parodyti žmogui.

risk_flags — ką verta patikrinti

Tai faktai, o ne verdiktai. Sprendimą priimate jūs, nes kryptį žinote jūs:

• own_company_in_vendor_slot — jūsų kliento įmonė yra pardavėjo lauke. Pirkimo sąskaitoje tai reiškia sukeistas puses; pardavimo sąskaitoje tai normalu.
• same_party_both_sides — ta pati įmonė abiejose pusėse. Nėra atvejo, kai tai teisinga.
• duplicate_invoice_number — tas pats tiekėjas jau atsiuntė sąskaitą tokiu pat numeriu. Laukas duplicate_of_invoice_number nurodo ankstesnės ID, sumą ir datą — būtent sumų skirtumas pasako, ar tiekėjas perrašė dokumentą, ar tiesiog atsiuntė pakartotinai. Failo dublikatų tikrinimas to nemato: perrašytas dokumentas yra kiti baitai.
• credit_note_signs_applied — dokumentas atpažintas kaip kreditinė, todėl total_amount,subtotal ir eilučių sumos priverstinai padarytos neigiamos. Skaičiai atsakyme gali nesutapti su ženklais, atspausdintais PDF faile.

Kodų sąrašas pildomas. Nepažįstamą kodą ignoruokite, o ne laikykite klaida — taip jūsų integracija nesulūš, kai pridėsime naują.

5. Pakartotinis siuntimas

Jei pakartotinai išsiunčiate tą patį failą (tie patys baitai, ta pati paskyra), o allow_duplicate yra false (numatyta) — grąžinamas ankstesnis nuskaitymas nemokamai(from_cache: true, duplicate_of rodo ankstesnį ID; AI iš naujo nepaleidžiamas). Taip „Power Automate" srautas, kas dieną perskaitantis tą patį aplanką, nėra apmokestinamas pakartotinai. Norėdami priverstinai nuskaityti iš naujo — perduokite allow_duplicate=true.

6. Apskaitos eksportas (Rivilė / Centas)

Failą galite gauti dviem būdais. Abu grąžina failą base64 formatu JSON viduje (content_base64) — jį iškoduokite ir išsaugokite.

A. Kartu su nuskaitymu (vienas failas)

Prie 2 sk. užklausos pridėkite parametrą include_export (rivile, centas arba finvalda) — atsakyme atsiras export laukas su tos sąskaitos failu:

export lauko struktūra tokia pati kaip paketinio atsakymo (žr. žemiau).

B. Pažymėtoms / filtruotoms sąskaitoms (paketas)

{format} = rivile, centas arba finvalda. Užklausos kūnas — arba konkretūs ID, arba filtrai (kaip sąskaitų sąraše, iki 1000):

{ "invoice_ids": ["<id1>", "<id2>"] }
// arba
{ "start_date": "2026-05-01", "end_date": "2026-05-31" }

Atsakymas — Rivilė (.zip su .eip failais):

{
  "format": "rivile",
  "filename": "Rivile_eksportas-20260612-061255.zip",
  "content_type": "application/zip",
  "content_base64": "UEsDBB...",   // base64 → baitai → išsaugoti kaip .xml
  "problems": [],                  // įspėjimai buhalteriui (žr. žemiau)
  "skipped_count": 0,
  "purchase_count": 1,
  "sale_count": 0
}

Atsakymas — Centas (.xml, arba .zip kai yra ir pirkimų, ir pardavimų):)

{
  "format": "centas",
  "filename": "Centas_eksportas-20260612-061255.xml",
  "content_type": "application/xml",   // arba application/zip
  "content_base64": "PD94bWw...",      // base64 → baitai → išsaugoti kaip .xml
  "problems": [],
  "skipped_count": 0,
  "purchase_count": 1,
  "sale_count": 0
}

problems — žmogui skirti įspėjimai (praleistos sąskaitos, 0%/atvirkštinio PVM klasė, kurią reikia patvirtinti) — parodykite juos prieš importą.

7. Įmonės nustatymai

Kai kurių reikšmių sąskaitoje nėra — jūsų įmonės kodas (pirkimui/pardavimui atskirti), PVM klasių kodai. Išsaugokite juos kartą, ir kiekvienas eksportas juos naudos:

{format} = rivile arba centas. PUT kūnas (nurodykite tik tai, ką norite nustatyti; kiti liks numatytieji). Laukai skiriasi pagal formatą:

Rivilė:

{ "config": {
    "own_company_code": "304827491",
    "own_vat_code": "LT100001738313",
    "vat_class_map": { "21": "PVM1", "0": "PVM5" },
    "partner_group": "PT001",
    "product_group": "PR001",
    "op_tip_purchase": 1,
    "op_tip_sale": 51
} }

Centas:

{ "config": {
    "own_company_code": "304827491",
    "own_vat_code": "LT100001738313",
    "vat_class_map": { "21": "PVM1", "0": "PVM5" },
    "account_purchase": "SANAUDOS",
    "account_sale": "PAJAMOS"
} }

Finvalda:

{ "config": {
    "own_company_code": "304827491",
    "own_vat_code": "LT100001738313",
    "op_type_purchase": "1",
    "op_type_sale": "51",
    "journal_purchase": "PIRK",
    "journal_sale": "PARD",
    "import_param": "IMP1",
    "default_client_code": "KL001",
    "account_purchase": "6001",
    "account_sale": "5001"
} }

Finvalda PVM klasės lauko neturi — klasę parenka imp_param, tad vat_class_map šiam formatui netaikomas.

Naudokite snake_case raktus (nežinomas raktas grąžins 422). Svarbu: 0% / atvirkštinio PVM klasė ("0") pagal nutylėjimą yra PVM5 — patvirtinkite teisingą kodą su buhalteriu (klaidingas, bet galiojantis kodas tyliai iškraipo PVM apskaitą). Nustatykite abu — own_company_code ir own_vat_code: pirkimas/pardavimas atpažįstamas, kai sutampa bet kuris iš jų (AI kartais nenuskaito įmonės kodo, ypač užsienietiškose sąskaitose).

8. Klaidos ir limitai

Klausimai dėl integracijos? Susisiekite — kontaktai.