API Elektroninio Parašo: Kūrėjo REST Vadovas 2026

Įvadas

REST elektroninio parašo API integravimas tapo neatsiejamu reikalavimu kūrėjų komandoms 2026 metais. Remiantis IDC European Digital Transformation Report 2025, daugiau nei 73 % Europos įmonių jau digitalizavo bent vieną sutarties procesą, todėl paklaus tvirtiems techninėms integracijoms eksponentiškai auga. Kuriate LegalTech SaaS, ERP ar HR platformą – supratimas, kaip naudoti elektroninio parašo API (OAuth2 autentifikavimas, webhooks valdymas, eIDAS atitiktis) tiesiogiai lemia dokumentų srautų kokybę ir teisinę vertę. Šis REST kūrėjo vadovas žingsnis po žingsnio jus lydės: architektūra, autentifikavimas, dokumento gyvenimo ciklas, real-time webhooks ir saugos geriausios praktikos.

---

REST Elektroninio Parašo API Architektūra

RESTful principai ir endpoint'ų struktūra

Gerai suprojektuota elektroninio parašo REST API remiasi aiškiai identifikuotais ištekliais ir semantiniais HTTP veiksmais. Pagrindiniai ištekliai paprastai yra:

• `/documents` — PDF/DOCX dokument ų įkėlimas, valdymas ir atgavimas
• `/signature-requests` — parašo prašymų kūrimas ir vadovavimas
• `/signatories` — parašiusių asmenų ir jų tapatybės valdymas
• `/audit-trails` — sertifikuotų audito žurnalų atgavimas
• `/templates` — pakartotinai naudojamų dokumento šablonų valdymas

Kiekvienas išteklius suteikia standartinį CRUD endpoint'us (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) ir grąžina JSON atsakymus su normalizuotais HTTP kodais: `200 OK`, `201 Created`, `400 Bad Request`, `401 Unauthorized`, `422 Unprocessable Entity`, `429 Too Many Requests`.

Kritinis aspektas, kuris dažnai nepaisomas: puslapio numeravimo valdymas. Brinės API naudoja cursor-based šabloną, o ne offset/limit, garantuojantis stabilų veikimą net su tūkstančiais pasirašytų dokumentų. Patikrinkite, kad tikslinė API suteikia `X-Next-Cursor` antraštę arba `next_page_token` lauką atsakymo tekste.

API versijų nustatymas ir atgalinė suderinamumas

Versijų nustatymas – svarbi integratoriams problema. Dvi dominuojančios 2026 m. požiūriai yra:

1. URL versijų nustatymas: `https://api.certyneo.com/v2/signature-requests` – skaitomas, CDN talpiklinis, rekomenduojamas B2B API.
2. Header versijų nustatymas: `Accept: application/vnd.certyneo.v2+json` – architektūroje grynesnė, tačiau mažiau matoma.

Teikite pirmenybę teikėjams, kurie įsipareigoja minimum 12 mėnesių nusidėvėjimo politikai ir publikuoja viešą žurnalą. Neplanuotas suderinamumo nutraukimas jūsų parašo sraute gali turėti tiesiogines teisines pasekmes (nepasirašyti kontraktai, praleisti terminai).

---

OAuth2 Autentifikavimas ir API Skambučių Sauga

OAuth2: client_credentials vs authorization_code srautai

Autentifikavimas yra kiekvienos elektroninio parašo API integracijos pamatas. Du pats aktualesni OAuth2 srautai kūrėjams yra:

Client Credentials Flow (M2M — Machine to Machine): ``` POST /oauth/token Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials &client_id=YOUR_CLIENT_ID &client_secret=YOUR_CLIENT_SECRET &scope=documents:write signature_requests:write audit_trails:read ``` Šis srautas idealus serverio-ir-serverio integracijoms, kai nėra galutinio vartotojo autentifikavime (paketinis apdorojimas, sutarčių automatizavimas).

Authorization Code Flow + PKCE: rekomenduojamas, kai jūsų programa veikia galutinio patvirtinto vartotojo vardu. PKCE (Proof Key for Code Exchange) yra privalomas nuo RFC 7636 ir apsaugo nuo pažeidimo atakų.

