API Signatura Electrònica: Guia Desenvolupador REST 2026

Introducció

L'integració d'una API REST de signatura electrònica s'ha convertit en un requisit indispensable per als equips de desenvolupament el 2026. Amb més del 73 % de les empreses europees que han digitalitzat almenys un procés contractual (font: IDC European Digital Transformation Report 2025), la demanda d'integracions tècniques robustes explota. Tant si construeixes un LegalTech SaaS, un ERP o una plataforma RH, comprendre com consumir una API de signatura electrònica — autenticació OAuth2, gestió de webhooks, conformitat eIDAS — determina directament la qualitat i el valor jurídic dels teus fluxos documentals. Aquesta guia desenvolupador REST t'acompanya pas a pas: arquitectura, autenticació, cicle de vida d'un document, webhooks en temps real i bones pràctiques de seguretat.

---

Arquitectura d'una API REST de Signatura Electrònica

Principis RESTful i estructura dels endpoints

Una API REST de signatura electrònica ben dissenyada es recolza en recursos clarament identificats i verbs HTTP semàntics. Els recursos fonamentals solen ser:

• `/documents` — càrrega, gestió i recuperació de documents PDF/DOCX
• `/signature-requests` — creació i pilotatge de les demandes de signatura
• `/signatories` — gestió dels signataris i de les seves identitats
• `/audit-trails` — recuperació dels diaris d'auditoria certificats
• `/templates` — gestió dels models de documents reutilitzables

Cada recurs exposa endpoints CRUD estàndard (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) i retorna respostes JSON amb codis HTTP normalitzats: `200 OK`, `201 Created`, `400 Bad Request`, `401 Unauthorized`, `422 Unprocessable Entity`, `429 Too Many Requests`.

Un aspecte crític sovint negligit: la gestió de la paginació. Les APIs madures utilitzen el patró cursor-based en comptes offset/limit, que garanteix un rendiment estable fins i tot amb volums de milers de documents signats. Verifica que l'API objectiu exposa una capçalera `X-Next-Cursor` o un camp `next_page_token` dins el body.

Versionat de l'API i compatibilitat ascendent

El versionat constitueix un punt de vigilància major per als integradors. Els dos enfocaments dominants el 2026 són:

1. Versionat per URL: `https://api.certyneo.com/v2/signature-requests` — llegible, cacheable pels CDN, recomanat per a les APIs B2B.
2. Versionat per capçalera: `Accept: application/vnd.certyneo.v2+json` — més net arquitectònicament però menys visible.

Prioritza els proveïdors que s'enganen en una política de depreciació mínima de 12 mesos i que publiquen un changelog públic. Una ruptura de compatibilitat no anunciada en el teu flux de signatura pot tenir conseqüències jurídiques directes (contractes no signats, terminis perduts).

---

Autenticació OAuth2 i Seguretat dels Crides API

OAuth2: flux client_credentials vs authorization_code

L'autenticació és la pedra angular de tota integració API de signatura electrònica. Els dos fluxos OAuth2 més rellevants per als desenvolupadors són:

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 ``` Aquest flux és ideal per a les integracions servidor-a-servidor on cap usuari final no està implicat en l'autenticació (processament per lots, automatització de contractes).

Authorization Code Flow + PKCE: recomanat quan la teva aplicació actua en nom d'un usuari final identificat. El PKCE (Proof Key for Code Exchange) és obligatori des de la RFC 7636 i protegeix contra atacs d'intercepció.

Consells de seguretat essencials:

• Emmagatzema els `client_secret` en un vault (HashiCorp Vault, AWS Secrets Manager) — mai en una variable d'entorn no encriptada
• Implementa la rotació automàtica de tokens amb un buffer de 60 segons abans de l'expiració
• Utilitza scopes granulars: només sol·licita les permisos estrictament necessaris

Gestió de claus API i rate limiting

Per a les integracions lleugeres o els entorns de prova, algunes APIs ofereixen claus API estàtiques (Bearer Token). Si les utilitzes en producció, aplica sistemàticament:

• Rotació trimestral de les claus
• Restricció per IP (allowlist)
• Monitoratge dels crides anòmals via el teu SIEM

El rate limiting és una realitat incontornnable: les APIs de signatura limiten generalment entre 100 i 1000 crides/minut segons el pla. Implementa un mecanisme de retry exponencial amb jitter: ``` retry_delay = base_delay * (2^attempt) + random_jitter ``` Respecta escrupulosament la capçalera `Retry-After` retornada amb els `429 Too Many Requests`.

---

Cicle de Vida d'una Demanda de Signatura via API

Creació i configuració d'una demanda de signatura

El cicle de vida d'una demanda de signatura via API REST segueix un esquema d'estats (`draft` → `pending` → `in_progress` → `completed` | `declined` | `expired`). Aquí tens els passos tècnics detallats:

Pas 1 — Càrrega del document: ``` POST /v2/documents Content-Type: multipart/form-data

