Anar al contingut principal
Certyneo
API REST eIDAS

L'API de signatura electrònica per a desenvolupadors

Incorpora la signatura electrònica eIDAS a la teva aplicació en poques hores. REST, webhooks fiables, SDK Node/Python/Ruby, sandbox gratuït il·limitat.

Crea un compte de desenvolupador Document API

Sandbox gratuït · 99,95% de temps d'operació · Sovereign Hosting UE

REST + OpenAPI 3.1

Endpoints previsibles, JSON net, codis HTTP estàndard.

Webhooks fiables

Retry automàtic amb backup exponencial, signatura HMAC SHA-256, diari d'esdeveniments consultable.

Conformitat eIDAS nativa

Signatures AES, AES-Q i QES disponibles a través de bandera API.

Latença < 200 ms

API allotjada a Estrasburg (UE), p95 < 200 ms des d'Europa.

Començament en 5 minuts

Crea el teu primer sobre amb una sola petició HTTP.

cURL Creació d'una 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 sol·licitud POST és suficient per crear un sobre, afegir un document, un signatur i la URL del webhook. L'API retorna un sign_url a 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 Node TypeScript SDK proporciona la tipografia completa, la gestió automàtica d'errors amb retry, i un constructor d'envelope fluid. També està disponible en Python i Ruby.

Webhooks reaccionar en temps real

Sis esdeveniments (envelope.sent, viewed, signed, completed, declined, expired) amb signatura HMAC verificable i intent automàtic.

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" }
  ]
}
  • HMAC SHA-256 de cada càrrega comproveu la autenticitat al costat del servidor.
  • Retry automàtic en cas de fracàs: 5 intents en 24 hores amb backup exponencial.
  • L'historial d'esdeveniments consultable des del tauler: veure cada intent, l'estat HTTP retornat, el cos.
  • URL de webhook configurable per sobrepassament o global en el projecte.

Per què una API dedicada a la signatura electrònica?

La incorporació de la signatura electrònica en el seu producte no és fàcil. Necessites garanties de conformitat legal (eIDAS), fiabilitat tècnica (webhooks que arriben realment) i sobirania de dades (allotjament europeu per evitar l'Acte Cloud).

Dissenyada per i per a desenvolupadors, segueix les convencions REST modernes: paginació basada en cursors, claus idempotency, versioning per URL, OpenAPI 3.1 per generar els teus clients automàticament.

La conformitat eIDAS explicada per als desenvolupadors

El Reglament eIDAS defineix tres nivells de signatura: simple (SES), avançat (AES) i qualificat (QES). L'API Certyneo permet triar el nivell per sobre mitjançant un camp `signatura_level`. El valor per defecte és AES (suficient per al 95% dels casos B2B).

Des del punt de vista tècnic, AES requereix una autenticació forta del signatari (OTP per SMS per defecte, KYC video opcional) i una pista d'auditoria amb horari.

Arquitectura d'integració recomanada

El patró d'integració més comú segueix aquest flux:

  • El backend crida POST /v1/envelops per crear l'envelop i rep una sign_url per presentar-la a l'usuari.
  • Redirecteu l'usuari a la sign_url o embed-la en iframe (amb la vostra marca a través del pla Pro).
  • Una vegada que s'ha completat la signatura, Certyneo crida al webhook amb l'esdeveniment envelope.completed.
  • Actualitza la teva base de dades i notifica a l'usuari (correcte correu electrònic, aplicació, etc.).

Sandbox gratuït sense límits

L'entorn de la sandbox és gratuït i il·limitat. Totes les funcionalitats de producció estan disponibles, excepte que les signatures no tenen valor legal (el PDF està marcat SANDBOX). Pràctic per a proves automàtiques, demostracions de clients, desenvolupament local. Les claus de la sandbox són diferents de les claus prod, aïllament total entre les dues.

Migrar des de DocuSign o Yousign

Si ja tens una integració de DocuSign o Yousign, l'API de mapeig és directa: envelops → envelops, recipients → recipients, webhooks de estatus → webhooks de estatus.

Fada a les preguntes API

Quin és el límit de la fusta de l'API?

1000 requeriments per minut per defecte, incrementable a petició per a usos elevats (fabriques, plataformes multi-tenent). L'encapçalament X-RateLimit-Remaining en cada resposta indica la quota restant. En cas de superar-la, l'API retorna 429 amb un Retry-After.

Quant costa l'API?

La producció funciona amb pagament per signatura (des de 0,40 € la signatura AES amb degradació de volum), sense subscripció mínima.

Hi ha ALS?

99,95% de temps d'activitat en els plans Business i Enterprise (un temps d'inactivitat màxim de 4 hores per any). Pàgina de estatus públic amb historial d'incidents: status.certyneo.com. El pla Enterprise inclou un crèdit automàtic en cas de no compliment de l'SLA.

Quina autenticació utilitzeu?

Per a les integracions OAuth (plataforma multi-tenent), oferim un OAuth 2.0 Client Credentials en el pla d'empresa.

Com es pot verificar la signatura HMAC d'un webhook?

Cada webhook inclou un capçalà X-Certyneo-Signature que conté un HMAC SHA-256 de la càrrega utilitzada, signat amb el webhook secret.

Els SDKs són de codi obert?

Sí. Els SDK Node, Python i Ruby estan a GitHub sota llicència MIT. Pots forcar-los, contribuir-los o simplement auditar-los. Els binaris es publiquen a npm, PyPI i RubyGems sota l'espai de noms @certyneo / certyneo.

Puc provar sense inscriure'm?

Sí, a través dels exemples interactius de la documentació de l'API: /developers/playground. Les sol·licituds s'hi dirigeixen contra una instància de sandbox compartida, sense clau requerida. Per a ús seriós, crea un compte de desenvolupador gratuït (sandbox il·limitat).

Estàs preparat per incorporar la signatura electrònica?

Sandbox gratuït il·limitat, documentació completa, SDK oficials.

Llegeix la documentació Parlar amb un desenvolupador de Certyneo