Integrujte elektronický podpis do vášho stacku

Rýchly štart

Tri kroky: vytvorte kľúč API z nastavení, zakódujte váš PDF v base64, odošlite. Odpoveď obsahuje `signUrl`, ktorý môžete zdieľať priamo s príjemcom.

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

Vyskúšajte API zo svojich nástrojov

Kolekcia Postman a hárok RapidAPI sú generované zo špecifikácie OpenAPI, ktorá tiež dokumentuje túto stránku. Všetky tri zostávajú v súlade s reálnym API, endpoint za endpointom, namiesto aby sa rozišli pri prvom pridaní.

Kolekcia Postman

25 žiadostí usporiadaných podľa domény — obálky, dokumenty, šablóny, pečiatky, webové háčiky — s príkladom tela a odpovede pre každú. Vložte svoj kľúč do premennej apiKey kolekcie a potom spustite GET /health: nevyžaduje žiadne overenie a potvrdzuje, že vaša konfigurácia je správna pred prvým overením hovoru.

Otvoriť v Postman

Fiche RapidAPI

Rovnaký katalóg endpointov, testovateľný priamo z prehliadača. Testovacia lavica očakáva dve odlišné hlavičky: kľúč RapidAPI, ktorý vám platforma pridelila, a váš kľúč Certyneo v Authorization — druhý v skutočnosti autorizuje volanie.

Pozrite sa na RapidAPI

Dostupné endpointy

Všetky verejné trasy: účet, dokumenty, obálky, šablóny, webhooku, elektrónické pečate, kľúče API a faktúrácia. Všetky akceptujú Bearer token a vracajú JSON.

Modely obalkov

Šablóna zaznamená raz a navždy PDF, úlohy a umiestnenie polí podpisu, potom sa opätovne použije pri každom odoslaní: zadajte jej identifikátor v templateId namiesto documentIds a umiestnené polia sú skopírované do vytvorenej obálky.

• • Šablóny sa vytvárajú z ovládacieho panela (Šablóny → Nová šablóna), kde nahrajete dokument a potom myšou umiestnite polia — to je najjednoduchší spôsob. Rozhranie API tiež umožňuje ich vytvorenie prostredníctvom POST /api/v1/templates poskytnutím dokumentov, úloh a polí; pozor, polia sú tam umiestnené v absolútnych súradniciach (strana, x, y, šírka, výška), takže musíte poznať rozloženie PDF.
• • Na konte, ktorý ešte neregistroval žiadnu šablónu, GET /api/v1/templates vracia prázdny zoznam. Toto je normálne správanie, nie chyba autentifikácie.
• • Zoznam obsahuje iba šablóny patriace používateľovi, ktorý vlastní kľúč API. Šablóna vytvorená kolegom sa v ňom nenachádza, dokonca ani v rámci zdieľaného pracovného priestoru: vygenerujte kľúč z konta, ktoré vlastní šablónu.
• • templateId a documentIds sa vzájomne vylučujú: odošlite jeden alebo druhý, nikdy oba ani žiadny z nich.
• • Poskytnite aspoň toľko príjemcov SIGNER, koľko rolí podpisujúcich má šablóna, inak je vytvorenie odmietnuté s kódom 400. Pole signerCount vrátené zoznamom označuje očakávaný počet.
• • Úroveň podpisu šablóny je dedená obálkou, pokiaľ požiadavka výslovne neposkytne 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.

Odoslanie dokumentu : dve akceptované formy

POST /api/v1/documents akceptuje súbor dvoma spôsobmi podľa výberu. V oboch prípadoch platia rovnaké kontroly : povolené typy, limit 50 MB, overenie binárneho podpisu a antivirusová analýza.

• • V multipart/form-data s časťou pomenovanou file. Toto je klasická forma, form curl -F a väčšiny knižníc.
• • V nezpracovanom tele : bajty súboru tvoria telo požiadavky a hlavička Content-Type určuje jeho typ (napríklad application/pdf). Užitočné z nástroja, ktorý prenáša obsah tak ako je, bez obaľovania požiadavky — to robí konektor Power Automate.
• • V nezpracovanom tele nemá meno súboru miesto v tele : zadajte ho cez hlavičku X-File-Name alebo parameter ?fileName=. Bez neho sa dokument pomenuje podľa svojho typu.
• • Nepodporovaný typ odpovie 415 a pomenujem dve akceptované formy a telo oznamuje multipart, ale je nečitateľné, odpovie 400. Ani jedno nie je chyba servera.

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

Umiestnenie polí podpisu

Bez šablóny, obálka vytvorená z documentIds nemá žiadne polia preumiestnené: podpisujúci dostane dokument bez miesta na podpis. Pole fields, odoslané v rovnakom volaní vytvorenia, umiestnuje každé pole s presnosťou na bod — to je ekvivalent na strane API toho, čo šablóna raz zaznamenáva.

• • Súradnice sú v bodoch PDF, pôvod v ľavom hornom rohu stránky a os Y smeruje nadol (stránka A4 má 595 × 842 bodov). x a y označujú ľavý horný roh poľa, width a height jeho veľkosť.
• • pageNumber začína na 1, documentIndex začína na 0. Číslo stránky za dokumentom nie je pri vytvorení zamietnuté: pole sa ignoruje v čase podpisu a nikde sa neobjavuje — to je prvá vec, ktorú je treba skontrolovať, keď v volaní chýba pole.
• • recipientEmail musí zodpovedať jednému z príjemcov v rovnakom volaní bez rozlišovania veľkých a malých písmen. V opačnom prípade vytvorenie zlyhá so zoznamom všetkých chybných riadkov, čo umožňuje ich oprávovanie naraz.
• • fields a templateId sa vzájomne vylučujú: šablóna už má svoju vlastnú rozloženie. Pole fields sa teda používa iba s documentIds.
• • Akceptované typy: SIGNATURE, INITIALS, DATE_SIGNED, TEXT, CHECKBOX a RADIO_GROUP. required je štandardne true; placeholder a dateFormat sú voliteľné, a options sa berie v úvahu iba pre RADIO_GROUP.
• • Obálka akceptuje maximálne 100 polí, 20 dokumentov a 50 príjemcov — limity vášho plánu môžu byť nižšie.

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

Overenie identity

Každé volanie nesie kľúč API v hlavičke Authorization. Kľúče sa generujú z Nastavenia → Kľúče API a zobrazia sa len raz.

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át: sk_live_… v produkcii, sk_test_… pre sandbox. Záhlavie: Authorization: Bearer <kľúč>.
• • Rozsahy: envelopes, documents, webhooks, seals — v režime čítania (:read) alebo zápisu (:write). Zápis implikuje čítanie; rozsah * dáva všetky práva.
• • Kľúče sk_test_ vytvárajú zdroje v sandbox režime, vylúčené z kvóty a fakturácie. Príjemcovi sa neposiela žiadny skutočný e-mail, pokiaľ jeho adresa nezodpovedá e-mailu odosielajúceho účtu — užitočné na otestovanie celého procesu na sebe.
• • Chyby: 401 neplatný kľúč, 403 nedostatočný rozsah, 429 prekročený limit rýchlosti, 402 dosiahnutá mesačná kvóta.

Formát odpovede

Bod, ktorý treba poznať pred napísaním vášho klienta: kolekcie sú zapuzdrené v objekte data, zatiaľ čo jednotné zdroje sa vracia plošne. Čítanie response.data.data na jednotnom zdroji teda vracia 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": [ /* … */ ]
}