API Elektronikus Aláírás: REST Fejlesztői Útmutató 2026

Bevezetés

Az elektronikus aláírás REST API integrálása 2026-ban már nélkülözhetetlenné vált a fejlesztési csapatoknak. Az IDC European Digital Transformation Report 2025 szerint az európai vállalatok 73%-a már digitalizált legalább egy szerződéses folyamatot, ami a robusztus technikai integrációk iránti igényt meglökte. Akár LegalTech SaaS-t, ERP-t vagy HR-platformot fejleszt, az elektronikus aláírás API fogyasztásának megértése — OAuth2 authentikáció, webhook-kezelés, eIDAS megfelelőség — közvetlenül meghatározza dokumentumfolyamatai minőségét és jogi érvényességét. Ez a REST fejlesztői útmutató lépésről lépésre végigvezeti Önt: architektúra, authentikáció, dokumentum-életciklus, valós idejű webhookok és biztonsági bevált gyakorlatok.

---

Az Elektronikus Aláírás REST API Architektúrája

RESTful-elvek és endpoint-szerkezet

A jól megtervezett elektronikus aláírás REST API világosan azonosított erőforrásokon és szemantikai HTTP-igékben alapul. Az alapvető erőforrások általában az alábbiak:

• `/documents` — PDF/DOCX dokumentumok feltöltése, kezelése és lekérése
• `/signature-requests` — aláírási kérelmek létrehozása és kezelése
• `/signatories` — aláírók és azok azonosságának kezelése
• `/audit-trails` — tanúsított naplók lekérése
• `/templates` — dokumentumsablonok kezelése

Minden erőforrás szabványos CRUD-végpontokat (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) és normalizált HTTP-válaszkódokat mutat be: `200 OK`, `201 Created`, `400 Bad Request`, `401 Unauthorized`, `422 Unprocessable Entity`, `429 Too Many Requests`.

Egy gyakran elhanyagolt kritikus szempont: a lapozás kezelése. A kifejezett API-k cursor-alapú lapozást használnak az offset/limit helyett, ami stabil teljesítményt garantál még több ezer aláírt dokumentum terén is. Ellenőrizze, hogy a cél-API `X-Next-Cursor` headert vagy `next_page_token` mezőt kínál-e a body-ban.

API verzionálás és visszafelé kompatibilitás

A verzionálás kritikus pont az integrálók számára. Az 2026-ban domináns két megközelítés:

1. URL-alapú verzionálás: `https://api.certyneo.com/v2/signature-requests` — olvasható, CDN-cachelhető, B2B API-khoz ajánlott.
2. Header-alapú verzionálás: `Accept: application/vnd.certyneo.v2+json` — architektúrailag tisztább, de kevésbé látható.

Részesítse előnyben azokat a szolgáltatókat, akik minimum 12 hónapos depreciation-politikát ígérnek és nyilvános changelog-ot publikálnak. Az unannounced kompatibilitás-szakadás az aláírási folyamatban közvetlen jogi következményeket okozhat (aláíratatlan szerződések, hiányzó határidők).

---

OAuth2 Authentikáció és API-Hívások Biztonsága

OAuth2: client_credentials vs authorization_code flow-k

Az authentikáció az elektronikus aláírás API-integráció sarokkövét képezi. A fejlesztőknek legtöbbet használt OAuth2 flow-k:

Client Credentials Flow (M2M — gép-géphez): ``` 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 ``` Ez a flow szerveről-szerverig integrációkhoz ideális, ahol nincs végfelhasználó authentikáció (köteg-feldolgozás, szerződés-automatizálás).

Authorization Code Flow + PKCE: ajánlott, amikor az alkalmazása egy azonosított végfelhasználó nevében járul el. A PKCE (Proof Key for Code Exchange) az RFC 7636 óta kötelező, és védelmet nyújt az elfogás elleni támadások ellen.

Alapvető biztonsági tanácsok:

• Tároljon `client_secret`-eket egy vault-ban (HashiCorp Vault, AWS Secrets Manager) — soha nem sima, nem titkosított környezeti változóban
• Valósítson meg automatikus token-rotációt 60 másodperces bufferrel a lejárat előtt
• Granulális scope-okat használjon: csak a szigorúan szükséges engedélyeket kérje

API-kulcsok kezelése és rate limiting

Könnyebb integrációkhoz vagy tesztkörnyezethez néhány API statikus API-kulcsokat (Bearer Token) kínál. Termelésben használatuk esetén:

• Negyedéves kulcs-rotáció
• IP szerinti korlátozás (allowlist)
• Rendellenes hívások megfigyelése az SIEM-en keresztül

A rate limiting elkerülhetetlen: az aláírás API-k általában 100 és 1000 hívás/perc közé limitálnak. Valósítson meg exponenciális retry mechanizmust jitterrel: ``` retry_delay = base_delay * (2^attempt) + random_jitter ``` Szigorúan kövesse a `429 Too Many Requests`-szel küldött `Retry-After` headert.

