Integrieren Sie elektronische Signaturen in Ihren Stack

Schnelleinstieg

Drei Schritte: Erstellen Sie einen API-Schlüssel in den Einstellungen, kodieren Sie Ihr PDF in Base64, versenden Sie es. 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"

// npm install @certyneo/sdk  (or call fetch directly)
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.

Verfügbare Endpoints

12 Routen für den kompletten Zyklus: Enveloppen, Dokumente, Webhooks, API-Schlüssel. Alle Routen akzeptieren einen 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.

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.
• • 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": [ /* … */ ]
}