API Sinatuaren Elektronikoa: Garapenarien Gida REST 2026

Sarrera

API REST sinatuaren elektronikoa integratzea beharrezkoa bilakatu da 2025ean garapen-taldeentzat. Europako enpreseen %73 baino gehiagok gutxienez kontratazio-prozesu bat digitalizatu dute (iturria: IDC European Digital Transformation Report 2025), eta integrazio teknikoen eskaera gero eta handitu da. LegalTech SaaS bat, ERP bat edo RH plataforma bat eraikitzen ari bazara, API sinatuaren elektronikoa nola erabili ikasteak —OAuth2 autentifikazioa, webhooks kudeaketa, eIDAS bateragarritasuna— erabakitzen du zuzen zuzenean zure dokumentazio-fluxuen kalitatea eta legaleko balioa. Gida honen bidez urratsez urratsean eramaten zaitugu: arkitektura, autentifikazioa, dokumentuaren bizi-zikloa, denbora errealen webhooks eta segurtasunaren onbide praktikaak.

---

Sinatuaren Elektronikoa API REST Arkitektura

RESTful printzipioak eta enpoint-en estruktura

Sinatuaren elektronikoa API REST ondo diseinatua baliabideak argi identifikatuetan eta HTTP aditz semantikoak oinarritzen da. Funtsezko baliabideak hauek dira normalean:

• `/documents` — igoera, kudeaketa eta PDF/DOCX dokumentuen berreskuraketa
• `/signature-requests` — sinatuaren eskaeren sorrera eta zuzendaritza
• `/signatories` — sinatariak eta haien identitatearen kudeaketa
• `/audit-trails` — sertifikatutako auditak lortzea
• `/templates` — berrerabiltzen diren dokumentu ereduen kudeaketa

Baliabide bakoitzak CRUD enpoint estandarrak ( `GET`, `POST`, `PUT`, `PATCH`, `DELETE`) argitzen du eta JSON erantzunak itzultzen ditu HTTP kodeekin normalizatuak: `200 OK`, `201 Created`, `400 Bad Request`, `401 Unauthorized`, `422 Unprocessable Entity`, `429 Too Many Requests`.

Alderdi kritikorik ez ohikoa: paginazioaren kudeaketa. API maduragoak cursor-based eredua erabiltzen dute offset/limitaren ordez, balio mota hobeak bermatzen ditu sinaturaren dokumentu-bolumenen gainean. Egiaztatu API helburua `X-Next-Cursor` header bat edo `next_page_token` eremu bat itzultzen duela.

API bertsioak eta atzerantz bateragarritasuna

Bertsio-kudeaketa ardatz arriskua dira integratzaileentzat. 2026an agertzen diren bi ikuspuntu nagusiak hauek dira:

1. Bertsio-kudeaketa URLan: `https://api.certyneo.com/v2/signature-requests` — irakurgarria, CDN bidez cacheable, B2B APIentzat gomendatua.
2. Bertsio-kudeaketa headerean: `Accept: application/vnd.certyneo.v2+json` — arkitekturoki garbiagoa baina ez horrenbeste ikusgaia.

Lehenetsi hornitzaileak gutxienez 12 hilabete desagertzeko politika adierazten dutenak eta publikoen changelog bat argitzen dutenak. Sinu-fluxuan ez-bateragarritasun zuzenera bidez bihurtutzeak legaleko ondorioak ditzake (kontratatu sinatu gabe, epeak galtzea).

---

OAuth2 Autentifikazioa eta API Deien Segurtasuna

OAuth2: client_credentials vs authorization_code fluxuak

Autentifikazioa edozein API sinatuaren elektronikoko integrazio hartako harriza da. Garapenarientzat adierazgarrienak den OAuth2 fluxu biak hauek dira:

Client Credentials Flow (M2M — Makina-Makinaren komunikazioa): ``` 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 ``` Fluxu hau ideal da zerbitzari-zerbitzari integrazioetarako non benetako erabiltzailerik ez dago autentifikazioan parte hartzen (batch prozesamendua, kontratuaren automatioa).

