Integrieren Sie elektronische Signaturen in Ihren Tech-Stack

Schnelleinstieg

Drei Schritte: Erstellen Sie einen API-Schlüssel in den Einstellungen, kodieren Sie Ihr PDF in Base64, senden Sie es ab. Die Antwort enthält die `signUrl`, die Sie direkt mit dem Empfänger teilen können.

# 1. Upload the PDF (multipart) and capture the returned document id.
DOC_ID=$(curl -s -X POST https://certyneo.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@contrat.pdf" | jq -r .id)

# 2. Create a DRAFT envelope referencing the uploaded document.
ENV_ID=$(curl -s -X POST https://certyneo.com/api/v1/envelopes \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d "{
    \"subject\": \"Contrat de prestation\",
    \"documentIds\": [\"$DOC_ID\"],
    \"recipients\": [
      { \"email\": \"client@example.com\", \"name\": \"Marie Dubois\", \"role\": \"SIGNER\" }
    ]
  }" | jq -r .id)

# 3. Dispatch the envelope — this sends the invitation email/SMS.
curl -X POST https://certyneo.com/api/v1/envelopes/$ENV_ID/send \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

// Plain fetch, no SDK to install.
const auth = { Authorization: `Bearer ${process.env.CERTYNEO_API_KEY}` };

// 1. Upload the PDF (multipart).
const fd = new FormData();
fd.append("file", new Blob([pdfBuffer], { type: "application/pdf" }), "contrat.pdf");
const doc = await fetch("https://certyneo.com/api/v1/documents", {
  method: "POST", headers: auth, body: fd,
}).then((r) => r.json());

// 2. Create the DRAFT envelope.
const envelope = await fetch("https://certyneo.com/api/v1/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: "Marie Dubois", role: "SIGNER" },
    ],
  }),
}).then((r) => r.json());

// 3. Dispatch — this triggers the invitation channel for every recipient.
await fetch(`https://certyneo.com/api/v1/envelopes/${envelope.id}/send`, {
  method: "POST", headers: auth,
});
console.log(envelope.id);

import os, requests

auth = {"Authorization": f"Bearer {os.environ['CERTYNEO_API_KEY']}"}

# 1. Upload the PDF (multipart).
with open("contrat.pdf", "rb") as f:
    doc = requests.post(
        "https://certyneo.com/api/v1/documents",
        headers=auth,
        files={"file": ("contrat.pdf", f, "application/pdf")},
    ).json()

# 2. Create the DRAFT envelope.
envelope = requests.post(
    "https://certyneo.com/api/v1/envelopes",
    headers={**auth, "Content-Type": "application/json"},
    json={
        "subject": "Contrat de prestation",
        "documentIds": [doc["id"]],
        "recipients": [
            {"email": "client@example.com", "name": "Marie Dubois", "role": "SIGNER"},
        ],
    },
).json()

# 3. Dispatch — this triggers the invitation channel for every recipient.
requests.post(
    f"https://certyneo.com/api/v1/envelopes/{envelope['id']}/send",
    headers=auth,
)
print(envelope["id"])

API von Ihren Tools aus ausprobieren

Die Postman-Sammlung und das RapidAPI-Blatt werden aus der OpenAPI-Spezifikation generiert, die diese Seite ebenfalls dokumentiert. Alle drei bleiben also auf die echte API abgestimmt, Endpoint für Endpoint, anstatt bei der ersten Erweiterung abzuweichen.

Postman-Sammlung

Die 25 Anfragen, nach Domäne sortiert – Umschläge, Dokumente, Vorlagen, Siegel, Webhooks – mit Beispiel-Text und Antwort für jede. Fügen Sie Ihren Schlüssel in die Variable apiKey der Sammlung ein und führen Sie GET /health aus: Dies erfordert keine Authentifizierung und bestätigt, dass Ihre Konfiguration vor dem ersten authentifizierten Aufruf korrekt ist.

In Postman öffnen

RapidAPI-Blatt

Der gleiche Endpoint-Katalog, direkt im Browser ausprobierbar. Der Teststand erwartet zwei unterschiedliche Header: den RapidAPI-Schlüssel, den Ihnen die Plattform zuweist, und Ihren Certyneo-Schlüssel in Authorization – der zweite autorisiert den Aufruf tatsächlich.

Auf RapidAPI anzeigen

