Zum Hauptinhalt springen
Certyneo
REST-API — eIDAS

Die API für elektronische Signaturen für Entwickler

Integrieren Sie eIDAS-Signaturen in wenigen Stunden in Ihre Anwendung. REST, zuverlässige Webhooks, SDK für Node/Python/Ruby, unbegrenzter kostenloser Sandbox.

Entwicklerkonto erstellen API-Dokumentation

Kostenloser Sandbox · 99,95 % Uptime · Souveränes EU-Hosting

REST + OpenAPI 3.1

Vorhersehbare Endpoints, sauberes JSON, Standard-HTTP-Codes. OpenAPI-3.1-Spezifikation herunterladbar, um Ihre eigenen Clients zu generieren.

Zuverlässige Webhooks

Automatische Wiederholung mit exponentiellem Backoff, HMAC SHA-256-Signatur, durchsuchbares Ereignisjournal. Kein Polling zum Programmieren erforderlich.

Native eIDAS-Konformität

AES-, AES-Q- und QES-Signaturen verfügbar über API-Flag. Qualifizierter Audit-Trail enthalten, qualifizierte EU-TSP-Zertifikate.

Latenz < 200 ms

API in Straßburg (EU) gehostet, p95 < 200 ms von Europa aus. 99,95 % Uptime-SLA, öffentlicher Echtzeit-Status.

Start in 5 Minuten

Erstellen Sie Ihren ersten Umschlag mit einer einzigen HTTP-Anfrage.

cURL — Umschlag erstellen
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"
  }'

Eine POST-Anfrage reicht aus, um einen Umschlag zu erstellen, ein Dokument hinzuzufügen, einen Unterzeichner und die Webhook-URL festzulegen. Die API gibt eine sign_url zurück, die sofort freigegeben werden kann.

Offizielles Node.js SDK
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

Das Node TypeScript SDK bietet vollständiges Typing, automatische Fehlerbehandlung mit Retry und einen fluent Envelope Builder. Auch in Python und Ruby verfügbar.

Webhooks — reagieren Sie in Echtzeit

Sechs Ereignisse (envelope.sent, viewed, signed, completed, declined, expired) mit verifizierbarer HMAC-Signatur und automatischer Wiederholung.

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-Signatur für jeden Payload — überprüfen Sie die Authentizität auf der Serverseite.
  • Automatische Wiederholung bei Fehler: 5 Versuche über 24 Stunden mit exponentiellem Backoff.
  • Durchsuchbares Ereignisjournal vom Dashboard aus: sehen Sie jeden Versuch, den zurückgegebenen HTTP-Status, den Body.
  • Webhook-URL konfigurierbar pro Umschlag (Überschreibung) oder global im Projekt.

Warum eine dedizierte API für elektronische Signaturen?

Die Integration von elektronischen Signaturen in Ihr Produkt ist nicht trivial. Sie benötigen Garantien für rechtliche Konformität (eIDAS), technische Zuverlässigkeit (Webhooks, die wirklich ankommen), und Datensouveränität (europäisches Hosting zur Vermeidung des Cloud Act). Die Certyneo API deckt alle drei ab.

Entwickelt von und für Entwickler, folgt sie modernen REST-Konventionen: cursor-basierte Pagination, Idempotency Keys, Versionierung über URL, OpenAPI 3.1 zur automatischen Client-Generierung. Kein SOAP, kein XML, keine Überraschungen.

eIDAS-Compliance erklärt für Entwickler

Die eIDAS-Verordnung definiert drei Signatur-Ebenen: einfach (SES), fortgeschritten (AES) und qualifiziert (QES). Die Certyneo-API ermöglicht die Wahl der Ebene pro Umschlag über ein Feld `signature_level`. Der Standardwert ist AES (ausreichend für 95 % der B2B-Fälle). QES ist verfügbar für Dokumente, die eine strikte rechtliche Gleichwertigkeit mit handschriftlicher Unterschrift erfordern (notarielle Urkunden, öffentliche Aufträge).

Technisch gesehen erfordert AES eine starke Authentifizierung des Unterzeichners (OTP per SMS standardmäßig, KYC-Video optional) und ein zeitgestempeltes Audit-Log. QES fügt ein qualifiziertes Zertifikat von einem qualifizierten EU-TSP hinzu. Dies alles wird von der API verwaltet — Sie rufen den Endpoint auf, wir kümmern uns um den Rest.

Empfohlene Integrationsarchitektur