file=@contrat.pdf ``` Resposta: `{ "document_id": "doc_a1b2c3", "checksum_sha256": "e3b0c442..." }`

Pas 2 — Creació de la demanda: ```json POST /v2/signature-requests { "document_id": "doc_a1b2c3", "name": "Contrato de prestación Q3 2026", "signatories": [ { "email": "signatari@client.fr", "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 } } ```

Pas 3 — Activació: `POST /v2/signature-requests/req_x9y8z7/activate`

A partir de l'activació, els signataris reben les seves invitacions i la demanda passa a l'estat `in_progress`.

Recuperació del document signat i de l'auditoria

Un cop assolit l'estat `completed` (detectible via webhook — veure secció següent), recupera:

``` GET /v2/signature-requests/req_x9y8z7/document/signed → PDF signat amb signatures electrònicas incrustades (PAdES-B-T segons ETSI EN 319 132)

GET /v2/signature-requests/req_x9y8z7/audit-trail → PDF del diari d'auditoria certificat (horodat qualificat RFC 3161) ```

Emmagatzema sempre els dos fitxers junts en la teva GED o DMS. El diari d'auditoria és la prova oposable en cas de contestació judicial.

---

Webhooks: Esdeveniments en Temps Real i Gestió d'Errors

Configuració i sectorització dels webhooks

Els webhooks transformen la teva integració d'un polling costós en una arquitectura d'events reactiva. Configura el teu endpoint webhook:

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

Sectorització HMAC obligatòria: valida cada payload entrant comparant la signatura HMAC-SHA256 calculada amb la capçalera `X-Certyneo-Signature`: ```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) ``` Mai utilitzis una comparació de cadenes clàssica — vulnerable als timing attacks.

Idempotència i gestió de retransmissions

Els webhooks es poden redelivrar en cas de timeout o error 5xx del teu endpoint. Implementa l'idempotència obligatòriament:

1. Extreu l'`event_id` únic de cada payload webhook
2. Verifica en base de dades si aquest `event_id` ja ha estat processat
3. Retorna `200 OK` immediatament (fins i tot per als dobles) per evitar retransmissions infinites
4. Tracta la lògica empresarial de forma asincrònica (cua: Redis, RabbitMQ, SQS)

Regla d'or: el teu endpoint webhook ha de respondre en menys de 5 segons. Tot tractament empresarial pesat (enviament d'email, arxivament GED, notificació ERP) ha de ser delegat a un worker asincrònic.

Per aprofundir la teva comprensió dels nivells de signatura disponibles via API, consulta la nostra guia completa de signatura electrònica que detalla les diferències entre signatures simples, avançades i qualificades.

---

Bones Pràctiques d'Integració i Rendiment

Entorns sandbox i estratègia de proves

Tota API de signatura electrònica seriosa ofereix un entorn sandbox aïllat de la producció. Adopta aquesta estratègia de proves:

• Proves unitàries: moquejar les respostes API (Wiremock, MSW) per validar la teva lògica empresarial sense dependre de la xarxa
• Proves d'integració: executar contra el sandbox real per validar el cicle de vida complet (creació → signatura → recuperació)
• Proves de càrrega: simular pics de demandes simultànies per identificar els teus colls d'ampolla antes de la posada en producció
• Proves de caos: simular timeouts i errors 5xx per validar la teva lògica de retry

Nun proveu en producció amb vertaderes identitats de signataris. Les signatures electrònicas creades en sandbox no tenen cap valor jurídic, que és exactament el que desitges per als teus proves.

Monitoratge, observabilitat i alerting

En producció, instrumenta la teva integració amb:

• Mètriques: taxa de succés dels crides API, latència p95/p99, taxa d'error per endpoint
• Traces distribuïdes: propaga els `trace-id` en les teves capçaleres per correlacionar els teus logs amb els logs API del proveïdor
• Alerting: activa una alerta si la taxa d'error supera l'1 % o si la latència p99 supera els 3 segons

Consulta el nostre comparatiu de solucions de signatura electrònica per avaluar els SLA de disponibilitat (uptime) proposats per diferents proveïdors — un criteri sovint subestima en integrar API.

Si migres des d'una altra plataforma, la nostra guia sobre com migrar de DocuSign o YouSign cap a Certyneo cobreix els aspectes tècnics de la migració d'API i la compatibilitat dels webhooks existents.

Per estimar la rendibilitat de la teva integració, utilitza el nostre calculador ROI de signatura electrònica que integra els guanys de productivitat lligats a l'automatització via API.

Finalment, si desitges anar més lluny en la generació automatitzada de documents per signar, descobreix el nostre generador de contractes per IA que s'interfaça nativament amb la nostra API REST.

Marc Legal Aplicable a l'API Signatura Electrònica

L'integració d'una API de signatura electrònica no es limita a un enjeu tècnic: compromet directament la responsabilitat jurídica de l'editor i dels seus clients sobre diversos textos fonamentals.

Reglament eIDAS n°910/2014 i eIDAS 2.0

El Reglament (UE) n°910/2014 (eIDAS) estableix el marc legal de la signatura electrònica a la Unió Europea. Distingeix tres nivells:

• Signatura electrònica simple (SES): valor jurídic mínim, adequada per a actes amb poc risc
• Signatura electrònica avançada (AES): lligada de manera univoca al signatari, creada a partir de dades sota el seu control exclusiu — article 26 eIDAS
• Signatura electrònica qualificada (QES): equivalent a una signatura manuscrita a tota la UE — article 25 §2 eIDAS

Amb l'entrada en aplicació progressiva del reglament eIDAS 2.0 (Reglament UE 2024/1183), els desenvolupadors han d'anticipar la integració dels Portefeuilles Europeus d'Identitat Digital (EUDIW) en els seus fluxos d'autenticació. Consulta la nostra guia eIDAS 2.0 per a les implicacions tècniques detallades.

Codi Civil Francés — Articles 1366 i 1367

En dret francés, l'article 1366 del Codi Civil estableix que « l'escrit electrònic té la mateixa força probatòria que l'escrit sobre suport paper, sota reserva que pugui ser degudament identificada la persona de la qual emana i que es estableixi i es conservi en condicions de naturalesa a garantir-ne la integritat ».

L'article 1367 precisa les condicions de la signatura electrònica fiable: identificació del signatari i garantia d'integritat del document. Aquests requisits es tradueixen tècnicament en l'obligació de conservar els diaris d'auditoria certificats i les proves d'identitat utilitzades en la signatura — elements que la teva API ha d'exposar i que has d'emmagatzemar.

Normes ETSI EN 319 132 — PAdES

El format tècnic obligatori per a les signatures PDF conformes eIDAS és PAdES (PDF Advanced Electronic Signatures), definit per la norma ETSI EN 319 132. La teva API ha de produir signatures PAdES-B-T (amb horodat) almenys, i PAdES-B-LT o PAdES-B-LTA per garantir la validabilitat a llarg termini (arxivament 10+ anys).

RGPD n°2016/679 — Dades dels signataris

Les dades personals recollides durant el procés de signatura (nom, cognom, email, adreça IP, dades d'identitat per a l'AES/QES) constitueixen dades de caràcter personal sotmeses al RGPD. Les teves obligacions com a responsable de tractament o subcontractista inclouen:

• Definir una durada de conservació justificada (generalment alineada amb els terminis de prescripció: 5 anys en dret comú)
• Preveure un mecanisme de purga automàtica via API (`DELETE /v2/signature-requests/{id}/personal-data`)
• Documentar el tractament en el teu registre de les activitats de tractament (article 30 RGPD)
• Concloure un DPA (Data Processing Agreement) amb el teu proveïdor d'API de signatura

Directiva NIS2 i continuïtat de servei

Per als editors de software qualificats d'entitats essencials o importants al sentit de la Directiva NIS2 (2022/2555), l'integració d'una API tercera crea una dependència que ha de ser documentada en la teva anàlisi dels riscos de la cadena d'aprovisionament digital. Exigeix al teu proveïdor API una certificació SOC 2 Type II i un SLA de disponibilitat ≥ 99,9 %.

Escenaris d'Ús: API Signatura Electrònica en Pràctica

Escenari 1 — Automatització dels contractes proveïdors en una PME industrial

Una PME industrial que gestionava aproximadament 200 contractes de proveïdors per any va voler eliminar els anar i portar paper i les relacions manuals que mobilitzaven 2 dies per mes d'un assistent administratiu. L'equip de desenvolupament va integrar l'API REST de signatura electrònica directament en el seu ERP empresarial via el flux següent:

1. En validar un bon de comanda a l'ERP, es desencadena automàticament una crida `POST /v2/signature-requests`
2. El contracte PDF generat es carrega i es redirecciona una demanda de signatura al contacte del proveïdor referenciat
3. Un webhook `signatory.signed` actualitza l'estat del bon de comanda en temps real
4. El document signat i el diari d'auditoria es arxiven automàticament en la GED via una segona crida API

Resultats observats (horquilla d'informes del sector KPMG/IDC 2024-2025): reducció del termini de signatura mitjà de 8 dies a menys de 24 hores, economia estimada del 60-70 % del temps administratiu dedicat a les relacions, i zero pèrdua documental.

Escenari 2 — Plataforma LegalTech per a despatxos d'advocats

Un editor de software que desenvolupava una solució SaaS destinada als despatxos d'advocats de 5 a 30 col·laboradors va integrar l'API de signatura electrònica per permetre als seus usuaris finals fer signar els mandats, convenis d'honoraris i actes de procediment directament des de la interfície del despatch.

L'arquitectura tècnica retinguda utilitza el flux OAuth2 Authorization Code + PKCE perquè cada advocat autentiqui les demandes en el seu propi nom. Els webhooks `signature_request.completed` desencadenen automàticament el dipòsit del document signat en la carpeta del client de la GED jurídica.

L'editor va valorar especialment la disponibilitat de les signatures electrònicas avançades (AES) via API — nivell requerit per als convenis d'honoraris segons les recomanacions del Consell Nacional dels Col·legis d'Advocats. El temps de desenvolupament de la integració inicial s'ha establert en aproximadament 3 setmanes per a un desenvolupador backend senior, amb una cobertura de proves del 85 %.

Escenari 3 — Incorporació digital en un grup de clíniques privades

Un grup de clíniques privades d'aproximadament 600 llits havia de desmaterialitzar els formularis de consentiment esclarit i els contractes d'admissió, fins al moment impresos i signats manualment a la recepció — generant costos d'impressió estimats en varis milers d'euros per any i terminis d'espera en recepció.

La integració API va connectar el sistema d'informació hospitalari (SIH) a la plataforma de signatura electrònica. Al registre d'un pacient, el SIH crida l'API per crear una demanda de signatura multipart (pacient + metge referent) amb posicionament automàtic dels camps de signatura calculat a partir de les metadades de la plantilla.

La conformitat RGPD va requerir la posada en marxa d'una purga automàtica programada via API (`PATCH /v2/signature-requests` + webhook de confirmació de supressió) alineada amb les durades de conservació legals dels dossiers métics (20 anys per als majors, segons l'article R. 1112-7 del Codi de la Salut Pública). Els guanys mesurits van arribar a una reducció del 80 % del temps d'espera a l'admissió i una economia del 40 % en costos d'impressió i digitalització.

Conclusió

Integrar una API REST de signatura electrònica el 2026 requereix un domini simultani de diverses dimensions: arquitectura RESTful robusta, autenticació OAuth2 segura, gestió d'events per webhooks, i conformitat amb els requisits eIDAS i RGPD. Els desenvolupadors que anticipen aquests enjeux des del disseny de la seva integració s'estalvien refaccions costoses i riscos jurídics majors.

Els tres pilars a recordar: securitza els teus crides API (OAuth2 + scopes mínims + vault), tracta els events de forma asincrònica i idempotent via webhooks, i arxiva sistemàticament el document signat amb el seu diari d'auditoria certificat.

Certyneo posa a disposició una API REST documentada, conforme eIDAS, amb sandbox gratuït i suport tècnic desenvolupador dedicat. Crea el teu compte Certyneo per accedir a la teva clau API sandbox i comença la teva integració avui mateix.