Ir al contenido principal
Certyneo
API REST — eIDAS

La API de firma electrónica para desarrolladores

Integre la firma electrónica eIDAS en su aplicación en pocas horas. REST, webhooks fiables, SDK Node/Python/Ruby, sandbox gratuito ilimitado.

Crear una cuenta de desarrollador Documentación API

Sandbox gratuito · 99,95 % uptime · Alojamiento soberano UE

REST + OpenAPI 3.1

Endpoints predecibles, JSON limpio, códigos HTTP estándar. Spec OpenAPI 3.1 descargable para generar tus propios clientes.

Webhooks confiables

Reintento automático con backoff exponencial, firma HMAC SHA-256, registro de eventos consultable. Sin polling que codificar.

Conformidad eIDAS nativa

Firmas AES, AES-Q y QES disponibles mediante flag API. Pista de auditoría cualificada incluida, certificados TSP cualificados UE.

Latencia < 200 ms

API alojada en Estrasburgo (UE), p95 < 200 ms desde Europa. SLA 99,95 % uptime, estado público en tiempo real.

Inicio en 5 minutos

Crea tu primer sobre con una única solicitud HTTP.

cURL — Creación de un sobre
curl https://api.certyneo.com/v1/envelopes \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contrat de prestation",
    "documents": [{"file_url": "https://your.app/contract.pdf"}],
    "recipients": [{"email": "client@example.com", "name": "Jane Doe"}],
    "webhook_url": "https://your.app/webhooks/sign"
  }'

Una solicitud POST es suficiente para crear un sobre, añadir un documento, un firmante y la URL de webhook. La API devuelve un sign_url listo para compartir.

SDK Node.js oficial
import Certyneo from '@certyneo/sdk';

const client = new Certyneo({ apiKey: process.env.CERTYNEO_API_KEY });

const envelope = await client.envelopes.create({
  title: 'Contrat de prestation',
  documents: [{ file_url: 'https://your.app/contract.pdf' }],
  recipients: [{ email: 'client@example.com', name: 'Jane Doe' }],
});

console.log(envelope.sign_url); // ready to share with the signer

El SDK Node TypeScript proporciona tipado completo, gestión automática de errores con reintento, y un constructor de sobre fluido. Disponible también en Python y Ruby.

Webhooks — reacciona en tiempo real

Seis eventos (envelope.sent, viewed, signed, completed, declined, expired) con firma HMAC verificable y reintento automático.

envelope.completed
{
  "event": "envelope.completed",
  "envelope_id": "env_3a2f...",
  "signed_at": "2026-05-25T14:32:18Z",
  "evidence_url": "https://api.certyneo.com/v1/envelopes/env_3a2f.../audit-trail.pdf",
  "signers": [
    { "email": "client@example.com", "signed": true, "ip": "82.x.x.x" }
  ]
}
  • Firma HMAC SHA-256 de cada payload — verifica la autenticidad en el servidor.
  • Reintento automático en caso de fallo: 5 intentos en 24 horas con backoff exponencial.
  • Registro de eventos consultable desde el dashboard: ve cada intento, el código HTTP devuelto, el body.
  • URL de webhook configurable por sobre (override) o global en el proyecto.

¿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 modernas: paginación basada en cursor, idempotency keys, versionado por URL, OpenAPI 3.1 para generar tus clientes automáticamente. 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 Certyneo permite elegir el nivel por sobre mediante un campo `signature_level`. El valor por defecto es AES (suficiente para el 95% de los casos B2B). QES está disponible para actos que requieren equivalencia legal estricta con la firma manuscrita manual (actos notariales, licitaciones públicas).

A nivel técnico, AES exige autenticación fuerte del firmante (OTP por SMS por defecto, KYC por vídeo como opción) y un registro de auditoría con marca de tiempo. QES añade un certificado cualificado emitido por un PST cualificado de la UE. Todo esto lo gestiona la API — llamas al endpoint y nosotros nos encargamos del resto.

Arquitectura de integración recomendada

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

  • Tu backend llama a POST /v1/envelopes para crear el sobre y recibe un sign_url para presentar al usuario.
  • Redirige al usuario hacia sign_url o incrústalo en un iframe (con tu marca mediante el plan Pro).
  • 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.).

Sandbox gratuito e ilimitado

El entorno sandbox es gratuito e ilimitado. Todas las funcionalidades de producción están disponibles, excepto que las firmas no tienen valor legal (el PDF está marcado SANDBOX). Práctico para pruebas automatizadas, demostraciones con clientes, desarrollo local. Las claves sandbox son distintas de las claves prod, aislamiento total entre ambas.

Migrar desde DocuSign o Yousign

Si ya tienes una integración con DocuSign o Yousign, el mapeo de API es directo: envelopes → envelopes, recipients → recipients, status webhooks → status webhooks. Nuestra guía de migración documenta las equivalencias endpoint por endpoint. Cuenta de 1 a 3 días para una migración completa, mucho menos si utilizas un wrapper interno.

Preguntas frecuentes — API

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

1 000 solicitudes por minuto por defecto, ampliable bajo demanda para usos elevados (factories, plataformas multi-tenant). El encabezado X-RateLimit-Remaining en cada respuesta indica la cuota restante. Si se supera, la API devuelve 429 con un Retry-After.

¿Cuánto cuesta la API?

El sandbox es gratuito e ilimitado. La producción funciona con pago por firma (desde 0,40 € la firma AES con degresión por volumen), sin suscripción mínima. El plan Enterprise incluye un SLA reforzado, IP whitelisting y una cuenta técnica dedicada.

¿Hay un SLA?

99,95 % de disponibilidad en los planes Business y Enterprise (tiempo de inactividad máximo de 4 horas por año). Página de estado pública con historial de incidentes: status.certyneo.com. El plan Enterprise incluye un crédito automático en caso de incumplimiento del SLA.

¿Qué autenticación utilizan?

Token Bearer (clave API) en el encabezado Authorization. Las claves son rotables desde el dashboard, con revocación inmediata. Para integraciones OAuth (plataforma multi-tenant), ofrecemos OAuth 2.0 Client Credentials en el plan Enterprise.

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

Cada webhook incluye un encabezado X-Certyneo-Signature que contiene un HMAC SHA-256 del payload, firmado con su secreto de webhook. Del lado del servidor, recalcule el HMAC y compare en tiempo constante (timing-safe comparison). El SDK oficial lo hace automáticamente mediante webhook.verify(payload, signature, secret).

¿Son los SDK de código abierto?

Sí. Los SDK de Node, Python y Ruby están en GitHub bajo licencia MIT. Puede hacer fork, contribuir o simplemente auditarlos. Los binarios se publican en npm, PyPI y RubyGems bajo el namespace @certyneo / certyneo.

¿Puedo probar sin registrarme?

Sí, a través de los ejemplos interactivos de la documentación de API: /developers/playground. Las solicitudes se ejecutan contra una instancia sandbox compartida, sin necesidad de clave. Para un uso serio, cree una cuenta de desarrollador gratuita (sandbox ilimitado).

¿Listo para integrar la firma electrónica?

Sandbox gratuito ilimitado, documentación completa, SDK oficiales. Comience ahora.

Leer la documentación Hable con un desarrollador de Certyneo