Integreer elektronische handtekeningen in uw stack

Drie stappen: maak een API-sleutel aan via instellingen, codeer uw PDF in base64, verzend. Het antwoord bevat de `signUrl` die u direct met de ontvanger kunt delen.

Enveloppen

# 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"])

De API vanuit uw tools uitproberen

De Postman-collectie en RapidAPI-kaart worden gegenereerd op basis van de OpenAPI-specificatie die ook deze pagina documenteert. De drie blijven dus aligned met de echte API, endpoint voor endpoint, in plaats van uit elkaar te groeien bij de eerste toevoeging.

Postman-collectie

De 25 verzoeken ingedeeld per domein — enveloppen, documenten, sjablonen, zegels, webhooks — met een voorbeeld van de body en het antwoord voor elk. Plak uw sleutel in de variabele apiKey van de collectie, en voer vervolgens GET /health uit: deze vereist geen authenticatie en bevestigt dat uw configuratie correct is voordat de eerste geverifieerde oproep wordt gedaan.

Openen in Postman

RapidAPI-blad

Dezelfde catalogus van eindpunten, rechtstreeks vanuit de browser te testen. De testbank verwacht twee verschillende headers: de RapidAPI-sleutel die het platform u toewijst, en uw Certyneo-sleutel in Authorization — de tweede autoriseerder daadwerkelijk de oproep.

Bekijken op RapidAPI

12 routes die de volledige cyclus dekken: enveloppen, documenten, webhooks, API-sleutels. Alle routes accepteren een Bearer token en retourneren JSON.

De 52 openbare routes: account, documenten, enveloppen, sjablonen, webhooks, elektronische zegels, API-sleutels en facturering. Allemaal accepteren een Bearer-token en retourneren JSON.

Enveloppesjablonen

Een sjabloon registreert eenmaal voor altijd de PDF, de rollen en de locatie van ondertekenningsvelden, en wordt vervolgens bij elke verzending hergebruikt: geef de bijbehorende identificatie in templateId door in plaats van documentIds, en de gepositioneerde velden worden naar de gemaakte enveloppe gekopieerd.

• • Sjablonen worden gemaakt via het dashboard (Sjablonen → Nieuw sjabloon), waar u het document uploadt en vervolgens de velden met de muis positioneert — dit is het eenvoudigste pad. De API maakt het ook mogelijk deze via POST /api/v1/templates aan te maken door de documenten, rollen en velden op te geven; let op, velden worden hier met absolute coördinaten gepositioneerd (pagina, x, y, breedte, hoogte), dus u moet de opmaak van de PDF kennen.
• • Op een account dat nog geen sjabloon heeft opgeslagen, retourneert GET /api/v1/templates een lege lijst. Dit is het normale gedrag, geen authenticatieprobleem.
• • De lijst bevat alleen sjablonen die eigendom zijn van de gebruiker die de API-sleutel bezit. Een sjabloon gemaakt door een collega staat daar niet in, zelfs niet binnen een gedeelde werkruimte: genereer de sleutel vanuit het account dat eigenaar is van het sjabloon.
• • templateId en documentIds sluiten elkaar uit: verzend het ene of het ander, nooit beide en nooit geen van beide.
• • Geef minstens zoveel SIGNER-ontvangers op als het sjabloon ondertekeningsrollen heeft, anders wordt het aanmaken in 400 geweigerd. Het veld signerCount dat door de lijst wordt geretourneerd geeft het verwachte aantal aan.
• • Het ondertekeniningsniveau van het sjabloon wordt door de enveloppe overgenomen, tenzij het verzoek expliciet signatureLevel doorgeeft.

# 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.

Documentverzending: twee geaccepteerde vormen

POST /api/v1/documents accepteert het bestand op twee manieren, naar keuze. In beide gevallen gelden dezelfde controles: toegestane typen, limiet van 50 MB, binaire handtekeningverificatie en antivirusscan.

• • In multipart/form-data, met een onderdeel met de naam file. Dit is de klassieke vorm, die van curl -F en van de meeste bibliotheken.
• • In onbewerkte body: de bytes van het bestand vormen de body van de verzoek, en de header Content-Type geeft het type aan (bijvoorbeeld application/pdf). Nuttig van een tool die de inhoud ongewijzigd doorgeeft, zonder het verzoek in te pakken — dit is wat de Power Automate-connector doet.
• • In onbewerkte body heeft de bestandsnaam geen plaats in de body: geef het op via de header X-File-Name of de parameter ?fileName=. Zonder het wordt het document genoemd naar het type.
• • Een niet-ondersteund type reageert 415 met vermelding van de twee geaccepteerde vormen, en een body die als multipart wordt aangekondigd maar onleesbaar is, reageert 400. Geen van beide is een serverfout.

# 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.

Plaatsing van ondertekenningsvelden

