API REST — eIDAS

La API de firma electrónica para desarrolladores

Integre la firma electrónica eIDAS en su aplicación: API REST, webhooks firmados con HMAC, firma integrada en iframe y claves de prueba gratuitas desde la cuenta gratuita.

Crear una cuenta de desarrollador Documentación API

Claves de prueba gratuitas · SLA del 99,9 % (Business y Enterprise) · Alojamiento en la UE

API REST + OpenAPI

Endpoints predecibles, JSON limpio, códigos HTTP estándar. Especificación OpenAPI descargable para generar sus propios clientes.

Webhooks confiables

5 intentos con intervalos crecientes, firma HMAC SHA-256, eventos fallidos reenviables desde el panel de control. Sin polling que programar.

Conformidad eIDAS nativa

Firmas simple, avanzada (OTP por SMS) y cualificada, elegidas por sobre con el campo signatureLevel. Pista de auditoría con sello de tiempo adjunta a cada documento firmado.

Alojada en la UE

Servidores en Alemania, Francia y España. Límites de tasa publicados por plan y cabeceras X-RateLimit en cada respuesta. SLA del 99,9 % en Business y Enterprise.

Empiece con tres llamadas

Suba el PDF, cree el sobre y envíelo: bastan tres peticiones HTTP.

cURL — subir, crear, enviar

# 1. Upload the PDF
curl https://certyneo.com/api/v1/documents \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -F "file=@contrat.pdf"
# → { "id": "cm8doc...", "status": "READY", ... }

# 2. Create the envelope (draft)
curl https://certyneo.com/api/v1/envelopes \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Contrat de prestation",
    "documentIds": ["cm8doc..."],
    "recipients": [{ "email": "client@example.com", "name": "Jane Doe" }]
  }'
# → { "id": "cm8env...", "status": "DRAFT", ... }

# 3. Send the invitations
curl -X POST https://certyneo.com/api/v1/envelopes/cm8env.../send \
  -H "Authorization: Bearer $CERTYNEO_API_KEY"

POST /documents devuelve el identificador del PDF, POST /envelopes crea un borrador con sus firmantes y, después, POST /envelopes/:id/send envía las invitaciones. El progreso llega luego por webhook.

Node.js — fetch nativo, sin dependencias

// Node 18+ — native fetch, no dependency
import { readFile } from "node:fs/promises";

const API = "https://certyneo.com/api/v1";
const auth = { Authorization: `Bearer ${process.env.CERTYNEO_API_KEY}` };

// 1. Upload the PDF
const form = new FormData();
const pdf = new Blob([await readFile("contrat.pdf")], { type: "application/pdf" });
form.append("file", pdf, "contrat.pdf");
const doc = await (await fetch(`${API}/documents`, { method: "POST", headers: auth, body: form })).json();

// 2. Create the envelope (draft)
const envelope = await (await fetch(`${API}/envelopes`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    subject: "Contrat de prestation",
    documentIds: [doc.id],
    recipients: [{ email: "client@example.com", name: "Jane Doe" }],
  }),
})).json();

// 3. Send the invitations
await fetch(`${API}/envelopes/${envelope.id}/send`, { method: "POST", headers: auth });

No se necesita ningún SDK: la API se consume con el fetch nativo de Node 18 o con cualquier cliente HTTP. La especificación OpenAPI también permite generar un cliente tipado en su lenguaje.

Webhooks — reacciona en tiempo real

Los eventos de sobre y destinatario, firma HMAC verificable y reintento automático.

envelope.completed

{
  "id": "cm8f2h6a10004qr9k5p2wm3xt",
  "event": "envelope.completed",
  "data": {
    "envelopeId": "cm7x2k9p40001qz8h3f7bn2ld",
    "subject": "Contrat de prestation",
    "status": "COMPLETED",
    "completedAt": "2026-09-26T08:42:13.000Z",
    "recipientCount": 1,
    "recipients": [
      { "email": "client@example.com", "name": "Jane Doe", "role": "SIGNER", "status": "SIGNED" }
    ],
    "signedDocumentUrl": "https://storage.certyneo.com/signed/...pdf?X-Amz-Expires=604800&..."
  },
  "timestamp": "2026-09-26T08:42:13.521Z"
}

