Integrálja az elektronikus aláírást a stackbe

Gyors kezdés

Három lépés: hozzon létre egy API kulcsot a beállításokból, kódolja a PDF-et base64-be, küldje el. A válasz tartalmazza a `signUrl`-t, amelyet közvetlenül megoszthat a címzettel.

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

Próbálja ki az API-t az Ön eszközeivel

A Postman-gyűjtemény és a RapidAPI-kártya az OpenAPI-specifikációból jönnek létre, amely ezt az oldalt is dokumentálja. A három tehát az API valódi végpontokkal marad igazodva, végpont végponttal, ahelyett, hogy az első hozzáadáskor eltérne.

Postman-gyűjtemény

A 25 kérés tartomány szerint rendezve — borítékok, dokumentumok, sablonok, pecsételés, webhookok — mindegyik esetében egy kéréstest és válaszpéldával. Illessze be az API-kulcsát a gyűjtemény apiKey változójába, majd futtassa a GET /health parancsot: nem igényel hitelesítést, és megerősíti, hogy a konfigurációja jó az első hitelesített hívás előtt.

Megnyitás a Postmanban

RapidAPI-kártya

Ugyanez a végpont-katalógus, közvetlenül a böngészőből kipróbálható. A tesztelési terület két különálló fejlécet vár: a RapidAPI-kulcsot, amelyet az Ön számára a platform rendel, és a Certyneo-kulcsot az Engedélyezésben — ez a második valóban hitelesíti a hívást.

Nézze meg a RapidAPI-n

Elérhető végpontok

A 53 nyilvános útvonal: fiók, dokumentumok, borítékok, sablonok, webhookok, elektronikus pecsételés, API-kulcsok és számlázás. Mindegyik elfogad Bearer tokent és JSON-t ad vissza.

Képzeletek zárolatok

A sablon egyszer és véglegesen rögzíti a PDF-et, a szerepeket és az aláírási mező helyét, majd minden elküldetéskor újra felhasználható: adja meg az azonosítóját a `templateId`-ben a `documentIds` helyett, és a pozicionált mezők az elkészült borítékra másolódnak.

• • A sablonok az irányítópultról hozhatók létre (Sablonok → Új sablon), ahol feltölt a dokumentum, majd az egeret használva pozícionálja a mezőket — ez a legegyszerűbb út. Az API a POST /api/v1/templates-en keresztül is létrehozhatja őket, dokumentumok, szerepek és mezők biztosítása után; vigyázat, a mezők abszolút koordinátákban helyezkednek el (lap, x, y, szélesség, magasság), tehát ismerni kell a PDF elrendezését.
• • Egy olyan fiók esetén, amely még nem rögzített sablont, a GET /api/v1/templates üres listát ad vissza. Ez a normális viselkedés, nem hitelesítési hiba.
• • A lista csak az API-kulcsot tulajdonló felhasználó tulajdonában lévő sablonokat tartalmazza. A kolléga által létrehozott sablon nem jelenik meg, még egy megosztott munkaterületen belül sem: az API-kulcsot az a fiók alapján generálja, amely a sablont possui.
• • A `templateId` és a `documentIds` kölcsönösen kizárják egymást: az egyiket vagy a másikat küldje el, soha mindkettőt vagy egyiket sem.
• • Legalább annyi SIGNER destinátáriust biztosítson, ahány aláírási szereppel rendelkezik a sablon, különben a létrehozás 400-as elutasítással kerül lejátszásra. A lista által visszaadott `signerCount` mező az elvárt számot adja meg.
• • A sablon aláírási szintje a boríték által öröklődik, kivéve, ha a kérés kifejezetten a `signatureLevel` értéket adja meg.

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

Dokumentum küldése: két elfogadott forma

A POST /api/v1/documents két módon fogadja a fájlt, szabadon választva. Mindkét esetben ugyanazok a kontrollok érvényesek: engedélyezett típusok, 50 MB-os korlát, bináris aláírás ellenőrzése és víruskeresés.

• • Multipart/form-data formátumban, egy file nevű résszel. Ez a klasszikus forma, a curl -F és a legtöbb könyvtár formája.
• • Nyers testben: a fájl bájtjai a kérés testét képezik, és a Content-Type fejléc a típusát adja meg (például application/pdf). Hasznos egy olyan eszközből, amely a tartalmat olyan, ahogyan van, továbbítja, anélkül, hogy a kérést burkolná — ezt teszi a Power Automate összekötő.
• • Nyers testben a fájlnév nem tartozik a testbe: adja meg az X-File-Name fejlécen vagy a ?fileName= paraméteren keresztül. Nélküle a dokumentum típusa alapján lesz elnevezve.
• • A nem támogatott típus 415-öt ad vissza, megnevezve a két elfogadott formát, és egy multipart-ként bejelentett, de olvashatatlan test 400-at ad vissza. Egyik sem szerver hiba.

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

Csomagolás a aláírás mezőknek