Verfügbare Endpoints

Die 52 öffentlichen Routen: Konto, Dokumente, Umschläge, Vorlagen, Webhooks, elektronische Siegel, API-Schlüssel und Abrechnung. Alle akzeptieren ein Bearer-Token und geben JSON zurück.

Umschlagvorlagen

Eine Vorlage speichert einmalig das PDF, die Rollen und die Position der Signaturfelder und wird dann bei jedem Versand wiederverwendet: Übergeben Sie deren Identifikator in templateId statt in documentIds, und die positionierten Felder werden in den erstellten Umschlag kopiert.

• • Vorlagen werden über das Dashboard erstellt (Vorlagen → Neue Vorlage), wo Sie das Dokument hochladen und die Felder mit der Maus positionieren – das ist der einfachste Weg. Die API ermöglicht es auch, sie per POST /api/v1/templates zu erstellen, indem Dokumente, Rollen und Felder bereitgestellt werden; beachten Sie, dass Felder dort in absoluten Koordinaten positioniert werden (Seite, x, y, Breite, Höhe), daher müssen Sie das Layout des PDF kennen.
• • Auf einem Konto, das noch keine Vorlage gespeichert hat, gibt GET /api/v1/templates eine leere Liste zurück. Das ist das normale Verhalten, kein Authentifizierungsfehler.
• • Die Liste enthält nur Vorlagen, die dem Benutzer gehören, dem der API-Schlüssel gehört. Eine von einem Kollegen erstellte Vorlage wird nicht angezeigt, auch nicht in einem gemeinsamen Arbeitsbereich: Generieren Sie den Schlüssel über das Konto, das die Vorlage besitzt.
• • templateId und documentIds schließen sich gegenseitig aus: Senden Sie das eine oder das andere, niemals beide oder keines von beiden.
• • Geben Sie mindestens so viele SIGNER-Empfänger an, wie die Vorlage Unterzeichner-Rollen hat, sonst wird die Erstellung mit 400 abgelehnt. Das von der Liste zurückgegebene Feld signerCount gibt die erwartete Anzahl an.
• • Die Signierungsstufe der Vorlage wird vom Umschlag geerbt, es sei denn, die Anfrage übergibt explizit signatureLevel.

# 1. Discover the templates saved on this account.
curl -s https://certyneo.com/api/v1/templates \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

# {
#   "data": [
#     { "id": "cmdq7f4k80001s6y2h1xa9pl3", "name": "Contrat de prestation",
#       "signerCount": 2, "documentCount": 1, "signatureLevel": "SIMPLE" }
#   ],
#   "pagination": { "page": 1, "pageSize": 20, "total": 1, "pages": 1 }
# }
#
# An empty "data" array means no template exists on this account yet —
# create one from the dashboard, it is not an authentication problem.

# 2. Create the envelope FROM the template: no documentIds and no field
#    coordinates, both are carried by the template. Pass one SIGNER
#    recipient per signer role, in the template's role order.
curl -X POST https://certyneo.com/api/v1/envelopes \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Contrat de prestation",
    "templateId": "cmdq7f4k80001s6y2h1xa9pl3",
    "recipients": [
      { "email": "client@example.com", "name": "Marie Dubois", "role": "SIGNER" },
      { "email": "legal@example.com", "name": "Paul Martin", "role": "SIGNER" }
    ]
  }'

# 3. The envelope is DRAFT at this point — POST /envelopes/{id}/send
#    dispatches it, exactly as in the quick-start above.

Dokumentversand: zwei akzeptierte Formen

POST /api/v1/documents akzeptiert die Datei auf zwei Arten, zur Wahl. Die gleichen Kontrollen gelten in beiden Fällen: zulässige Typen, Obergrenze von 50 Mo, Überprüfung der binären Signatur und Antivirenscan.

• • In multipart/form-data mit einem Teil namens file. Dies ist die klassische Form, die von curl -F und den meisten Bibliotheken verwendet wird.
• • Im unformatiert körper: die Bytes der Datei bilden den Anforderungstext, und der Header Content-Type gibt ihren Typ an (z.B. application/pdf). Nützlich von einem Tool, das den Inhalt wie er ist übermittelt, ohne die Anfrage zu verpacken — dies ist das, was der Power Automate-Konnektor tut.
• • Im unformatiert körper hat der Dateiname keinen Platz im Text: geben Sie ihn über den Header X-File-Name oder den Parameter ?fileName= an. Ohne ihn wird das Dokument nach seinem Typ benannt.
• • Ein nicht unterstützter Typ antwortet mit 415 und nennt die beiden akzeptierten Formen, und ein als multipart angekündigter aber unlesbarer Text antwortet mit 400. Keines von beiden ist ein Serverfehler.

