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, Centas XML arba Finvalda 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: PDF arba JPG / PNG / HEIC nuotrauka; failas iki 10 MB; iki 20 puslapių (/extract-direct riba atskira, bet numatytai lygi /upload ribai — abi po 20; administratorius konkrečiam klientui gali pakelti /upload ribą iki 50, o /extract-direct riba nuo to nekinta; paskyroms, kurioms Robodam įjungė kuro kortelių ataskaitų skaitymą, ataskaitai, kurios atspausdintos sumos susitikrina iki cento, puslapių riba netaikoma — iki 200 puslapių; visoms kitoms paskyroms riba nesikeičia); 30 užklausų/min. Kelių sąskaitų PDF čia traktuojamas kaip vienas dokumentas (skaidymas vyksta tik per /upload).

Visa užklausa (multipart kūnas) — iki 20 MB: didesnę atmeta šliuzas dar prieš API (413 be JSON kūno). Vienas failas — iki 10 MB, jei administratorius jūsų paskyrai nenustatė kitaip (daugiausia 18 MB). /batch-upload riba galioja visų failų sumai.

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,
  "invoice_id": "3f2b9c1e-...",   // išsaugotos sąskaitos ID Scan sistemoje; null kai save_to_profile=false
  "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.

Pakartojimas su jūsų dokumento ID

Siųskite savo dokumento ID antraštėje Idempotency-Key arba formos lauke external_id (1–128 simbolių) — /upload, /extract-direct ir /batch-upload keliuose. Jis išsaugomas kaip sąskaitos external_id, grąžinamas atsakyme ir filtruojamas (GET /invoices?external_id=…). Pakartojus užklausą su tuo pačiu ID grąžinamas PIRMASIS rezultatas — net jei failas nuskenuotas iš naujo ir jo baitai kitokie — antra sąskaita nesukuriama ir neapmokestinama.

curl -X POST "{BASE}/api/v1/invoices/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: DMS-2026-000123" \
  -F "file=@saskaita.pdf"

Į /batch-upload siųskite po vieną external_id lauką kiekvienam failui, ta pačia tvarka; viena Idempotency-Key antraštė keliems failams atmetama (422).

Dėmesio: su save_to_profile=false rezultatas neišsaugomas, tad pakartota užklausa yra naujas nuskaitymas ir naujas mokestis (ID su šiuo parametru atmetamas). Automatizacijoms, kurios kartoja po klaidos ar laiko limito, naudokite numatytąjį save_to_profile=true ir savo ID.

6. Apskaitos eksportas (Rivilė / Centas / Finvalda)

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, centas arba finvalda. 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

9. Masinis kelias: įkelti → apklausti → paimti → eksportuoti

Kai dokumentų daug arba jie ilgi, naudokite asinchroninį kelią: įkeliate dabar, o rezultatus pasiimate, kai jie paruošti.

1. Įkelti — POST /invoices/upload (vienas failas) arba /batch-upload (iki 100 failų). /batch-upload visada atsako 201 su rezultatu kiekvienam failui, net kai visi failai atmesti — tikrinkite kiekvieno results[].status.
2. Apklausti — GET /invoices su sort_by=updated_at&sort_order=asc&page_size=100. Kol atsakymo next_cursor nėra null, siųskite jį atgal kaip cursor.
3. Paimti — GET /invoices/{id} grąžina visus nuskaitytus laukus (sąraše jie sutrumpinti).
4. Eksportuoti — POST /invoices/export/{format} su invoice_ids (§6).

GET {BASE}/api/v1/invoices?sort_by=updated_at&sort_order=asc&page_size=100&updated_after=2026-09-27T08:00:00Z
→ { "items": [ … ], "total": 240, "next_cursor": "eyJ1Ijoi…" }
GET {BASE}/api/v1/invoices?sort_by=updated_at&sort_order=asc&page_size=100&updated_after=2026-09-27T08:00:00Z&cursor=eyJ1Ijoi…
→ { "items": [ … ], "next_cursor": null }

Receptas: saugus inkrementinis sinchronizavimas

Išsisaugokite paskutinės gautos eilutės updated_at. Kitą sinchronizavimą pradėkite su updated_after = ta reikšmė minus 2 minutės ir eikite per next_cursor. Persidengimas būtinas: vėliau įsipareigojęs įrašas gali turėti ankstesnę žymą. Tą pačią sąskaitą galite gauti dukart — atpažinkite ją pagal id. Puslapiai pagal page keičiantis duomenims gali praleisti eilutę — sinchronizavimui jų nenaudokite.

Būsenų gyvavimo ciklas (status)

uploaded → processing → galutinė būsena. Daugiapuslapis PDF pirma pereina detection_pending; jei jame kelios sąskaitos, tėvinė eilutė tampa split, o kiekviena sąskaita apdorojama kaip atskira eilutė.

Laukai sąraše ir detalėse

Sąraše extracted_data sutrumpintas iki penkių laukų — vendor.name, total_amount, subtotal, tax_amount, currency — tais pačiais vardais kaip detalėse (§3). Eilutės, pirkėjas, datos ir numeris yra tik GET /invoices/{id}. Abiejuose yra updated_at ir external_id. Laukų vardai nekeičiami — nauji tik pridedami.

10. Kontraktas: OpenAPI, versija ir klaidų kodai

Mašinai skaitomas kontraktas — openapi-public.json (OpenAPI 3.1, be administravimo maršrutų). Kiekvienas atsakymas turi antraštę X-Contract-Version (data): toje pačioje versijoje pakeitimai tik pridedami, o pašalinimas ar prasmės pakeitimas reiškia naują datą. Nežinomus laukus ir kodus ignoruokite.

Kiekvienas atsakymas turi X-Request-ID, o kiekvienos klaidos kūnas — ir request_id: nurodykite jį, kai rašote mums. Klaidos kodas yra detail.error (pagal jį šakokite), žmogui skirtas tekstas — detail.message.

HTTP/1.1 403 Forbidden
X-Request-ID: 5f0c…
X-Contract-Version: 2026-09-30

{ "detail": { "error": "trial_exhausted", "message": "…", "retryable": false },
  "request_id": "5f0c…" }

Dažnio limitai skaičiuojami jūsų API raktui (arba prisijungusiam vartotojui), ne IP adresui — tik prisijungimo ir registracijos keliai ribojami pagal IP. Ribojami atsakymai turi X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset; atsakymas 429 — ir Retry-After (sekundės).

Klaidų kodai

Nežinomą kodą traktuokite kaip „nekartoti“ dabar — bandykite vėlesniu paleidimu, bet galutiniu jo nelaikykite. Jei lauko retryable atsakyme nėra, tai nėra false. Atsiskaitymo klaidos (payment_blocked, trial_exhausted, insufficient_credits) visada yra 403 su retryable: false: sustabdykite visą paleidimą ir praneškite žmogui, o ne praleiskite failą.

Klausimai dėl integracijos? Susisiekite — kontaktai.