Sablon nélkül, a documentIds alapján létrehozott boríték nem rendelkezik előzetesen elhelyezett mezőkkel: az aláíró a dokumentumot aláírási helyek nélkül kapja meg. A fields tömb, amelyet ugyanabban a létrehozási hívásban adunk át, minden mezőt pontosan elhelyez — ez az API oldaláról az egyenértéke annak, amit egy sablon egyszer és mindenkorra rögzít.

• • A koordináták PDF pontok, az origó az oldal bal felső sarkában, az Y tengely lefelé mutat (egy A4-es oldal 595 × 842 pont). Az x és y a mező bal felső sarkát, a width és height annak méretét jelöli.
• • A pageNumber 1-ből kezdődik, a documentIndex 0-ból. Egy dokumentumon túli oldalszám nem kerül elutasításra a létrehozás során: a mező az aláírás időpontjában figyelmen kívül marad és sehol nem jelenik meg — ez az első dolog, amit ellenőrizni kell, ha egy mező hiányzik a hívásból.
• • A recipientEmail meg kell, hogy egyezzen az ugyanabban a hívásban szereplő egyik címzetttel, kis- és nagybetűkre való tekintet nélkül. Ellenkező esetben a létrehozás meghiúsul az összes hibás sor felsorolásával, így nem kell egyenként javítani őket.
• • A fields és templateId kölcsönösen kizárják egymást: egy sablon már rendelkezik saját elrendezésével. A fields tömb ezért csak documentIds-vel használható.
• • Elfogadott típusok: SIGNATURE, INITIALS, DATE_SIGNED, TEXT, CHECKBOX és RADIO_GROUP. A required alapértelmezett értéke true; a placeholder és dateFormat opcionálisak, és az options csak a RADIO_GROUP esetén vesz fel értéket.
• • Egy boríték legfeljebb 100 mezőt, 20 dokumentumot és 50 címzettet fogad el — az Ön csomagjának korlátai ennél alacsonyabbak lehetnek.

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

Beépített aláírás: aláírás az alkalmazás elhagyása nélkül

Ügyfele megtekinti és aláírja dokumentumát az Ön saját felületéről. A ceremónia az oldalán egy ablakban nyílik meg, és automatikusan visszatér Önhöz, miután elkészült. Szerver oldalán semmi új: az envelopot szokásosan hozza létre a redirectUrl megadásával, majd bízza az SDK-ra a címzett aláírási URL-jét.

• • Hívja meg a Certyneo.sign() függvényt közvetlenül a kattintáskezelőjében, és adja át a szerveroldali hívást a getUrl segítségével. Az await a sign() előtt kilépteti a felhasználói gesztusból: a Safari és a Firefox ekkor blokkolja az ablakot. Az SDK azonnal megnyitja és betölti, amikor az ígérete feloldódik.
• • A redirectUrl a visszatérési csatorna. Ide visszairányítjuk az aláírót a certyneo_status (completed vagy declined) és a certyneo_envelope hozzáadásával. Töltse be ugyanezt a szkriptet ezen a visszatérési oldalon: ez értesíti az háttérben nyitva maradt portálablakot.
• • Beágyazott módban saját műveletfelhívásaink elnyomódnak. Az ügyfele soha nem lát meghívást a Certyneo-fiók létrehozására.
• • Ha a böngésző elutasítja az ablakot, az SDK automatikusan teljes oldalas átirányításra vált. Az útvonal azonos az aláíróhoz képest, és a visszatérési oldala pontosan ugyanazokat a paramétereket kapja.
• • Szándékosan nem létezik "a felhasználó elhagyta" callback: az ablak állapota nem olvasható az oldaláról, és egy ilyen callback tévedésből aktiválódna. Az elmaradó aláírás függőben marad a webhook-ig.

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

Hitelesítés

Kulcs API minden hívásban a Header-ben szerepel. A kulcsok a Beállítások → API-képek oldalról generálhatók és csak egyszer jelennek meg.

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

• • Formátum: sk_live_… éles környezetben, sk_test_… a tesztkörnyezetben. Fejléc: Authorization: Bearer <clé>.
• • Tartalom: kijelölőlapok, dokumentumok, webhívások, aláírások – olvasható (:) vagy írási (:write) mód. Az íráshoz szükség van olvasáshoz; a tartalom * minden jogot ad.
• • A sk_test_ kulcsok sandbox erőforrásokat hoznak létre, a kvótából és a számlázásból kizárva. A címzettnek nem küld valódi e-mailt, kivéve, ha a címe megegyezik a küldő fiók e-mail címével — hasznos a teljes folyamat saját magadon történő teszteléséhez.
• • Hibák: 401 érvénytelen kulcs, 403 túlcsordult tartomány, 429 túl sok kérelem, 402 havi kvótának elérése.

Válasz formátuma

Egy fontos információ a kliens előtt: a könyvtárak egy objektumban kerülnek bekapcsolódásra, míg az egyszerű erőforrások átadóként jelennek meg. Egy egyszerű erőforráson response.data.data olvasása tehát undefined ad vissza.

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

További információ

• Elektronikus aláírás API: árak és dokumentáció
• Natív integrációk (HubSpot, Zapier, Make, Power Automate…)
• Dokumentumok tömeges elküldése aláírásra, kód nélkül
• Ismerje meg a Certyneo elektronikus aláírás megoldást