# a. multipart/form-data — the classic shape.
curl -X POST https://certyneo.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@contrat.pdf;type=application/pdf"

# b. raw body — the file bytes ARE the body, typed by Content-Type.
#    The filename has nowhere to live in the body, so pass it as a header
#    (or ?fileName=). Without it the document is named after its type.
curl -X POST https://certyneo.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/pdf" \
  -H "X-File-Name: contrat.pdf" \
  --data-binary "@contrat.pdf"

# Both return the same 201 with the document id to pass as documentIds.

Platzierung der Signaturfelder

Ohne Vorlage hat ein Umschlag, der aus documentIds erstellt wird, kein vordefiniertes Feld: Der Unterzeichner erhält das Dokument ohne Unterschriftsort. Das Feld fields, das im selben Erstellungsaufruf übertragen wird, platziert jedes Feld auf den Punkt genau – es ist das API-Äquivalent dessen, was eine Vorlage ein für alle Mal speichert.

• • Die Koordinaten werden in PDF-Punkten angegeben, der Ursprung befindet sich oben links auf der Seite und die Y-Achse zeigt nach unten (eine A4-Seite misst 595 × 842 Punkte). x und y bezeichnen die obere linke Ecke des Feldes, width und height seine Größe.
• • pageNumber beginnt bei 1, documentIndex bei 0. Eine Seitennummer außerhalb des Dokuments wird bei der Erstellung nicht abgelehnt: das Feld wird zum Zeitpunkt der Unterzeichnung ignoriert und erscheint nirgendwo — das ist das Erste, das überprüft werden muss, wenn ein Feld beim Aufruf fehlt.
• • recipientEmail muss einem der Empfänger des gleichen Aufrufs entsprechen, ohne Berücksichtigung der Groß- und Kleinschreibung. Andernfalls schlägt die Erstellung fehl und listet alle fehlerhaften Zeilen auf, was vermeidet, sie einzeln zu korrigieren.
• • fields und templateId schließen sich gegenseitig aus: eine Vorlage bringt bereits ihr eigenes Layout mit sich. Das Array fields wird daher nur mit documentIds verwendet.
• • Akzeptierte Typen: SIGNATURE, INITIALS, DATE_SIGNED, TEXT, CHECKBOX und RADIO_GROUP. required ist standardmäßig wahr; placeholder und dateFormat sind optional, und options wird nur für RADIO_GROUP berücksichtigt.
• • Eine Umschlag akzeptiert maximal 100 Felder, 20 Dokumente und 50 Empfänger — die Limits Ihres Plans können niedriger sein.

# Ad-hoc envelope WITH pre-placed fields — no template involved.
# Coordinates are PDF points, origin TOP-LEFT of the page, +Y downwards
# (A4 = 595 x 842 pt). x / y are the field box's top-left corner.
#
# The last field is positioned by ANCHOR instead of by eye: the server
# locates "Signature du client" in the PDF and computes the spot. x / y
# stay required there — they are the fallback if the text is not found.
curl -X POST https://certyneo.com/api/v1/envelopes \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Contrat de prestation",
    "documentIds": ["cmdq7f4k80001s6y2h1xa9pl3"],
    "recipients": [
      { "email": "client@example.com", "name": "Marie Dubois", "role": "SIGNER" }
    ],
    "fields": [
      { "recipientEmail": "client@example.com", "documentIndex": 0,
        "pageNumber": 2, "fieldType": "SIGNATURE",
        "x": 90, "y": 640, "width": 180, "height": 44 },
      { "recipientEmail": "client@example.com", "documentIndex": 0,
        "pageNumber": 2, "fieldType": "DATE_SIGNED",
        "x": 320, "y": 640, "width": 140, "height": 30,
        "dateFormat": "DD/MM/YYYY" },
      { "recipientEmail": "client@example.com", "documentIndex": 0,
        "pageNumber": 2, "fieldType": "TEXT",
        "x": 90, "y": 700, "width": 200, "height": 30,
        "placeholder": "Fonction", "required": false },
      { "recipientEmail": "client@example.com", "documentIndex": 0,
        "pageNumber": 2, "fieldType": "SIGNATURE",
        "anchorText": "Signature du client", "anchorPlacement": "below",
        "anchorIndex": 0,
        "x": 90, "y": 640, "width": 180, "height": 44 }
    ]
  }'