Esminiai saugos patarimai:

• Saugokite `client_secret` bunkeryje (HashiCorp Vault, AWS Secrets Manager) – niekada nešifriotoje aplinkos kintamajame
• Įgyvendinkite automatinį token rotavimą su 60 sekundžių buffer'iu prieš galiojimą
• Naudokite granuliarūs scopes: reikalaukite tik tiesiogiai reikalingų leidimų

API raktų valdymas ir greičio apribojimai

Lengviems integracijoms ar testų aplinkoms kai kurie API siūlo statinius API raktus (Bearer Token). Jei juos naudojate produkcijoje, taikyti systematiškai:

• Ketvirčio API raktų rotacija
• IP apribojimas (allowlist)
• Nenormalaus skambučių stebėjimas per jūsų SIEM

Greičio apribojimai – neišvengiama realybė: elektroninio parašo API paprastai riboja tarp 100 ir 1000 skambučių/minutę pagal planą. Įgyvendinkite exponential retry mechanizmą su jitter: ``` retry_delay = base_delay * (2^attempt) + random_jitter ``` Griežtai gerbkite `Retry-After` antraštę, grąžintą su `429 Too Many Requests`.

---

Parašo Prašymo Gyvenimo Ciklas per API

Parašo prašymo kūrimas ir konfigūravimas

Parašo prašymo gyvenimo ciklas per REST API seka būsenų schemą (`draft` → `pending` → `in_progress` → `completed` | `declined` | `expired`). Čia yra išsamūs techniniai žingsniai:

1 žingsnis — Dokumento įkėlimas: ``` POST /v2/documents Content-Type: multipart/form-data

file=@sutartis.pdf ``` Atsakymas: `{ "document_id": "doc_a1b2c3", "checksum_sha256": "e3b0c442..." }`

2 žingsnis — Prašymo kūrimas: ```json POST /v2/signature-requests { "document_id": "doc_a1b2c3", "name": "Paslaugų sutartis Q3 2026", "signatories": [ { "email": "signataris@klients.lt", "first_name": "Marija", "last_name": "Dupont", "signature_level": "advanced", "fields": [{ "type": "signature", "page": 3, "x": 120, "y": 680 }] } ], "expiry_date": "2026-06-05T23:59:59Z", "reminder_settings": { "enabled": true, "frequency_days": 3 } } ```

3 žingsnis — Aktyvinimas: `POST /v2/signature-requests/req_x9y8z7/activate`

Nuo aktyvinimo parašiusieji asmenys gauna kvietimus ir prašymas pereina į `in_progress` būseną.

Pasirašyto dokumento ir audito žurnalo atgavimas

Kai pasiekta `completed` būsena (aptinkama per webhook – žr. tolesnę sekciją), atgaukite:

``` GET /v2/signature-requests/req_x9y8z7/document/signed → PDF su integruotais elektroniniais parašais (PAdES-B-T pagal ETSI EN 319 132)

GET /v2/signature-requests/req_x9y8z7/audit-trail → Audito žurnalo PDF su sertifikuotu laiku (RFC 3161 qualified) ```

Visada saugokite abu failus kartu jūsų DMS ar dokumento vadybos sistemoje. Audito žurnalas yra įrodymas priešintis bet kokiam ginčui.

---

Webhooks: Real-time Įvykiai ir Klaidų Valdymas

Webhooks konfigūravimas ir apsauga

Webhooks transformuoja jūsų integraciją iš brangaus polling į reaktyvią įvykių architektūrą. Konfigūruokite webhook endpoint:

``` POST /v2/webhooks { "url": "https://jūsu-programa.com/hooks/certyneo", "events": [ "signature_request.completed", "signature_request.declined", "signatory.signed", "signature_request.expired" ], "secret": "whsec_jūsų_hmac_slaptis" } ```

Privalomoji HMAC sauga: patvirtinkite kiekvieną gaunantį payload'ą lyginant HMAC-SHA256 su `X-Certyneo-Signature` antrašte: ```python import hmac, hashlib