Authorization Code Flow + PKCE: gomendatua zure aplikazioak identifikatutako benetako erabiltzaile baten izenan jarduten duenean. PKCE (Proof Key for Code Exchange) derrigorrezkoa da RFC 7636tik eta oztopotzaile-intersepzio erasoetan babestuta.

Segurtasun aholkuak funtsezkoak:

• Gordetzen dituzu `client_secret` vault batean (HashiCorp Vault, AWS Secrets Manager) — inoiz ere ez zifratutako ingurune-aldagaietan
• Inplementatu token automatikoko errotazioa 60 segunduko bufferarekin iraungitzearen aurretik
• Erabili scope granularrak: eskatzen dituzu bakarrik beharrezkoak diren baimanak

API gakoaren kudeaketa eta rate limiting

Integrazio arina edo saiakuntza-inguruneetarako, API batzuek estatiko API-gakoak (Bearer Token) proposatzen dituzte. Ekoizpenean erabiltzen badituzu, beti aplikatu:

• Hilerokako gakoaren errotazioa
• IP baieztapena (allowlist)
• Eskaera-desberdintasunen monitorizazioa zure SEIMaren bidez

Rate limiting egitate esmena da: sinatuaren API-k normalean 100 eta 1000 eskaera/minutuaren artean mugatzen dute plano negoziatu araberan. Inplementatu retry esponentzial mekanismo jitter batekin: ``` retry_delay = base_delay * (2^attempt) + random_jitter ``` Errespetatu eskrupulosoki `Retry-After` headera `429 Too Many Requests` bihurtzean itzularaziko du.

---

Sinatuaren Eskaeraren Bizi-Zikloa API RESTaren bidez

Sinatuaren Eskaeraren Sorrera eta Konfigurazioa

Sinatuaren eskaeraren bizi-zikloak API REST bidez egoeren eredua jarraitzen du ( `draft` → `pending` → `in_progress` → `completed` | `declined` | `expired`). Hona hemen urratsez urrats teknikoak:

Urratsak 1 — Dokumentuaren igoera: ``` POST /v2/documents Content-Type: multipart/form-data

[email protected] ``` Erantzuna: `{ "document_id": "doc_a1b2c3", "checksum_sha256": "e3b0c442..." }`

Urratsak 2 — Eskaeraren sorrera: ```json POST /v2/signature-requests { "document_id": "doc_a1b2c3", "name": "Prestazioen kontratuaren 2026ko 3. orokorra", "signatories": [ { "email": "[email protected]", "first_name": "Marie", "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 } } ```

Urratsak 3 — Aktibatzea: `POST /v2/signature-requests/req_x9y8z7/activate`

Aktibatutik, sinatariak haien gonbidaak jasotzen dituzte eta eskaera `in_progress` egoera batera doa.

Sinatutako Dokumentuaren eta Auditaren Berreskuratzea

`completed` egoera atzean dagoenean (webhookaren bidez detektagarria — hurrengo atalean ikusi), berreskuratu:

``` GET /v2/signature-requests/req_x9y8z7/document/signed → Sinatutako PDF sinatuaren elektronikoak txertatuta (PAdES-B-T ETSI EN 319 132 arabera)

GET /v2/signature-requests/req_x9y8z7/audit-trail → Sertifikatutako auditaren PDF (horodatazio kalifikatuak RFC 3161) ```

Gorde beti bi fitxategiak elkarrekin zure GED edo DMS-ean. Audit-pista judizialean kontsulta egiten da bategietan.

---

Webhooks: Denbora-Errealen Gertaerak eta Erroreen Kudeaketa

Webhookak Konfiguratzea eta Segurtzea

Webhooks zure integrazioa pollingeko kostu handikoa dena abantzada erreaktibo EventServicean bihurtzen du. Konfiguratu zure webhook enpoint-a:

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

HMAC segurtasuna nahitaez: balioztatu sarrera egiten duten payload guztiak HMAC-SHA256 kalkulatuta eta `X-Certyneo-Signature` headerarekin konparatzita: ```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) ``` Inoiz ere ez erabili karaktere-kate konparazio klasikoa — betzea timing erasoetan.