---

Aláírási Kérelem Életciklusa API-n Keresztül

Aláírási kérelem létrehozása és konfigurálása

Az aláírási kérelem életciklusa API-n keresztül egy állapot-sémát követ (`draft` → `pending` → `in_progress` → `completed` | `declined` | `expired`). Részletes technikai lépések:

1. lépés — Dokumentum feltöltése: ``` POST /v2/documents Content-Type: multipart/form-data

file=@szerzoodes.pdf ``` Válasz: `{ "document_id": "doc_a1b2c3", "checksum_sha256": "e3b0c442..." }`

2. lépés — Kérelem létrehozása: ```json POST /v2/signature-requests { "document_id": "doc_a1b2c3", "name": "Szolgáltatási szerződés Q3 2026", "signatories": [ { "email": "aláíró@ügyfél.hu", "first_name": "Márta", "last_name": "Kovács", "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. lépés — Aktiválás: `POST /v2/signature-requests/req_x9y8z7/activate`

Az aktiválás után az aláírók meghívókat kapnak, és a kérelem `in_progress` állapotba megy.

Az Aláírt Dokumentum és Audit Trail Lekérése

Miután az `completed` állapot eléréséül (webhook-on keresztül felderíthető — lásd az alábbi szakaszt), kérje le:

``` GET /v2/signature-requests/req_x9y8z7/document/signed → PDF aláírva elektronikus aláírásokkal (PAdES-B-T ETSI EN 319 132 szerint)