Firma HMAC SHA-256 de cada payload — verifica la autenticidad en el servidor.
Reintento automático en caso de fallo temporal: 5 intentos en aproximadamente 1 h 20 con backoff exponencial.
Los eventos fallidos aparecen en el panel de control y se pueden reenviar con un clic. Tras 5 fallos consecutivos, el endpoint se suspende y se le avisa.
Hasta 5 endpoints en Standard, 15 en Business y 50 en Business Pro, cada uno suscrito a los eventos que elija.

¿Por qué una API dedicada a la firma electrónica?

Integrar la firma electrónica en tu producto no es trivial. Necesitas garantías sobre el cumplimiento legal (eIDAS), la confiabilidad técnica (webhooks que realmente lleguen), y la soberanía de datos (alojamiento europeo para evitar la Cloud Act). La API Certyneo cubre los tres.

Diseñada por y para desarrolladores, sigue las convenciones REST: versión en la URL (/api/v1), paginación con page y limit, errores JSON con un código legible por máquina y especificación OpenAPI para generar sus clientes. Sin SOAP, sin XML, sin sorpresas.

Cumplimiento eIDAS explicado para desarrolladores

El reglamento eIDAS define tres niveles de firma: simple (SES), avanzada (AES) y cualificada (QES). La API de Certyneo permite elegir el nivel de cada sobre con el campo signatureLevel: SIMPLE (por defecto), ADVANCED o QUALIFIED. La firma simple cubre la mayoría de los contratos comerciales habituales; la QES se usa cuando una norma o un destinatario exige la equivalencia con la firma manuscrita.

En el plano técnico, el nivel avanzado activa automáticamente el OTP por SMS y exige un número de teléfono para cada firmante. La pista de auditoría lleva sello de tiempo conforme a la norma RFC 3161. La QES se basa en un certificado cualificado emitido por un prestador cualificado de servicios de confianza de la UE. Todo se controla mediante la API.

Arquitectura de integración recomendada

El patrón de integración más común sigue este flujo:

Su backend sube el PDF (POST /api/v1/documents), crea el sobre como borrador (POST /api/v1/envelopes) y luego lo envía (POST /api/v1/envelopes/:id/send).
El firmante recibe su invitación por correo electrónico o firma directamente en su interfaz gracias a la firma integrada en iframe (POST /api/v1/envelopes/:id/embed-url, desde el plan Standard).
Una vez completada la firma, Certyneo llama a tu webhook con el evento envelope.completed.
Actualizas tu base de datos y notificas al usuario (correo electrónico, in-app, etc.).

Claves de prueba gratuitas

Las claves sk_test_ están disponibles en todos los planes, incluido Gratis, y los sobres de prueba no consumen su cuota mensual. En el plan Gratis, solo pueden enviarse a su propia dirección de correo electrónico y están limitadas a 20 peticiones por hora; los planes de pago van de 200 a 1000 peticiones por hora. Los datos de prueba se borran a los 30 días. La primera clave de prueba de una cuenta gratuita desbloquea además un mes del plan Standard gratis.

¿Y si no quiere escribir código?

Todo lo que hace esta API también se puede controlar sin escribir una línea, desde un flujo: crear un sobre, enviarlo, reaccionar a una firma, recuperar el PDF sellado y su pista de auditoría. La misma base, con un diseñador visual en lugar del cliente HTTP. Ver la integración Power Automate y Microsoft 365.

Migrar desde DocuSign o Yousign

Si ya tiene una integración de firma con DocuSign o Yousign, el vocabulario es parecido: envelopes → envelopes, recipients → recipients, webhooks de estado → webhooks. La guía de migración de DocuSign y Yousign a Certyneo detalla los pasos, desde la exportación de las plantillas hasta el cambio de los webhooks.

¿Se está migrando desde Adobe Acrobat Sign (anteriormente EchoSign, luego Adobe Sign)? La asignación es igual de directa —agreements → envelopes, participants → recipients, webhooks → webhooks. Comparar Certyneo y Adobe Acrobat Sign →

Precio de una API de firma electrónica: ¿dónde comprar una suscripción?