Idempotentzia eta Retrasnmisioen Kudeaketa

Webhooks berregin daitezke timeout-en edo zure enpoint-aren 5xx errore-en kasuan. Inplementatu idempotentzia derrigorrezkoa:

1. Extrahitu `event_id` bakarra payload webhook bakoitzean
2. Egiaztatu eta kudeaketa gabe dagoen `event_id` hau
3. Bueltatu `200 OK` berehala (beharrezkoak ez diren berregin eragotzeak)
4. Tratatu negozio logika asinkronoki (queue: Redis, RabbitMQ, SQS)

Arau gorena: zure webhook enpoint-ak 5 segundo baino lehen erantzun behar du. Edozein negozio-prozesamendu astuna (e-posta bidalketak, GED-en archiboa, ERP-eko notifikazioak) lan-txartelean delegatu behar da asinkronoki.

Zure ulertzea sakontzeko sinatuaren mailen bidez API eskuragarriak, kontsultatu gure sinatuaren elektronikaren gida osoa eta sinadura sinpleak, aurreratuenak eta kalifikatuak bereizten ditu.

---

Integrazio Pratika Onbegingarriak eta Performantzia

Sandbox Inguruneak eta Prubaren Estrategia

Edozein sinatuaren elektronikako API serio-mailakoakhan sandbox ingurune isolatuak proposatzen dituzte ekoizpenetik. Hartu estrategia hau prubaketa:

• Unitate-prubak: API erantzunak simulatu (Wiremock, MSW) zure negozio logika balioztatzeko sarearen mendekotasunarik gabe
• Integrazio-prubak: egiazkoa sandbox-a gauzatzea bizi-zikloa osoa balioztatzeko (sorrera → sinadura → berreskuratzea)
• Kargatzea prubak: simulatu aldibereko eskaeren piko mailaak gauntlet identifikatzeko zure enplazimendu hobegarriei aurretik ekoizpena
• Kaosa prubak: simulatu timeout-ak eta 5xx erroreak zure retry logika balioztatzeko

Inoiz ere ez proba ekoizpena identitate zintzo sinatariarekin. Sandbox-en sortuako sinatuaren elektronikoak legaleko balorazioa izango dute, hori zehazki nahi duzun dena zure prubak.

Monitorizazioa, Ikusgarritasuna eta Alerting

Ekoizpenean, instrumentu zure integrazioa:

• Metrikak: API deiden arrakasta-tasak, latentzia p95/p99, enpoint bakoitzean errore-tasa
• Banaketak zabalduta: `trace-id` argalduta zure headeretan zure logekin API fournisseur-aren logekin korrelatzeko
• Alerting: piztu alerta errore-tasak %1 gainditzen badute edo latentzia p99 3 segundu gainditzen badute

Kontsultatu gure sinatuaren elektronikako soluzioen konparatiboa SLA disponibilitate (uptime) ebaluatzeko fournisseur desberdinek proposatzen duten — aztergaia askoren azpiestimatua API integrazioan.

Beste plataforma batetik migratzea bazabiltza, gure DocuSign edo YouSign-tik Certyneo-ra migratzea nola egin gida API migrazioan aspektua teknikoak eta existitzen diren webhookak konpatibilitate.

Zure integrazio-ROI estimatzeko, erabili gure sinatuaren elektronikako ROI kalkulua automatizazioaren produktibitate irabaziak integratzen dituena API bidez.

Azkenik, dokumentuaren sorrera automatikoago zoazten sinadura, aurkeztu gure IA bidezko kontratuen sortzailea beren API REST bidez natiboa interfazea.

Aplikagarria API Sinatuaren Elektronikoan Esparru Legala

API sinatuaren elektronikoa integrazioa aspektu teknikoa ez da soilik: zuzenean atera ditzake ardura legala editorea eta beren bezeroa hainbat testuz.

Erregelamendua eIDAS n°910/2014 eta eIDAS 2.0