Zonder sjabloon heeft een enveloppe gemaakt van documentIds geen vooraf gepositioneerde velden: de ondertekenaar ontvangt het document zonder plaats om te ondertekenen. De tabel fields, in dezelfde aanroep doorgegeven, positioneert elk veld tot op het puntje nauwkeurig — dit is het equivalent aan API-zijde van wat een sjabloon eenmaal voor altijd opslaat.

• • De coördinaten zijn in PDF-punten, oorsprong in de linkerbovenhoek van de pagina en Y-as naar beneden (een A4-pagina is 595 × 842 punten groot). x en y geven de linkerbovenhoek van het veld aan, width en height zijn de grootte.
• • pageNumber begint op 1, documentIndex begint op 0. Een paginanummer buiten het document wordt niet bij aanmaak geweigerd: het veld wordt genegeerd op het moment van ondertekening en verschijnt nergens — dit is het eerste wat u moet controleren wanneer een veld niet wordt gevonden.
• • recipientEmail moet overeenkomen met een van de ontvangers in dezelfde aanroep, zonder onderscheid naar hoofdletters. Anders mislukt het aanmaken en worden alle foutieve rijen vermeld, wat het corrigeren ervan één voor één voorkomt.
• • fields en templateId sluiten elkaar uit: een sjabloon bevat al zijn eigen opmaak. De tabel fields wordt dus alleen gebruikt met documentIds.
• • Geaccepteerde typen: SIGNATURE, INITIALS, DATE_SIGNED, TEXT, CHECKBOX en RADIO_GROUP. required is standaard true; placeholder en dateFormat zijn optioneel, en options wordt alleen gebruikt voor RADIO_GROUP.
• • Een enveloppe accepteert maximaal 100 velden, 20 documenten en 50 ontvangers — de limieten van uw plan kunnen lager zijn.

# 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.

Geïntegreerde handtekening: ondertekenen zonder uw toepassing te verlaten

Uw klant raadpleegt en ondertekent zijn document vanuit uw eigen interface. De ceremonie opent zich in een venster boven uw pagina en hij keert automatisch bij u terug zodra deze is voltooid. Aan serverzijde niets nieuws: u maakt de envelop zoals gewoonlijk aan door redirectUrl in te vullen en vertrouwt het SDK de handtekening-URL van de ontvanger toe.

• • Roep Certyneo.sign() rechtstreeks in uw klikhandler aan en geef uw serveroproep door via getUrl. Een await vóór sign() treedt uit de gebruikersgebaar: Safari en Firefox blokkeren dan het venster. Het SDK opent het onmiddellijk en laadt het wanneer uw belofte wordt opgelost.
• • redirectUrl is het retourkanaal. We sturen de ondertekenaar daarheen terug door certyneo_status (completed of declined) en certyneo_envelope toe te voegen. Laad hetzelfde script op deze retourpagina: dit is het dat het portalvenster dat achter is gebleven in kennis stelt.
• • In embedded mode zijn onze eigen call-to-action-elementen verborgen. Uw klant ziet nooit een uitnodiging om een Certyneo-account aan te maken.
• • Als de browser het venster weigert, schakelt de SDK automatisch over naar volledige paginaredirectie. Het parcours is identiek voor de ondertekenaar en uw retourpagina ontvangt exact dezelfde parameters.
• • Er bestaat opzettelijk geen callback "de gebruiker heeft het verlaten": de status van het venster is niet leesbaar vanaf uw pagina, en zo'n callback zou ten onrechte worden geactiveerd. Een handtekening die niet wordt voltooid, blijft in behandeling totdat de webhook wordt ontvangen.

// 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"
  }
}

Authenticatie

Elk verzoek bevat een API-sleutel in de Authorization-header. Sleutels worden gegenereerd via Instellingen → API-sleutels en worden slechts eenmaal weergegeven.

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" } }

• • Formaat: sk_live_… in productie, sk_test_… voor de sandbox. Header: Authorization: Bearer <clé>.
• • Bereiken: envelopes, documents, webhooks, seals — in leesmodus (:read) of schrijfmodus (:write). Schrijven impliceert lezen; het bereik * geeft alle rechten.
• • sk_test_-sleutels maken resources in de sandbox aan, uitgesloten van quota en facturering. Er wordt geen echte e-mail naar de ontvanger verstuurd, tenzij het adres overeenkomt met het e-mailadres van het verzendende account — handig om de volledige flow op uzelf te testen.
• • Fouten: 401 ongeldige sleutel, 403 onvoldoende bereik, 429 snelheidslimiet overschreden, 402 maandelijks quota bereikt.

Vorm van antwoorden

Een belangrijk punt voordat u uw client schrijft: collecties zijn ingekapseld in een data-object, terwijl individuele resources volledig worden geretourneerd. Het lezen van response.data.data op een individuele resource retourneert dus undefined.

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

Verder gaan

• API voor elektronische handtekeningen: prijzen en documentatie
• Native integraties (HubSpot, Zapier, Make, Power Automate…)
• Massaal verzenden van documenten ter ondertekening, zonder code
• Ontdek de elektronische handtekeningoplossing van Certyneo