No necesita presupuesto ni orden de compra para contratar una suscripción a la API de firma: las claves de prueba son gratuitas, la clave API se genera desde el panel de control y el acceso a la API REST de producción está incluido desde el plan Standard a 19 €/mes — webhooks incluidos, sin coste por firma simple.

Standard — 19 €/mes: 100 sobres/mes, API REST + webhooks, 10 usuarios
Business — 39 €/mes: 300 sobres/mes, envío en lote, formularios web
Business Pro — 99 €/mes: 1 000 sobres/mes, API de alta frecuencia (300 req/min), usuarios ilimitados

La firma cualificada (QES) se factura por uso y se paga en el momento del envío: 9,90 € por firma con una suscripción, cargados en la tarjeta registrada una vez agotadas las QES incluidas en Business y Business Pro, y 14,90 € sin suscripción.

Para volúmenes importantes o una necesidad de compromiso contractual (SLA, DPA dedicado, facturación anual), el plan Enterprise se contrata con el equipo comercial. En cualquier caso, los precios son públicos — compárelos antes de comprometerse.

Profundiza más

Preguntas frecuentes — API

¿Cuál es el límite de velocidad (rate limit) de la API?

El límite se aplica a cada clave, por minuto, según el plan: 60 peticiones en Standard, 120 en Business, 300 en Business Pro y 1000 en Enterprise. Cada respuesta incluye las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; por encima, la API devuelve 429 con una cabecera Retry-After.

¿Cuánto cuesta la API?

Las claves de prueba (sk_test_) son gratuitas en todos los planes. El acceso a la API REST de producción está incluido desde el plan Standard a 19 €/mes (100 sobres/mes), luego Business a 39 €/mes y Business Pro a 99 €/mes con cuotas crecientes; la firma cualificada (QES) se factura por uso, 9,90 € con una suscripción. Para volúmenes superiores, el plan Enterprise se contrata con el equipo comercial.

¿Hay un SLA?

Sí: 99,9 % de disponibilidad mensual en los planes Business y Enterprise, con un crédito en factura del 10 al 50 % según la desviación constatada. El estado del servicio se publica de forma continua en la página de estado de Certyneo.

¿Qué autenticación utilizan?

Una clave API en la cabecera Authorization (Bearer sk_live_… o sk_test_…). Las claves se crean y se revocan desde el panel de control, con efecto inmediato. Para una aplicación de terceros que actúa en nombre de sus usuarios, OAuth 2.0 está disponible con el flujo authorization code y PKCE.

¿Cómo verificar la firma HMAC de un webhook?

Cada webhook lleva su firma en la cabecera X-Certyneo-Signature: el HMAC SHA-256, en hexadecimal, del cuerpo sin procesar de la petición, calculado con el secreto de su endpoint. Vuelva a calcularlo en el servidor sobre el cuerpo sin modificar y compare en tiempo constante (crypto.timingSafeEqual en Node, hmac.compare_digest en Python).

¿Existe un SDK oficial?

Todavía no se ha publicado. La API se llama directamente por HTTP desde cualquier lenguaje, y la especificación OpenAPI permite generar un cliente tipado con openapi-generator o una herramienta equivalente. Sin código, Certyneo también está disponible en Make, n8n, Postman y RapidAPI.

¿Puedo probar sin pagar?

Sí: cree una cuenta gratuita y genere una clave sk_test_ desde el panel de control. La primera clave de prueba de una cuenta gratuita desbloquea además un mes del plan Standard gratis. La colección de Postman permite encadenar las primeras llamadas sin escribir código.

¿Cuánto cuesta la API EchoSign (que se convirtió en Adobe Acrobat Sign)?

EchoSign fue adquirida por Adobe en 2011 y rebautizada Adobe Sign y después Adobe Acrobat Sign: la API sigue existiendo, pero su precio no es público y requiere un presupuesto empresarial del equipo comercial de Adobe, normalmente por tramos de transacciones anuales. Certyneo, en cambio, publica sus precios: el acceso a la API de firma en producción está incluido desde el plan Standard a 19 €/mes, contratado en línea sin presupuesto, con claves de prueba gratuitas para evaluar la API antes de pagar.

¿Listo para integrar la firma electrónica?

Claves de prueba gratuitas, especificación OpenAPI, webhooks firmados. Empiece ahora.

Leer la documentación Hable con un desarrollador de Certyneo