def verify_webhook(payload: bytes, secret: str, signature_header: str) -> bool: expected = hmac.new( secret.encode(), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature_header) ``` Niekada nenaudokite paprasto šios lyginimo – pažeidžiamas timing atakoms.

Idempotencija ir persiunčiamų webhook'ų valdymas

Webhook'ai gali būti iš naujo išsiųsti dėl timeout'o ar jūsų endpoint'o 5xx klaidos. Įgyvendinkite idempotencija privalomoje:

1. Iš kiekvieno webhook payload'o ištrauk unikalų `event_id`
2. Duomenų bazėje patikrinkite, ar šis `event_id` jau buvo apdorotas
3. Grąžinkite `200 OK` iš karto (net dubliniams) kad išvengtumėte begalinių persiunčiamų
4. Traktuokite verslo logiką asinchroniškai (queue: Redis, RabbitMQ, SQS)

Auksinė taisyklė: jūsų webhook endpoint turi atsakyti per mažiau nei 5 sekundes. Visas sunkus verslo apdorojimas (el. laiško siuntimas, DMS archyvavimas, ERP pranešimas) turi būti perduotas asinchroniniam darbininkui.

Norėdami geriau suprasti galimus pasirašymo lygius per API, žr. mūsų Pilną elektroninio parašo vadovą, kuris detaliai paaiškina skirtumus tarp paprastų, išplėstinių ir kvalifikuotų parašų.

---

Integracijos Geros Praktikos ir Veikimas

Sandbox aplinkos ir testų strategija

Kiekviena rimta elektroninio parašo API siūlo izoliuotą sandbox aplinką nuo produkcijos. Priimkite šią testų strategiją:

• Vienetiniai testai: mokyti API atsakymai (Wiremock, MSW) patvirtinti jūsų verslo logiką be tinklo priklausomybės
• Integracijos testai: vykdyti sandbox realybėje pilnam gyvenimo ciklui patvirtinti (kūrimas → parašas → atgavimas)
• Apkrovos testai: simuliuoti vienalaikus prašymus pikams nustatyti ankščiau nei produkcija
• Chaos testai: simuliuoti timeout'us ir 5xx klaidas patvirtinti retry logiką

Niekada netesuokite produkcijoje su tikrai parašiusių asmenų identitetais. Sandbox parašai neturi teisinio vertės – tai lygiai tai, ko jums reikia testams.

Stebėjimas, stebėjimas ir perspėjimai

Produkcijoje instrumentuokite jūsų integraciją su:

• Metrika: API skambučių sėkmės procentas, p95/p99 latenija, klaidų dažnis per endpoint
• Paskirstytos sekos: platinkite `trace-id` jūsų antraštėse jūsų žurnalams su API fornieriaus žurnalais
• Perspėjimai: suaktyvinkite perspėjimą jei klaidų dažnis viršija 1 % arba p99 latenija viršija 3 sekundes

Žr. mūsų elektroninio parašo sprendimų palyginimą, kad įvertintumėte skirtingų teikėjų siūlomus SLA pagal pasieklamumą – dažnai neįvertintas API integracijos kriterijus.

Jei migruojate iš kitos platformos, mūsų DocuSign ar YouSign migracijos į Certyneo vadovas apima API migracijos techninius aspektus ir esamo webhook'o suderinamumą.

ROI savo integracijai įvertinti, naudokite mūsų elektroninio parašo ROI skaičiuoklę, kuri apima produktyvumo pelną iš API automatizavimo.

Galiausiai, norint automatizuoti dokumentų generavimą pasirašymui, atraskite mūsų AI sutarčių generatorių, kuris iš karto sąveikauja su mūsų REST API.

Taikytinas Teisinis Rėmimas Elektroninio Parašo API

Elektroninio parašo API integravimas – ne tik techninis iššūkis: tai tiesiogiai įsipareigoja redaktoriaus ir jo klientų teisinę atsakomybę keliems pagrindiniais tekstams.

Reglamentas eIDAS nr. 910/2014 ir eIDAS 2.0

Reglamentas (ES) Nr. 910/2014 (eIDAS) nustato elektroninio parašo teisinį rėmimą Europos Sąjungoje. Jis nurodo tris lygius:

• Paprastas elektroninis parašas (PEP): minimali teisinio vertė, tinkamas žemos rizikos aktams
• Išplėstinis elektroninis parašas (IEP): unikaliai susietas su parašiusiaisiais, sukurtas iš parašiusiųjų išskirtinės kontrolės duomenimis – eIDAS 26 straipsnis
• Kvalifikuotas elektroninis parašas (KP): lygus rankraštinio parašo – visos ES – eIDAS 25 straipsnis, 2 dalis

Su eIDAS 2.0 (Reglamentas ES 2024/1183) įsigalijimu, kūrėjai turi iš anksto integruoti Europos Skaitmeninės Tapatybės Piniginės (ESTP) į autentifikavimo srautus. Žr. mūsų eIDAS 2.0 vadovą dėl išsamių techninių nuodų.

Prancūzijos Civilinis Kodeksas – 1366 ir 1367 straipsniai

Prancūzų teisėje Civilinio Kodekso 1366 straipsnis nurodo, jog „elektroninis raštas turi tą pačią įrodymų galią kaip popierinė forma, jei gali būti tinkamai identifikuota asmuo, kurio jis kilo, ir jei jis buvo sudarytas ir saugomas tokiomis sąlygomis, kurios garantuoja jo vientisumą".

1367 straipsnis nurodo patikimos elektroninio parašo sąlygas: parašiusiųjų identifikavimas ir dokumento vietumo garantija. Šie reikalavimai techniškai verčiami sertifikuotų audito žurnalų ir tapatybės įrodymų saugojimo pareiga – elementai, kuriuos jūsų API turi suteikti ir kuriuos turite saugoti.

ETSI EN 319 132 Standartai – PAdES

Techninis žurnalas, priimtinas eIDAS parašams PDF, yra PAdES (PDF Advanced Electronic Signatures), apibrėžtas ETSI EN 319 132. Jūsų API turi gaminti PAdES-B-T parašus (su laiku) minimumui, ir PAdES-B-LT arba PAdES-B-LTA ilgalaikei patikrinimui (archyvavimas 10+ metų).

GDPR nr. 2016/679 – Parašiusių Duomenys

Asmeniniai duomenys, surinkti parašo proceso (vardas, pavardė, el. paštas, IP adresas, tapatybės duomenys IEP/KP), yra asmeninės duomenys, kuriems taikoma GDPR. Jūsų pareigos kaip duomenų valdytojo ar tvarkytojo apima:

• Nustatyti saugojimo laiką, pagrįstą tiesioginėmis reikalavimais (paprastai: 5 metai pagal imperatyvą)
• Numatyti automatinio grynimo mechanizmą per API (`DELETE /v2/signature-requests/{id}/personal-data`)
• Dokumentuoti tvarkymą jūsų tvarkyme žurnale (GDPR 30 str.)
• Sudaryti DPA (Data Processing Agreement) su jūsų elektroninio parašo API teikėju

NIS2 Direktyva ir Paslaugų Tęstinumas

Programos leidėjams, klasifikuotiems kaip esminiai ar svarbūs pagal NIS2 direktyvą (2022/2555), trečiosios šalies API integravimas sukuria priklausomybę, kuri turi būti dokumentuota skaitmeninės tiekimo grandinės rizikos analizėje. Reikalaukite iš jūsų API teikėjo SOC 2 Type II sertifikatą ir ≥ 99,9 % pasieklamumo SLA.

Naudojimo Scenarijai: Elektroninio Parašo API Praktikoje

Scenarijus 1 – Tiekėjo Sutarčių Automatizavimas Mažoje Pramonės Įmonėje

Maža pramonės įmonė, valdanti apie 200 tiekėjo sutarčių per metus, norėjo pašalinti popierinių ir rankinių persiunčiamų, kurie reguliariai suvartojos 2 dienas per mėnesį administratoriaus laiko. Kūrėjo komanda integruoto elektroninio parašo API REST tiesiai į jų verslo ERP per šį srautą:

1. Patvirtinus pirkimo užsakymą ERP, automatiškai suaktyvinamas `POST /v2/signature-requests` skambutis
2. Sugeneruotas sutarties PDF yra įkeltas ir parašo prašymas siunčiamas nurodytam tiekėjo kontaktui
3. Webhook `signatory.signed` atnaujina pirkimo užsakymo būseną real-time
4. Pasirašytas dokumentas ir audito žurnalas automatiškai archyvuojami DMS per antrą API skambutį

Stebėti rezultatai (KPMG/IDC 2024-2025 sektoriaus ataskaitų diapazonas): vidutinio parašo laiko sumažėjimas nuo 8 dienų iki mažiau nei 24 valandų, administracinių persiunčiamų laiko ekonomija iki 60-70 %, ir nulis dokumento nuostolių.

Scenarijus 2 – LegalTech Platforma Teisininkų Kanceliarijoms

Programos leidėjas, kurianti SaaS sprendimą 5–30 teisininkų kanceliarijoms, integruojo elektroninio parašo API, kad jos naudotojai galėtų pasirašyti pavedimus, honorarų sutartis ir procedūros aktus tiesiai iš kanceliarijos sąsajos.

Pasirinkta architektūra naudoja OAuth2 Authorization Code + PKCE srautą, kad kiekvienas teisininkas autentifikuotų prašymus savo vardu. Webhook'ai `signature_request.completed` automatiškai dedina pasirašytą dokumentą į kliento aplanką teisės DMS.

Leidėjas ypač vertino išplėstinių elektroninių parašų (IEP) per API pasiekiamumą – lygis, reikalavimas honorarų sutartims pagal Nacionalinio Advokatur Tarybos rekomendacijas. Pradinės integracijos kūrimo laikas buvo apie 3 savaitės vienam vyresniajam backend kūrėjui, su 85 % testų aprėpimu.

Scenarijus 3 – Skaitmeninė Registracija Privačių Klinikų Grupėje

Privačių klinikų grupė, turinti apie 600 lovų, norėjo dematalizuoti informuoto sutikimo formas ir priėmimo sutartis, kurios buvo spausdintos ir rankiniu būdu pasirašytos priėmimo metu – sukelianti kelių tūkstančių eurų spausdinimo išlaidas per metus ir priėmimo laukimo laikus.

API integravimas sujungė ligoninės informacijos sistemą (LIS) su elektroninio parašo platforma. Paciento registracijoje LIS iškviečia API sukurti daugiapusę parašo prašymą (pacientas + gydytojas) su automatiškai apskaičiuotas parašo laukų padėtimi iš šablono metaduomenų.

GDPR atitiktis reikalavo automatinio grynimo programavimo per API (`PATCH /v2/signature-requests` + grynimo patvirtinimo webhook) suderinta su medicininių failų saugojimo periodais (20 metų suaugusiems, pagal Sveikatos kodekso R. 1112-7 straipsnį). Išmatuoti pelnas pasiekė 80 % priėmimo laukimo laiko sumažėjimą ir 40 % spausdinimo ir skenavimo išlaidos santaupą.

Išvada

Elektroninio parašo REST API integravimas 2026 m. reikalauja vienu metu keturių dimensijų įvaldymo: tvirta RESTful architektūra, saugi OAuth2 autentifikacija, įvykių valdymas webhook'ais ir eIDAS bei GDPR atitiktis. Kūrėjai, kurie iš anksto numano šiuos iššūkius iš pat integracijos pradžios, išvengia brangių perrašymų ir didelės teisinės rizikos.

Trys pagrindiniai stulpai: apsaugokite savo API skambučius (OAuth2 + minimalūs scope + bunkery), asinchroniškai ir idempotenciškai traktuokite įvykius webhook'ais, ir sistematiškai archyvuokite pasirašytą dokumentą su jo sertifikuotu audito žurnalu.

Certyneo suteikia dokumentuotą REST API, atitinkančią eIDAS, su nemokamu sandbox ir dedikuota kūrėjo techninę pagalbą. Sukurkite Certyneo paskyrą, jei norite prieiti prie jūsų sandbox API rakto ir pradėti integraciją šiandien.