API Sinatura Electrónica: Guía de Desenvolvedor REST 2026

Introdución

A integración dunha API REST de sinatura electrónica converteuse nun requisito inescusable para os equipos de desenvolvemento en 2026. Con máis do 73% das empresas europeas tendo digitalizado polo menos un proceso contractual (fonte: IDC European Digital Transformation Report 2025), a demanda de integracións técnicas sólidas explota. Tanto se estás construíndo un SaaS LegalTech, un ERP ou unha plataforma RH, comprender como consumir unha API de sinatura electrónica — autenticación OAuth2, xestión de webhooks, conformidade eIDAS — determina directamente a calidade e o valor xurídico dos teus fluxos documentarios. Esta guía de desenvolvedor REST acompáñate paso a paso: arquitectura, autenticación, ciclo de vida dun documento, webhooks en tempo real e boas prácticas de seguridade.

---

Arquitectura dunha API REST de Sinatura Electrónica

Principios RESTful e estrutura dos endpoints

Unha API REST de sinatura electrónica ben deseñada repousa en recursos claramente identificados e verbos HTTP semánticos. Os recursos fundamentais son xeralmente:

• `/documents` — carga, xestión e recuperación de documentos PDF/DOCX
• `/signature-requests` — creación e pilotaxe das solicitudes de sinatura
• `/signatories` — xestión dos asinantes e das súas identidades
• `/audit-trails` — recuperación dos diarios de auditoría certificados
• `/templates` — xestión dos modelos de documentos reutilizables

Cada recurso expón endpoints CRUD estándar (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) e devolve respostas JSON con códigos HTTP normalizados: `200 OK`, `201 Created`, `400 Bad Request`, `401 Unauthorized`, `422 Unprocessable Entity`, `429 Too Many Requests`.

Un aspecto crítico a miúdo negligenciado: a xestión da paxinación. As APIs maduras usan o patrón cursor-based en lugar de offset/limit, o que garante un desempeño estable incluso en volumes de miles de documentos asinados. Verifica que a API obxectivo expón un encabezado `X-Next-Cursor` ou un campo `next_page_token` no corpo.

Versionado da API e compatibilidade ascendente

O versionado constitúe un punto de vixilancia importante para os integradores. Os dous enfoques dominantes en 2026 son:

1. Versionado por URL: `https://api.certyneo.com/v2/signature-requests` — lexible, cacheable polos CDN, recomendado para APIs B2B.
2. Versionado por encabezado: `Accept: application/vnd.certyneo.v2+json` — máis limpo arquitectonicamente pero menos visible.

Privilexia os provedores que se comprometen cunha política de deprecación mínima de 12 meses e que publican un changelog público. Un cambio de compatibilidade non anunciado no teu fluxo de sinatura pode ter consecuencias xurídicas directas (contratos non asinados, prazos perdidos).

---

Autenticación OAuth2 e Seguridade das Chamadas API

OAuth2: fluxo client_credentials vs authorization_code

A autenticación é a pedra angular de calquera integración API de sinatura electrónica. Os dous fluxos OAuth2 máis relevantes para desenvolvedores son:

Fluxo Client Credentials (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 ``` Este fluxo é ideal para integracións servidor-a-servidor onde ningún usuario final está implicado na autenticación (procesamento en lote, automatización de contratos).

Fluxo Authorization Code + PKCE: recomendado cando a túa aplicación actúa en nome dun usuario final identificado. O PKCE (Proof Key for Code Exchange) é obrigatorio desde a RFC 7636 e protexe contra ataques de interceptación.

Consellos de seguridade esenciais:

• Almacena os `client_secret` nun vault (HashiCorp Vault, AWS Secrets Manager) — nunca en variable de contorno non cifrada
• Implementa a rotación automática de tokens cun buffer de 60 segundos antes de expiración
• Usa scopes granulares: non solicites máis que os permisos estrictamente necesarios

Xestión de claves API e rate limiting

Para integracións lixeiras ou contornos de proba, algunhas APIs ofrecen claves API estáticas (Bearer Token). Se as usas en produción, aplica sistematicamente:

• Rotación trimestral das claves
• Restrición por IP (allowlist)
• Supervisión de chamadas anormais a través do teu SIEM

O rate limiting é unha realidade inescusable: as APIs de sinatura limitán xeralmente entre 100 e 1000 chamadas/minuto segundo o plan. Implementa un mecanismo de retry exponencial con xitter: ``` retry_delay = base_delay * (2^attempt) + random_jitter ``` Respecta escrupulosamente o encabezado `Retry-After` devolto coas `429 Too Many Requests`.

---

Ciclo de Vida dunha Solicitude de Sinatura vía API

Creación e configuración dunha solicitude de sinatura

O ciclo de vida dunha solicitude de sinatura vía API REST segue un esquema de estados (`draft` → `pending` → `in_progress` → `completed` | `declined` | `expired`). Aquí están os pasos técnicos detallados:

Paso 1 — Carga do documento: ``` POST /v2/documents Content-Type: multipart/form-data

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

Paso 2 — Creación da solicitude: ```json POST /v2/signature-requests { "document_id": "doc_a1b2c3", "name": "Contrato de prestación Q3 2026", "signatories": [ { "email": "signatario@cliente.es", "first_name": "María", "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 } } ```

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

A partir da activación, os asinantes reciben as súas invitacións e a solicitude pasa ao estado `in_progress`.

Recuperación do documento asinado e do arquivo de auditoría

Unha vez alcanzado o estado `completed` (detectable vía webhook — ver sección seguinte), recupera:

``` GET /v2/signature-requests/req_x9y8z7/document/signed → PDF asinado con sinaturas electrónicas incrustadas (PAdES-B-T segundo ETSI EN 319 132)

GET /v2/signature-requests/req_x9y8z7/audit-trail → PDF do diario de auditoría certificado (horodataxe calificado RFC 3161) ```

Almacena sempre os dous ficheiros xuntos na túa GED ou DMS. O diario de auditoría é a proba opositiva en caso de contestación xudicial.

---

Webhooks: Eventos en Tempo Real e Xestión de Erros

Configuración e aseguramento dos webhooks

Os webhooks transforman a túa integración dun polling custoso nunha arquitectura de eventos reactiva. Configura o teu endpoint webhook:

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

Aseguramento HMAC obrigatorio: valida cada payload de entrada comparando a sinatura HMAC-SHA256 calculada co encabezado `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) ``` Nunca uses unha comparación de cadeas clásica — vulnerable aos ataques de temporización.

Idempotencia e xestión de retransmisións

Os webhooks poden ser retransmitidos en caso de timeout ou erro 5xx do teu endpoint. Implementa a idempotencia obrigatoriamente:

1. Extrae o `event_id` único de cada payload webhook
2. Verifica en base de datos se este `event_id` xa foi procesado
3. Devolve `200 OK` inmediatamente (mesmo para duplicados) para evitar retransmisións infinitas
4. Procesa a lóxica de negocio de forma asincrónica (cola: Redis, RabbitMQ, SQS)

Regra de ouro: o túo endpoint webhook debe responder en menos de 5 segundos. Calquera procesamento de negocio pesado (envío de correo electrónico, arquivamento en GED, notificación ERP) debe ser delegado a un worker asincrónico.

Para profundizar na túa comprensión dos niveis de sinatura dispoñibles vía API, consulta a nosa guía completa de sinatura electrónica que detalla as diferenzas entre sinaturas simples, avanzadas e calificadas.

---

Boas Prácticas de Integración e Desempeño

Contornos sandbox e estratexia de probas

Calquera API de sinatura electrónica seria ofrece un contorno sandbox illado da produción. Adopta esta estratexia de probas:

• Probas unitarias: simular as respostas API (Wiremock, MSW) para validar a túa lóxica de negocio sen depender da rede
• Probas de integración: executar contra o sandbox real para validar o ciclo de vida completo (creación → sinatura → recuperación)
• Probas de carga: simular picos de solicitudes simultáneas para identificar os teus cuellos de botella antes de ir a produción
• Probas de caos: simular timeouts e erros 5xx para validar a túa lóxica de retry

Nunca propes en produción con verdadeiras identidades de asinantes. As sinaturas electrónicas creadas en sandbox non teñen valor xurídico, que é exactamente o que desexas para as túas probas.

Supervisión, observabilidade e alertas

En produción, instrumenta a túa integración con:

• Métricas: taxa de éxito das chamadas API, latencia p95/p99, taxa de erro por endpoint
• Trazas distribuídas: propaga os `trace-id` nos teus encabezados para correlacionar os teus logs cos logs API do provedor
• Alertas: dispara un alerta se a taxa de erro supera o 1% ou se a latencia p99 supera 3 segundos

Consulta o noso comparativo de solucións de sinatura electrónica para avaliar os SLA de dispoñibilidade (uptime) ofrecidos por diferentes provedores — un criterio a miúdo subestimado ao integrar API.

Se estás migrando doutro plataforma, a nosa guía sobre como migrar de DocuSign ou YouSign a Certyneo cobre os aspectos técnicos da migración de API e a compatibilidade dos webhooks existentes.

Para estimar o retorno de inversión da túa integración, usa a nosa calculadora ROI de sinatura electrónica que integra os ganhos de produtividade relacionados coa automatización vía API.

Por último, se desexas ir máis alá na xeración automatizada de documentos para asinar, descubre o noso xerador de contratos por IA que se interface nativamente coa nosa API REST.

Marco Xurídico Aplicable á API de Sinatura Electrónica

A integración dunha API de sinatura electrónica non se limita a un reto técnico: implica directamente a responsabilidade xurídica do editor e dos seus clientes en varios textos fundamentais.

Regulamento eIDAS nº910/2014 e eIDAS 2.0

O Regulamento (UE) nº910/2014 (eIDAS) establece o marco xurídico da sinatura electrónica na Unión Europea. Diferencia tres niveis:

• Sinatura electrónica simple (SES): valor xurídico mínimo, axeitada para actos de baixo risco
• Sinatura electrónica avanzada (AES): vinculada de xeito unívoco ao asinante, creada a partir de datos baixo o seu control exclusivo — artigo 26 eIDAS
• Sinatura electrónica calificada (QES): equivalente a unha sinatura manuscrita en toda a UE — artigo 25 §2 eIDAS

Coa entrada en aplicación progresiva do regulamento eIDAS 2.0 (Regulamento UE 2024/1183), os desenvolvedores deben anticipar a integración das Carteiras Europeas de Identidade Dixital (EUDIW) nos seus fluxos de autenticación. Consulta a nosa guía eIDAS 2.0 para as implicacións técnicas detalladas.

Código civil francés — Artigos 1366 e 1367

En dereito francés, o artigo 1366 do Código civil establece que «o escrito electrónico ten a mesma forza probatoria que o escrito en soporte papel, baixo reserva de que poida ser devidamente identificada a persoa da que emana e de que se estableza e se conserve en condicións de natureza a garantir a súa integridade».

O artigo 1367 precisa as condicións da sinatura electrónica fiable: identificación do asinante e garantía de integridade do documento. Estes requisitos tradúcense tecnicamente na obriga de conservar os diarios de auditoría certificados e as probas de identidade utilizadas durante a sinatura — elementos que a túa API debe expor e que debes almacenar.

Normas ETSI EN 319 132 — PAdES

O formato técnico obrigatorio para sinaturas PDF conformes eIDAS é PAdES (PDF Advanced Electronic Signatures), definido pola norma ETSI EN 319 132. A túa API debe producir sinaturas PAdES-B-T (con horodataxe) como mínimo, e PAdES-B-LT ou PAdES-B-LTA para garantir a validabilidade a longo prazo (arquivamento 10+ anos).

RGPD nº2016/679 — Datos dos asinantes

Os datos persoais recollidos durante o proceso de sinatura (nome, apelido, correo electrónico, dirección IP, datos de identidade para AES/QES) constitúen datos de carácter persoal sometidos ao RGPD. As túas obrigas como responsable de tratamento ou subcontratista inclúen:

• Definir unha duración de conservación xustificada (xeralmente alineada cos prazos de prescrición: 5 anos en dereito común)
• Prever un mecanismo de purga automática vía API (`DELETE /v2/signature-requests/{id}/personal-data`)
• Documentar o tratamento no túo rexistro de actividades de tratamento (artigo 30 RGPD)
• Pechar un DPA (Data Processing Agreement) co túo provedor de API de sinatura

Directiva NIS2 e continuidade de servizo

Para editores de software cualificados de entidades esenciais ou importantes ao sentido da Directiva NIS2 (2022/2555), a integración dunha API de terceiros crea unha dependencia que debe documentarse na túa análise de riscos da cadea de subministración dixital. Esixe ao túo provedor de API unha certificación SOC 2 Type II e un SLA de dispoñibilidade ≥ 99,9%.

Escenarios de Uso: API de Sinatura Electrónica na Práctica

Escenario 1 — Automatización de contratos con provedores nunha PEME industrial

Unha PEME industrial xestionando aproximadamente 200 contratos con provedores por ano quería eliminar os vaivéns de papel e as lembranzas manuais que mobilizaban 2 días ao mes dun asistente administrativo. O equipo de desenvolvemento integrou a API REST de sinatura electrónica directamente no seu ERP específico a través do seguinte fluxo:

1. A validación dun pedido de compra no ERP, unha chamada `POST /v2/signature-requests` desencádease automaticamente
2. O contrato PDF xerado é enviado e unha solicitude de sinatura é enviada ao contacto de provedor referenciado
3. Un webhook `signatory.signed` actualiza o estado do pedido de compra en tempo real
4. O documento asinado e o diario de auditoría son arquivados automaticamente na GED a través dunha segunda chamada API

Resultados observados (intervalo de informes de sectores KPMG/IDC 2024-2025): redución do prazo medio de sinatura de 8 días a menos de 24 horas, economía estimada do 60-70% do tempo administrativo dedicado ás lembranzas, e cero perda documentaria.

Escenario 2 — Plataforma LegalTech para bufetes de avogados

Un editor de software desenvolvendo unha solución SaaS para bufetes de avogados de 5 a 30 colaboradores integrou a API de sinatura electrónica para permitir aos seus usuarios finais facer asinar os mandatos, convencións de honorarios e actos de procedemento directamente desde a interface do bufete.

A arquitectura técnica retida usa o fluxo OAuth2 Authorization Code + PKCE para que cada avoado autentica as solicitudes en seu nome propio. Os webhooks `signature_request.completed` desencadean automaticamente o depósito do documento asinado no cartafol do cliente da GED xurídica.

O editor valorizou especialmente a dispoñibilidade das sinaturas electrónicas avanzadas (AES) vía API — nivel requirido para as convencións de honorarios segundo as recomendacións do Consello Nacional de Barras. O tempo de desenvolvemento da integración inicial estabeleceuse en aproximadamente 3 semanas para un desenvolvedor backend sénior, con cobertura de probas do 85%.

Escenario 3 — Incorporación dixital nun grupo de clínicas privadas

Un grupo de clínicas privadas de aproximadamente 600 prazas debía desmaterializar os formularios de consentimento informado e os contratos de admisión, ata ese momento impresos e asinados manualmente na recepción — xerando custos de impresión estimados en varios miles de euros ao ano e tempos de espera na recepción.

A integración de API conectou o sistema de información hospitalario (SIH) á plataforma de sinatura electrónica. No rexistro dun paciente, o SIH chama á API para crear unha solicitude de sinatura multipartita (paciente + médico referente) con posicionamento automático dos campos de sinatura calculado a partir dos metadatos do template.

A conformidade RGPD requiriu a implementación dunha purga automática programada vía API (`PATCH /v2/signature-requests` + webhook de confirmación de eliminación) alineada coas duracións de conservación legais dos dossiers médicos (20 anos para maiores de idade, segundo o artigo R. 1112-7 do Código de Saúde Pública). Os ganhos medidos chegaron a unha redución do 80% do tempo de espera na admisión e unha economía do 40% nos custos de impresión e dixitalización.

Conclusión

Integrar unha API REST de sinatura electrónica en 2026 require unha maestría simultánea de varias dimensións: arquitectura RESTful sólida, autenticación OAuth2 segura, xestión de eventos a través de webhooks, e conformidade cos requisitos eIDAS e RGPD. Os desenvolvedores que anticipan estas cuestións desde o deseño da súa integración evítanse refactorizacións custozas e riscos xurídicos importantes.

Os tres pilares a recordar: asegura as túas chamadas API (OAuth2 + scopes mínimos + vault), procesa os eventos de forma asincrónica e idempotente vía webhooks, e arquiva sistematicamente o documento asinado co seu diario de auditoría certificado.

Certyneo pon á disposición unha API REST documentada, conforme a eIDAS, con sandbox gratuíto e soporte técnico de desenvolvedor dedicado. Crea a túa conta Certyneo para acceder á túa clave API sandbox e comeza a túa integración hoxe mesmo.