# The envelope is DRAFT at this point — POST /envelopes/{id}/send
# dispatches it, exactly as in the quick-start above.

Integrierte Signatur: Unterschreiben, ohne Ihre Anwendung zu verlassen

Ihr Kunde konsultiert und unterzeichnet sein Dokument über Ihre eigene Schnittstelle. Die Zeremonie wird in einem Fenster über Ihrer Seite geöffnet, und er kehrt nach Abschluss automatisch zu Ihnen zurück. Auf der Serverseite gibt es nichts Neues: Sie erstellen den Umschlag wie gewohnt, indem Sie redirectUrl angeben, und übergeben dann dem SDK die Signatur-URL des Empfängers.

• • Rufen Sie Certyneo.sign() direkt in Ihrem Klick-Handler auf und übergeben Sie Ihren Serveraufruf über getUrl. Ein await vor sign() beendet die Benutzergeste: Safari und Firefox blockieren dann das Fenster. Das SDK öffnet es sofort und lädt es, wenn sich Ihr Promise auflöst.
• • redirectUrl ist der Rückgabekanal. Wir leiten den Unterzeichner dorthin weiter und fügen certyneo_status (completed oder declined) und certyneo_envelope hinzu. Laden Sie dasselbe Skript auf diese Rückgabenseite: Es teilt dem Portal-Fenster mit, das offen im Hintergrund geblieben ist.
• • Im integrierten Modus werden unsere eigenen Call-to-Action-Elemente unterdrückt. Ihr Kunde sieht niemals eine Aufforderung, ein Certyneo-Konto zu erstellen.
• • Falls der Browser das Fenster ablehnt, wechselt das SDK automatisch zur vollständigen Seitenumleitung. Der Ablauf ist für den Unterzeichner identisch, und Ihre Rückgabenseite erhält exakt dieselben Parameter.
• • Es gibt absichtlich keinen Rückruf "der Benutzer hat abgebrochen": Der Fensterzustand ist von Ihrer Seite aus nicht lesbar, und ein solcher Rückruf würde fälschlicherweise ausgelöst. Eine Signatur, die nicht ankommt, bleibt bis zum Webhook ausstehend.

// 1. Your server creates and sends the envelope, then hands the browser the
//    recipient's signing URL. Nothing new on the API side:
//      POST /api/v1/envelopes        { …, "redirectUrl": "https://your-app.com/quote/42/signed" }
//      POST /api/v1/envelopes/{id}/send   → recipients[].accessToken
//      signingUrl = "https://certyneo.com/sign/" + accessToken

// 2. On your quote page — load the SDK once:
//      <script src="https://certyneo.com/embed.js"></script>

document.querySelector("#sign").addEventListener("click", () => {
  Certyneo.sign({
    // Called AFTER the window is already open, so no popup blocker ever
    // sees a delay between the click and window.open.
    getUrl: () =>
      fetch("/api/quote/42/signature", { method: "POST" })
        .then((r) => r.json())
        .then((d) => d.signingUrl),

    onCompleted: (e) => showConfirmation(e.envelopeId),
    onDeclined: () => showDeclined(),
    onError: (e) => showError(e),
  });
});

// 3. On https://your-app.com/quote/42/signed — your return page — load the
//    same script and render a short confirmation. It relays the outcome to
//    the portal window behind it, then closes itself.

// Mode cadre : la cérémonie s'affiche DANS votre page.
//
// 1. Déclarez votre site une fois pour toutes dans Réglages → Signature
//    intégrée, et publiez l'enregistrement DNS qu'on vous y donne.
//
// 2. À chaque signature, votre serveur demande une URL fraîche. Elle porte
//    l'autorisation qui permet au navigateur d'afficher la cérémonie chez
//    vous, et vaut deux heures :
//
//      POST /api/v1/envelopes/{id}/embed-url
//      { "origin": "https://portail.exemple.fr" }
//      -> { "signingUrl": "…", "expiresAt": "…" }

