Intégrez la signature électronique dans votre stack

Démarrage rapide

Trois étapes : créez une clé API depuis les paramètres, encodez votre PDF en base64, envoyez. La réponse contient le `signUrl` que vous pouvez partager directement avec le destinataire.

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

Essayer l'API depuis vos outils

La collection Postman et la fiche RapidAPI sont générées depuis la spécification OpenAPI qui documente aussi cette page. Les trois restent donc alignées sur l'API réelle, endpoint par endpoint, plutôt que de diverger au premier ajout.

Points de terminaison disponibles

12 routes couvrant le cycle complet : enveloppes, documents, webhooks, clés API. Toutes les routes acceptent un Bearer token et renvoient JSON.

Modèles d'enveloppe

Un modèle enregistre une fois pour toutes le PDF, les rôles et l'emplacement des champs de signature, puis se réutilise à chaque envoi : passez son identifiant dans templateId au lieu de documentIds, et les champs positionnés sont recopiés sur l'enveloppe créée.

• • Les modèles se créent depuis le tableau de bord (Modèles → Nouveau modèle), où vous déposez le document puis positionnez les champs à la souris — c'est le chemin le plus simple. L'API permet aussi de les créer par POST /api/v1/templates, en fournissant les documents, les rôles et les champs ; attention, les champs y sont positionnés en coordonnées absolues (page, x, y, largeur, hauteur), il faut donc connaître la mise en page du PDF.
• • Sur un compte qui n'a encore enregistré aucun modèle, GET /api/v1/templates renvoie une liste vide. C'est le comportement normal, pas un défaut d'authentification.
• • La liste ne contient que les modèles appartenant à l'utilisateur propriétaire de la clé API. Un modèle créé par un collègue n'y figure pas, même au sein d'un espace de travail partagé : générez la clé depuis le compte qui possède le modèle.
• • templateId et documentIds s'excluent mutuellement : envoyez l'un ou l'autre, jamais les deux ni aucun des deux.
• • Fournissez au moins autant de destinataires SIGNER que le modèle compte de rôles signataires, sinon la création est refusée en 400. Le champ signerCount renvoyé par la liste indique le nombre attendu.
• • Le niveau de signature du modèle est hérité par l'enveloppe, sauf si la requête passe explicitement 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.

Envoi du document : deux formes acceptées

POST /api/v1/documents accepte le fichier de deux façons, au choix. Les mêmes contrôles s'appliquent dans les deux cas : types autorisés, plafond de 50 Mo, vérification de la signature binaire et analyse antivirus.

• • En multipart/form-data, avec une partie nommée file. C'est la forme classique, celle de curl -F et de la plupart des bibliothèques.
• • En corps brut : les octets du fichier constituent le corps de la requête, et l'en-tête Content-Type en donne le type (application/pdf par exemple). Utile depuis un outil qui transmet le contenu tel quel, sans envelopper la requête — c'est ce que fait le connecteur Power Automate.
• • En corps brut, le nom du fichier n'a pas de place dans le corps : indiquez-le via l'en-tête X-File-Name ou le paramètre ?fileName=. Sans lui, le document est nommé d'après son type.
• • Un type non pris en charge répond 415 en nommant les deux formes acceptées, et un corps annoncé comme multipart mais illisible répond 400. Ni l'un ni l'autre n'est une erreur serveur.

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

Placement des champs de signature

Sans modèle, une enveloppe créée à partir de documentIds n'a aucun champ pré-positionné : le signataire reçoit le document sans emplacement où signer. Le tableau fields, transmis dans le même appel de création, place chaque champ au point près — c'est l'équivalent, côté API, de ce qu'un modèle enregistre une fois pour toutes.

• • Les coordonnées sont en points PDF, origine en haut à gauche de la page et axe Y vers le bas (une page A4 mesure 595 × 842 points). x et y désignent le coin supérieur gauche du champ, width et height sa taille.
• • pageNumber commence à 1, documentIndex commence à 0. Un numéro de page au-delà du document n'est pas rejeté à la création : le champ est ignoré au moment de la signature et n'apparaît nulle part — c'est la première chose à vérifier lorsqu'un champ manque à l'appel.
• • recipientEmail doit correspondre à l'un des destinataires du même appel, sans distinction de casse. Sinon la création échoue en listant toutes les lignes fautives, ce qui évite de les corriger une par une.
• • fields et templateId s'excluent mutuellement : un modèle porte déjà sa propre mise en page. Le tableau fields ne s'utilise donc qu'avec documentIds.
• • Types acceptés : SIGNATURE, INITIALS, DATE_SIGNED, TEXT, CHECKBOX et RADIO_GROUP. required vaut true par défaut ; placeholder et dateFormat sont facultatifs, et options n'est retenu que pour RADIO_GROUP.
• • Une enveloppe accepte au maximum 100 champs, 20 documents et 50 destinataires — les limites de votre plan pouvant être inférieures.

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

Authentification

Chaque appel porte une clé API dans l'en-tête Authorization. Les clés se génèrent depuis Réglages → Clés API et ne sont affichées qu'une seule fois.

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_… en production, sk_test_… pour le bac à sable. En-tête : Authorization: Bearer <clé>.
• • Portées : envelopes, documents, webhooks, seals — en lecture (:read) ou écriture (:write). L'écriture implique la lecture ; la portée * donne tous les droits.
• • Les clés sk_test_ créent des ressources en bac à sable, exclues du quota et de la facturation.
• • Erreurs : 401 clé invalide, 403 portée insuffisante, 429 limite de débit dépassée, 402 quota mensuel atteint.

Forme des réponses

Un point à connaître avant d'écrire votre client : les collections sont encapsulées dans un objet data, alors que les ressources unitaires sont renvoyées à plat. Lire response.data.data sur une ressource unitaire renvoie donc 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": [ /* … */ ]
}