GET /v2/signature-requests/req_x9y8z7/audit-trail → Tanúsított audit trail PDF (RFC 3161 időbélyeg) ```

Mindig tároljuk együtt a két fájlt a GED vagy DMS-ben. Az audit trail a bizonyíték bármilyen jogi vitatásban.

---

Webhookok: Valós Idejű Események és Hibakezelés

Webhookok Konfigurálása és Biztosítása

A webhookok az integrációt drága polling-ból reaktív eseménysémába alakítják. Állítsa be webhook-végpontját:

``` POST /v2/webhooks { "url": "https://az-app.com/hooks/certyneo", "events": [ "signature_request.completed", "signature_request.declined", "signatory.signed", "signature_request.expired" ], "secret": "whsec_hmac_titkos_kulcs" } ```

Obligatorikus HMAC biztosítás: validálja minden beérkező payload-t az HMAC-SHA256 aláírás összehasonlításával az `X-Certyneo-Signature` headerrel: ```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) ``` Soha ne használjon sima string-összehasonlítást — sebezhetetlen az időzítés elleni támadásokra.

Idempotencia és Újraküldés Kezelése

A webhookok timeout vagy 5xx hiba esetén újraküldésre kerülhetnek. Valósítson meg kötelező idempotenciát:

1. Húzza ki az egyedi `event_id`-t minden webhook payload-ből
2. Ellenőrizze az adatbázisban, ha az `event_id` már feldolgozva van
3. Azonnal válaszoljon `200 OK`-val (még az ismétlésekre is) az újraküldések megelőzéséhez
4. A munkaáramlat logikáját asszinkronul kezelje (queue: Redis, RabbitMQ, SQS)

Aranyábra: webhook-végpontja 5 másodperc alatt válaszoljon. Minden nehéz feldolgozás (e-mail küldés, GED archívum, ERP értesítés) asszinkron worker-nek delegálva.

Az aláírási szintek mélyebb megismeréséhez tekintse meg az elektronikus aláírás teljes útmutatóját, amely részletezi az egyszerű, fejlett és minősített aláírások közötti különbségeket.

---

Integrációs Bevált Gyakorlatok és Teljesítmény

Sandbox környezetek és tesztelési stratégia

Minden komolyabb elektronikus aláírás API sandbox környezetet kínál a termelésből izolálva. Alkalmazza ezt a tesztstratégiát:

• Unit tesztek: API válaszok mockolása (Wiremock, MSW) az üzleti logika validációjához hálózati függőség nélkül
• Integrációs tesztek: valódi sandbox-elleni tesztelés a teljes életciklus érvényesítéséhez (létrehozás → aláírás → lekérés)
• Terheléstesztek: párhuzamos kérelmek szimulálása a szűk keresztmetszetek azonosításához termelés előtt
• Chaos tesztek: timeout-ok és 5xx hibák szimulálása a retry logika validálásához

Soha ne teszteljen termelésben valódi aláírók identitásaival. A sandbox-ban létrehozott elektronikus aláírások jogi értéke nincs, ami pontosan ami a tesztekhez szükséges.

Monitorozás, Megfigyelhetőség és Riasztás

Termelésben kezelje az integrációt:

• Metrikák: API hívások sikerességi aránya, latencia p95/p99, hiba arány végpontonként
• Elosztott nyomvonalak: propagálja a `trace-id`-t header-ekben az Ön naplóinak korrelálásához az API fournisseur naplóival
• Riasztás: aktiválódjon, ha a hibaarány 1% felett van vagy a latencia p99 3 másodperc felett

Nézze meg az elektronikus aláírás megoldások összehasonlítóját a különféle fournisserek ajánlott SLA (uptime) feltételeinek értékeléséhez — egy gyakran alulbeccsült API-integrációs szempont.

Ha más platformról migrálni szeretne, az útmutató a DocuSign vagy YouSign-ról a Certyneo-ra történő migráláshoz az API-migrálás technikai aspektusait és meglévő webhook kompatibilitásait ismerteti.

Az integrációs beruházás megtérülésének becsléséhez használja az elektronikus aláírás ROI kalkulátor, amely az API-automatizáció produktivitási nyereségeit tartalmazza.

Végül, ha mélyebbre szeretne menni az aláírásra váró dokumentumok automatizált generálásában, fedezze fel az AI kontraktus generátort, amely natívan integrálódik REST API-nkkal.

Az Elektronikus Aláírás API-ét Alkalmazandó Jogi Keret

Az elektronikus aláírás API integrálása nem csak technikai megfontolandó: közvetlenül érinti a szerkesztő és ügyfeleinek jogi felelősségét több alapvető dokumentumban.

Az (EU) 910/2014 eIDAS Rendelet és eIDAS 2.0

Az eIDAS Rendelet (EU) 910/2014 az elektronikus aláírás jogi keretét az Európai Unióban határozza meg. Három szintet különböztet meg:

• Egyszerű elektronikus aláírás (SES): minimális jogi érték, alacsony kockázatú aktusokhoz
• Fejlett elektronikus aláírás (AES): egyértelműen összekapcsolódik az aláíróval, az ő kizárólagos kontrollján belüli adatokból létrehozva — eIDAS 26. cikk
• Minősített elektronikus aláírás (QES): egyenértékű a kézírásos aláírással az EU-ban — eIDAS 25. cikk 2. pont

Az eIDAS 2.0 Rendelet (EU 2024/1183 rendelet) fokozatos alkalmazásával a fejlesztőknek már a Digitális Identitás Európai Tárcájának (EUDIW) integrációját kell tervezniük. Az eIDAS 2.0 útmutató részletes technikai implikációkat tartalmaz.

Francia Polgári Kódex — 1366. és 1367. cikk

Francia jogban az 1366. cikk azt határozza meg, hogy "az elektronikus írás az írott papír szerkezeten alapuló írással azonos bizonyító erővel rendelkezik, feltéve, hogy az eredete egyértelműen azonosítható, és az épülésének és konzervációjának körülményei garantálják az integritást".

Az 1367. cikk konkretizálja a megbízható elektronikus aláírás feltételeit: az aláíró azonosítása és a dokumentum integritásának garantálása. Ezek a követelmények technikai szinten az auditálás tanúsított naplóinak és az aláíráskor használt identitásbizonyítékok kötelező megtartásához vezet — elemek, amelyeket az API-nak feltárnia és Önnek tárolnia kell.

ETSI EN 319 132 Szabványok — PAdES

Az eIDAS-nak megfelelő PDF-aláírások kötelező technikai formátuma a PAdES (PDF Advanced Electronic Signatures), az ETSI EN 319 132 szabvány által meghatározott. Az API-nak minimum PAdES-B-T aláírásokat (időbélyegzéssel), illetve PAdES-B-LT vagy PAdES-B-LTA-kat kell generálnia a hosszú távú érvényesség garantálásához (10+ éves archívum).

GDPR 2016/679 — Az Aláírók Adatai

Az aláírási folyamat során gyűjtött személyes adatok (név, utónév, e-mail, IP-cím, identitásadatok az AES/QES-hez) személyes adatok, amelyek a GDPR alá tartoznak. Az adatkezelőként vagy adatfeldolgozóként vállalt kötelezettségei közé tartoznak:

• Egy indokolt adatmegőrzési időszak meghatározása (általában az elévülési időkhöz igazodik: 5 év közjogban)
• Az automatikus törlés mechanizmusának implementálása API-n keresztül (`DELETE /v2/signature-requests/{id}/personal-data`)
• A feldolgozás dokumentálása az adatfeldolgozási tevékenység nyilvántartásában (GDPR 30. cikk)
• Az adatfeldolgozási megállapodás (DPA) megkötése az aláírás API-fournisseurrel

NIS2 Irányelv és Szolgáltatás Folytonossága

Az olyan szoftver-szerkesztők számára, akiket az NIS2 Irányelv (2022/2555) alapvető vagy fontos entitásként definiál, a harmadik fél API integrálása függőséget teremt, amelyet dokumentálni kell az ellátási lánc digitális kockázatelemzésében. Az aláírás API-fournisseurtől SOC 2 Type II tanúsítványt és 99,9%-os SLA-t igényeljen.

Használati Esetek: Az Elektronikus Aláírás API Gyakorlatban

1. Eset — Szállítói Szerződések Automatizálása az Ipari KKV-ban

Egy ipari KKV évente körülbelül 200 szállítói szerződést kezel, és el akarta kerülni a papír alá-felá mozgatást és a manuális felszólításokat, amelyek havonta 2 napot emésztett fel egy adminisztratív asszisztenst. A fejlesztőcsapat közvetlenül az ERP-be integrálta az elektronikus aláírás REST API-t az alábbi folyamaton keresztül:

1. Egy beszerzési rendelés ERP-en belüli jóváhagyásakor automatikusan egy `POST /v2/signature-requests` hívás kerül kiváltásra
2. A generált PDF szerződés feltöltésre kerül, és aláírási kérelem a szállító regisztrált kontaktjához érkezik
3. Egy `signatory.signed` webhook valós időben frissíti a beszerzési rendelés státuszát
4. Az aláírt dokumentum és audit trail automatikusan archívra kerülnek a GED-ben egy második API-hívás keresztül

Megfigyelt eredmények (KPMG/IDC 2024-2025 szektoros jelentések tartománya): átlagos aláírási idő 8 napról 24 óra alá csökkent, adminisztratív időmegtakarítás 60-70%, nulla dokumentum-veszteség.

2. Eset — LegalTech Platform Ügyvédi Irodáknak

A 5-30 fős ügyvédi irodáknak szánt SaaS szoftver-fejlesztő integráltaa elektronikus aláírás API-t, hogy felhasználói közvetlenül az irodai interfészből aláírathassanak meghatalmazásokat, megállapodásokat és eljárási aktusokat.

A kiválasztott technikai architektúra az OAuth2 Authorization Code + PKCE flow-t használja, hogy minden jogász az ő nevében authentifikálhassa a kérelmeket. A `signature_request.completed` webhook automatikusan az aláírt dokumentumot a ügyfél mappájához kötözi a jogi GED-ben.

A szerkesztő különösen értékelte a fejlett elektronikus aláírások (AES) API-n keresztül való elérhetőségét — a Nemzeti Ügyvédi Tanács javaslatai szerint a megállapodásokhoz szükséges szint. Az integrációs fejlesztési idő körülbelül 3 hét volt egy tapasztalt backend fejlesztőre, 85%-os tesztkoverággal.

3. Eset — Digitális Onboarding Privát Klinikacsoport Számára

Egy kb. 600 ágyas privát klinikacsoport démateriálizálni akarta a tájékoztatott beleegyezési formákat és felvételi szerződéseket, amelyeket addig nyomtatva és kézzel írtak alá a recepción — nyomtatási költségek több ezer euró évente és várakozási idő a befogadásnál.

Az API-integráció összekapcsolta az egészségügyi információs rendszert az elektronikus aláírás platformmal. A beteg regisztrációjakor az EIR API-hívást indít az aláírás kérelem létrehozásához (multipartite: beteg + kezelőorvos) az aláírási mezők automatikus pozicionálásával a sablon metaadataiból.

A GDPR megfelelőséghez szükség volt az API-n keresztüli automatikus törlés implementálására a jogi megőrzési időtartamokkal (20 év a felnőttek esetén a Közegészségügyi Kódex R. 1112-7 cikke szerint). Mért nyereség: felvételi várakozási idő 80%-os csökkenése és nyomtatási/szkenneléséi költségek 40%-os megtakarítása.

Konklúzió

Az elektronikus aláírás REST API integrálása 2026-ban több dimenzió egyidejű megismerését igényli: robusztus RESTful architektúra, biztonságos OAuth2 authentikáció, esemény-alapú webhook-kezelés, valamint eIDAS és GDPR megfelelőség. Azok a fejlesztők, akik ezeket az ügyelete már az integrációs tervezésből anticipate-ik, megkímélhetik magukat a költséges átdolgozásoktól és súlyos jogi kockázatoktól.

Három szín-tanácsi: API-hívások biztosítása (OAuth2 + minimális scope-ok + vault), események asszinkron és idempotens kezelése webhook-on, valamint aláírt dokumentum+ tanúsított audit trail szisztematikus archívuma.

A Certyneo dokumentált, eIDAS-nak megfelelő REST API, ingyenes sandbox-al és dedikált fejlesztői támogatással rendelkezik. Hozzon létre Certyneo-fiókot, hogy hozzáférjen sandbox API-kulcsához és még ma indítsa el az integrációt.