Certyneo.sign({
  mode: "iframe",
  el: "#zone-signature",        // sélecteur ou nœud de votre page

  getUrl: () =>
    fetch("/api/devis/42/signature", { method: "POST" })
      .then((r) => r.json())
      .then((d) => d.signingUrl),

  onCompleted: (e) => afficherConfirmation(e.envelopeId),
  onDeclined: () => afficherRefus(),
});

// Le cadre parle à votre page par postMessage — pas besoin de page de retour,
// contrairement au mode fenêtre.

POST /api/v1/envelopes

{
  "subject": "Mandat de gestion",
  "documentIds": ["doc_8f2c1a4b9e7d"],
  "recipients": [
    {
      "email": "client@exemple.fr",
      "name": "Camille Client",
      "role": "SIGNER",
      "notificationChannel": "NONE"
    },
    {
      "email": "notaire@exemple.fr",
      "name": "Maître Notaire",
      "role": "SIGNER"
    }
  ]
}

// La réponse rend le lien de chaque signataire :
//
//   "recipients": [
//     { "email": "client@exemple.fr",  "accessToken": "…",
//       "notificationChannel": "NONE"  },
//     { "email": "notaire@exemple.fr", "accessToken": "…",
//       "notificationChannel": "EMAIL" }
//   ]
//
// Le client ne reçoit rien : vous l'emmenez sur sa signature depuis votre
// portail. Le notaire, lui, reçoit son invitation comme d'habitude.

POST /api/v1/envelopes

{
  "subject": "Devis 2026-118",
  "documentIds": ["doc_8f2c1a4b9e7d"],
  "recipients": [
    { "email": "client@exemple.fr", "name": "Camille Client", "role": "SIGNER" }
  ],
  "sender": {
    "name": "1.2.3. Panneaux Solaires",
    "email": "devis@123-panneaux-solaires.fr"
  }
}

Authentifizierung

Jeder Aufruf trägt einen API-Schlüssel im Authorization-Header. Schlüssel werden über Einstellungen → API-Schlüssel generiert und nur einmal angezeigt.

GET /api/v1/account/me HTTP/1.1Host: certyneo.com
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

# 200 OK
{ "data": { "id": "usr_…", "email": "you@example.com", "plan": "BUSINESS", "environment": "live" } }

• • Format: sk_live_… in der Produktion, sk_test_… für die Sandbox. Header: Authorization: Bearer <Schlüssel>.
• • Bereiche: envelopes, documents, webhooks, seals — im Lese- (:read) oder Schreibmodus (:write). Schreiben impliziert Lesen; der Bereich * gewährt alle Rechte.
• • sk_test_-Schlüssel erstellen Ressourcen in der Sandbox, ausgeschlossen von Kontingent und Abrechnung. Es wird keine echte E-Mail an den Empfänger gesendet, es sei denn, dessen Adresse stimmt mit der E-Mail-Adresse des sendenden Kontos überein – nützlich, um den gesamten Ablauf an sich selbst zu testen.
• • Fehler: 401 ungültiger Schlüssel, 403 unzureichender Bereich, 429 Ratengrenze überschritten, 402 monatliches Kontingent erreicht.

Form der Antworten

Ein wichtiger Punkt vor dem Schreiben Ihres Clients: Sammlungen sind in einem data-Objekt gekapselt, während einzelne Ressourcen flach zurückgegeben werden. Das Lesen von response.data.data auf einer einzelnen Ressource gibt daher undefined zurück.

// GET /api/v1/envelopes
// Collections are WRAPPED in a "data" array.
{
  "data": [
    { "id": "env_abc123", "subject": "Contrat", "status": "SENT" }
  ]
}

// GET /api/v1/envelopes/{id}
// Single resources are returned FLAT — no "data" envelope.
{
  "id": "env_abc123",
  "subject": "Contrat",
  "status": "COMPLETED",
  "recipients": [ /* … */ ]
}

Weiter gehen

• API für elektronische Signatur: Preise und Dokumentation
• Native Integrationen (HubSpot, Zapier, Make, Power Automate…)
• Massenhafter Versand von Dokumenten zum Signieren, ohne Code
• Entdecken Sie die elektronische Signaturdösung Certyneo