Das häufigste Integrationsmuster folgt diesem Ablauf:

  • Ihr Backend ruft POST /v1/envelopes auf, um den Umschlag zu erstellen, und erhält eine sign_url zur Präsentation gegenüber dem Benutzer.
  • Sie leiten den Benutzer zur sign_url um oder betten sie in einen iframe ein (mit Ihrem Branding über den Pro-Plan).
  • Nach Abschluss der Signatur ruft Certyneo Ihren Webhook mit dem Ereignis envelope.completed auf.
  • Sie aktualisieren Ihre Datenbank und benachrichtigen den Benutzer (E-Mail, In-App usw.).

Kostenlose unbegrenzte Sandbox

Die Sandbox-Umgebung ist kostenlos und unbegrenzt. Alle Produktionsfunktionen sind verfügbar, aber Signaturen haben keinen rechtlichen Wert (das PDF ist mit SANDBOX gekennzeichnet). Praktisch für automatisierte Tests, Client-Demos, lokale Entwicklung. Sandbox-Schlüssel unterscheiden sich von Produktionsschlüsseln, vollständige Isolation zwischen beiden.

Migration von DocuSign oder Yousign

Wenn Sie bereits eine DocuSign- oder Yousign-Integration haben, ist das API-Mapping direkt: envelopes → envelopes, recipients → recipients, status webhooks → status webhooks. Unser Migrationsleitfaden dokumentiert die Endpoint-Äquivalenzen Punkt für Punkt. Rechnen Sie mit 1 bis 3 Tagen für eine vollständige Migration, deutlich weniger, wenn Sie einen internen Wrapper verwenden.

Häufig gestellte Fragen — API

Was ist das Rate Limit der API?

1.000 Anfragen pro Minute standardmäßig, auf Anfrage für hohe Nutzung erhöhbar (Fabriken, Multi-Tenant-Plattformen). Der Header X-RateLimit-Remaining bei jeder Antwort zeigt das verbleibende Kontingent an. Bei Überschreitung gibt die API 429 mit einem Retry-After zurück.

Was kostet die API?

Die Sandbox ist kostenlos und unbegrenzt. Produktion läuft auf Pay-per-Signature-Basis (ab 0,40 € pro AES-Signatur mit Staffelrabatt), ohne Mindestabonnement. Der Enterprise-Plan beinhaltet verstärktes SLA, IP-Whitelisting und ein dediziertes technisches Konto.

Gibt es ein SLA?

99,95 % Uptime bei Business- und Enterprise-Plänen (maximale Ausfallzeit von 4 Stunden pro Jahr). Öffentliche Statusseite mit Incident-Verlauf: status.certyneo.com. Der Enterprise-Plan beinhaltet automatische Gutschrift bei SLA-Nichteinhaltung.

Welche Authentifizierung verwenden Sie?

Bearer Token (API-Schlüssel) im Authorization-Header. Schlüssel können vom Dashboard aus rotiert werden, mit sofortiger Widerrufung. Für OAuth-Integrationen (Multi-Tenant-Plattform) bieten wir OAuth 2.0 Client Credentials im Enterprise-Plan an.

Wie überprüfe ich die HMAC-Signatur eines Webhooks?

Jeder Webhook enthält einen X-Certyneo-Signature-Header mit einem HMAC SHA-256 des Payload, signiert mit Ihrem Webhook-Secret. Berechnen Sie auf der Serverseite das HMAC neu und vergleichen Sie es zeitkonstant (Timing-Safe Comparison). Das offizielle SDK macht dies automatisch über webhook.verify(payload, signature, secret).

Sind die SDKs Open Source?

Ja. Die Node-, Python- und Ruby-SDKs befinden sich auf GitHub unter der MIT-Lizenz. Sie können forken, beitragen oder einfach audieren. Binaries werden auf npm, PyPI und RubyGems unter dem Namespace @certyneo / certyneo veröffentlicht.

Kann ich ohne Registrierung testen?

Ja, über die interaktiven Beispiele der API-Dokumentation: /developers/playground. Anfragen laufen gegen eine gemeinsame Sandbox-Instanz, ohne Schlüssel erforderlich. Für ernsthafte Nutzung erstellen Sie ein kostenloses Entwicklerkonto (unbegrenzte Sandbox).

Bereit, elektronische Signaturen zu integrieren?

Kostenlose unbegrenzte Sandbox, vollständige Dokumentation, offizielle SDKs. Jetzt starten.

Dokumentation lesen Mit einem Certyneo-Entwickler sprechen