Erregelamendua (UE) n°910/2014 (eIDAS) ezartzen du sinatuaren elektronikaren esparru legala Europako Batasunean. Maila hiruetan bereizten da:

• Sinadura elektroniko sinplea (SES): legaleko balioa minimoa, arrisku baxuko aktuetan egokia
• Sinadura elektroniko aurreratua (AES): artikulu 26 eIDAS araberan, sinataria argi eta identifikatu egiten dituena, sortuak zein bere baimen esklusiboa
• Sinadura elektroniko kalifikatuak (QES): berdinak eskriz sinadura UE osoan — artikulu 25 §2 eIDAS

Sarrera enplegu progresiboarekin eIDAS 2.0 erregelamendua (Erregelamendua UE 2024/1183), garapenariek aurreau artzen dute integrazio Europako Portefeuilaren Identitate Digitala (EUDIW) beren autentifikazio-fluxuetan. Kontsultatu gure eIDAS 2.0 gida araueran hari lekuko teknikoek.

Frantses Zibil Kodea — Artikulu 1366 eta 1367

Frantses zibil arauetan, artikulu 1366ak ezartzen du « idatzia elektronikoa baliokidea da papelean idatzia, baldintzetan identifikatu ahal daitekeenaren pertsona norekin emana eta kudeaketa beste baldintzetan integritatea bermatzeko ».

Artikulu 1367k zehaztzen du fidagarri sinatuaren elektronikaren baldintzak: sinatariaren identifikazioa eta dokumentuaren integritatea bermea. Exigentzia haiek teknikoki itzultzen dira sertifikatutako audit-pistu kontserbatzea eta identitate frogak sinadura-prozesuan erabilitakoak - elementuak API zure argitzea eta stocku egin beharko dituzu.

Arauak ETSI EN 319 132 — PAdES

Teknika formatu derrigorrezkoa sinatuaren PDF-etan eIDAS bateragarriak PAdES (PDF Advanced Electronic Signatures), ETSI EN 319 132 arauan. API-ak sortu behar dituzte PAdES-B-T (horodatazioa) gutxienez, eta PAdES-B-LT edo PAdES-B-LTA balio etengabean bermatzeko (archibo 10+ urte).

RGPD n°2016/679 — Sinatariek Datua

Pertsonen datua sinatuaren prozesuean (izena, bikoitena, eposta, IP helbidea, identitate datua AES/QES-etan) pertsona datu-gaiei osoa RGPD-a ezarritakoak. Zure obligazioak ardura-emaila hondara edo hondara bilaketa osatzeko:

• Ezarri dataren kontserbazio-denbora justifikatua (normalean epeen bizia: 5 urteak zibil arauetan)
• Aurreikusi purga automatikoaren mekanismo APIaren bidez ( `DELETE /v2/signature-requests/{id}/personal-data`)
• Kudeaketa dokumentatu zure sailaren jardueran erregistroaren ( artikulu 30 RGPD)
• Egin DPA (Data Processing Agreement) zure API sinatuaren hornitzailearekin

Direktiba NIS2 eta zerbitzuaren segitsazioa

Softwarearen editoreek entitate esential edo garrantzitsuk Direktiba NIS2-ren arabera (2022/2555), API talde honetara mendekotasuna bada dokumentatu egin ditzake zure analisiaren digital-katean arriskua. Eskatzen du API-ak sortu zure hornitzailea SOC 2 Type II sertifikazioa eta %99,9ko SLA bermea.

Erabileraren Eszenariak: API Sinatuaren Elektronikoa Sarrera

Eszenarioa 1 — Fournisseuraren Kontratuaren Automatioa PME Industrialean

PME industriala gutxi 200 hornitzaile-kontratu bapo urteko kudeatzea nahi izena zuzen zuzeneko aseriak eta harrera manualak mobilizatzen zituen 2 egunak osoa asistente administratiboan. Garapena taldea integratzea erabaki API REST sinatuaren elektronikoa zuzenean haien ERP negozioan:

1. Ebaketa bonu batean ERP-an baieztapena, `POST /v2/signature-requests` deiak automatikoki pizten dira
2. Sortutako PDF kontratua igoera eta sinatuaren eskaera hornitzaile kontaktuari bidaliko du
3. Webhook `signatory.signed` bon baten egoera eguneratzen du errealean
4. Sinatutako dokumentua eta audit pista DMS-an automatikoki gordetzea bigarren API deiarekin

Emaitzak ikusita (balioaren barrutia KPMG/IDC izerren txostenetan 2024-2025): sinatuaren batez besteko denbora murriztu 8 egun batetik 24 orduko baino gutxiago, asistenteko denboran %60-70eko aurrezkia estimatua, eta ez dokumentazio galtzea.

Eszenarioa 2 — Abokatuari kabinetaren LegalTech Plataforma

Software editorea SaaS soluzio garatzen ari da 5-30 laguneko abokatuaren kabinetei zuzenekoa API sinatuaren elektronikoa integratzea baimena ematen du beren erabiltzaileei amaiak, abokatuaren konbentzionak eta prozedura-aktoak zuzenean kabinetaren interfazean sinatzea.

Hautaturiko arkitektura teknika OAuth2 Authorization Code + PKCE fluxua erabiltzen du gero abogadu identifikatu eske deitako sinatuaren eskaera. Webhooks `signature_request.completed` automatikoki aktivatzen dute sinatutako dokumentuaren jaslokua kliente-txosten juridikoan.

Editoreak bereziki balioztatu zen sinatuaren elektroniko aurreratua (AES) API bidez eskuragarritasuna — mailak proposatuen Consejo Nazionalaren Barreak. Integrazio hasieraren garapen-denborak ~3 asteak ezarri garapen-atzean senior-entzat, test estaltzarekin %85a.

Eszenarioa 3 — Digitala Abizioa Kliniken Taldean

Klinika pribatuen ~600 ohe duten taldea behar zuen desmaterializatzea consentimiento argia osaketak eta sarrera-kontratua, arte 0ean inprima eta eskuz-sinatuak jasotzearen — kalkulatzen gastua milakatik duten euros urtean eta epeak itxaraketak errezeptsioan.

API integrazio konektatu spitalaren informatika-sistema (SIH) sinatuaren elektronikoa plataformara. Pazientearen erregistroan, SIH deituko luke API sinatuaren eskaera sortzera multipartite (pazientea + aginduko medikua) sinatuaren eremu-posizionamendua kalkulatuta ereduaren metadatuetan.

RGPD bateragarritasun automatikoa purga programatua exijitu API bidez ( `PATCH /v2/signature-requests` + webhookaren baieztazio-gainean) legaleko kontserbazio-denborden berdinerako (aditu maioretan medikua-dosier 20 urteak, Erregelamendua R. 1112-7ean). Neurtuak irabaziak %80ko murrizketak lortarazi errezeptsioan itxarote-denborotan eta %40ko aurrezkin inprimatzean eta digitalizazioko gastuetan.

Ondorioa

API REST sinatuaren elektronikoa integratzea 2026an eskatzen du neurrioetan dimentsioen kutsua: arkitektura RESTful biziago, OAuth2 autentifikazioa segurua, gestion gertakari webhooks bidez, eta eIDAS eta RGPD exigentziaren bateragarritasuna. Garapenariek aurreikustea dituzte integrazioaren desiderata osoan denbora-hobeduran sabereko dute kasuak eta legaleko arrisku nagusiak.

Hiru horrenptziak orotaraino: aseguratu zure API deitaketa (OAuth2 + scope minimalak + vault), osatu gertakaria asinkronoki eta idempotentea webhooks bidez, eta archibo beti sinatutako dokumentua beren auditaren pista sertifikatuarekin.

Certyneo-k API REST bakarrra duzu dokumentua, eIDAS-a bateragarria, libre sandbox eta garapena suportua dedikatu. Sortu zure Certyneo-rako kontua zure API sandbox gakoa sarbidetzeko eta zure integrazioa hastea asteletik.