امضای الکترونیکی را در پشته خود ادغام کنید

شروع سریع

سه مرحله: یک کلید API از تنظیمات ایجاد کنید، PDF خود را به base64 رمزگذاری کنید، ارسال کنید. پاسخ شامل `signUrl` است که می‌توانید مستقیماً با گیرنده به اشتراک بگذارید.

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

تست API از ابزارهای شما

مجموعه Postman و فیش RapidAPI از مشخصات OpenAPI تولید می‌شوند که این صفحه را نیز مستند می‌کنند. هر سه بنابراین در هر endpoint با API واقعی هم‌راستا می‌مانند، نه اینکه در اولین اضافه‌کردن جدا شوند.

مجموعه Postman

۲۵ درخواست دسته‌بندی‌شده بر اساس دامنه — پوش‌های اطلاعات، اسناد، الگوها، مهرها، webhooks — با نمونه متن و پاسخ برای هر کدام. کلید خود را در متغیر apiKey مجموعه قرار دهید، سپس GET /health را اجرا کنید: هیچ احراز هویتی نمی‌طلبد و تأیید می‌کند که پیکربندی شما قبل از اولین فراخوانی احراز‌شده خوب است.

باز کردن در Postman

فیش RapidAPI

همان فهرست endpoints، قابل تست مستقیم از مرورگر. پایگاه تست دو سرصحت متمایز را انتظار می‌کشد: کلید RapidAPI که پلتفرم برای شما اختصاص می‌دهد، و کلید Certyneo شما در Authorization — دومی است که فراخوانی را واقعاً مجاز می‌کند.

مشاهده در RapidAPI

نقاط انتهایی موجود

52 مسیرهای عمومی: حساب، اسناد، پاکت‌ها، الگوها، webhook‌ها، مهرهای الکترونیکی، کلیدهای API و صورت‌حساب. همه آن‌ها یک Bearer token را می‌پذیرند و JSON برمی‌گردانند.

الگوهای پاکت

یک الگو PDF، نقش‌ها و موقعیت فیلدهای امضا را یک بار برای همیشه ثبت می‌کند، سپس در هر ارسال دوباره استفاده می‌شود: شناسهٔ آن را در templateId به جای documentIds قرار دهید، و فیلدهای موقعیت‌یافته بر روی پاکت ایجادشده کپی می‌شوند.

• • الگوها از داشبورد ایجاد می‌شوند (الگوها → الگوی جدید)، جایی که سند را رها می‌کنید و سپس فیلدها را با ماوس موقعیت می‌دهید — این ساده‌ترین راه است. API همچنین اجازه می‌دهد آنها را از طریق POST /api/v1/templates ایجاد کنید، با ارائهٔ اسناد، نقش‌ها و فیلدها؛ توجه داشته باشید که فیلدها در آنجا با مختصات مطلق موقعیت‌یافته‌اند (صفحه، x، y، عرض، ارتفاع)، بنابراین باید طرح‌بندی PDF را بدانید.
• • در حسابی که هنوز هیچ الگو ثبت نکرده است، GET /api/v1/templates فهرستی خالی برمی‌گرداند. این رفتار عادی است، نه یک خرابی احراز هویت.
• • فهرست فقط الگوهایی را شامل می‌شود که متعلق به کاربری هستند که مالک کلید API هستند. الگویی که توسط یک همکار ایجاد شده است در آن ظاهر نمی‌شود، حتی در یک فضای کاری مشترک: کلید را از حسابی تولید کنید که الگو را دارا است.
• • templateId و documentIds متقابلاً منحصر به فرد هستند: یکی یا دیگری را ارسال کنید، هرگز هر دو یا هیچ یک را نه.
• • حداقل به اندازهٔ تعداد نقش‌های امضاکننده الگو، گیرندگان SIGNER فراهم کنید، در غیر این صورت ایجاد در ۴۰۰ رد می‌شود. فیلد signerCount برگردانده شده توسط فهرست، تعداد انتظار رفته را نشان می‌دهد.
• • سطح امضای الگو توسط پاکت به ارث می‌رسد، مگر اینکه درخواست به صراحت 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.

ارسال سند: دو فرم پذیرفته شده

POST /api/v1/documents فایل را به دو روش می‌پذیرد، به انتخاب شما. کنترل‌های یکسانی در هر دو مورد اعمال می‌شود: انواع مجاز، سقف ۵۰ مگابایت، تأیید امضای دودویی و تحلیل آنتی‌ویروس.

• • در multipart/form-data، با بخشی به نام file. این فرم کلاسیک است، همان‌طور که curl -F و اکثر کتابخانه‌ها.
• • در متن خام: بایت‌های فایل بدنه درخواست را تشکیل می‌دهند و سرصحافه Content-Type نوع آن را مشخص می‌کند (برای مثال application/pdf). از یک ابزار که محتوا را همان‌طور که هست منتقل می‌کند، بدون بسته‌بندی درخواست مفید است — این کاری است که Certyneo انجام می‌دهد.
• • در متن خام، نام فایل جایی در بدنه ندارد: آن را از طریق سرصحافه X-File-Name یا پارامتر ?fileName= مشخص کنید. بدون آن، سند از نوع آن نام‌گذاری می‌شود.
• • یک نوع پشتیبانی‌نشده با ۴۱۵ پاسخ می‌دهد و دو فرم پذیرفته‌شده را نام می‌برد، و بدنه‌ای که به عنوان multipart اعلام شده است اما خوانایی ندارد ۴۰۰ پاسخ می‌دهد. هیچ یک از اینها خطای سرور نیست.

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

جایابی فیلدهای امضا

بدون الگو، پاکتی که از documentIds ایجاد می‌شود، هیچ فیلد پیش‌موقعیت‌یافته ای ندارد: امضاکننده سند را بدون مکانی برای امضا دریافت می‌کند. آرایهٔ fields، در همان فراخوانی ایجاد منتقل شده، هر فیلد را در نقطهٔ دقیق قرار می‌دهد — این معادل API است که الگو یک بار برای همیشه ثبت می‌کند.

• • مختصات بر حسب نقاط PDF هستند، منشأ در گوشهٔ بالا سمت چپ صفحه و محور Y به سمت پایین (صفحهٔ A4 برابر است با ۵۹۵ × ۸۴۲ نقطه). x و y گوشهٔ بالا سمت چپ فیلد را مشخص می‌کنند، width و height اندازهٔ آن را.
• • pageNumber از ۱ شروع می‌شود، documentIndex از ۰ شروع می‌شود. شمارهٔ صفحه‌ای فراتر از سند در ایجاد رد نمی‌شود: فیلد در زمان امضا نادیده گرفته می‌شود و جای هیچ‌کس ظاهر نمی‌شود — این اولین چیزی است که باید وقتی فیلدی در فراخوانی کم شود، بررسی کنید.
• • recipientEmail باید با یکی از گیرندگان همان فراخوانی مطابقت داشته باشد، بدون تمایز بزرگ و کوچک. در غیر این صورت ایجاد با فهرست تمام ردیف‌های خاطی ناموفق است، که از تصحیح آنها یکی یکی جلوگیری می‌کند.
• • fields و templateId متقابلاً منحصر به فرد هستند: الگو قبلاً طرح‌بندی خود را دارد. بنابراین آرایهٔ fields فقط با documentIds استفاده می‌شود.
• • انواع پذیرفته‌شده: SIGNATURE، INITIALS، DATE_SIGNED، TEXT، CHECKBOX و RADIO_GROUP. required به طور پیش‌فرض true است؛ placeholder و dateFormat اختیاری هستند، و options فقط برای RADIO_GROUP نگهداری می‌شود.
• • یک پاکت حداکثر ۱۰۰ فیلد، ۲۰ سند و ۵۰ گیرنده را می‌پذیرد — حدود برنامه‌ای شما ممکن است کمتر باشد.

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

امضای یکپارچه: امضا کردن بدون ترک برنامه شما

مشتری شما سند خود را از رابط کاربری خود مشاهده و امضا می‌کند. مراسم در پنجره‌ای بالای صفحه شما باز می‌شود و پس از اتمام، او به صورت خودکار به شما بازمی‌گردد. از سوی سرور، چیز جدیدی نیست: پاکت را طبق معمول با پر کردن redirectUrl ایجاد می‌کنید، سپس URL امضای دریافت‌کننده را به SDK محول می‌کنید.

• • Certyneo.sign() را مستقیماً در کنترل‌کننده کلیک خود فراخوانی کنید و تماس سرور خود را از طریق getUrl ارسال کنید. یک await قبل از sign() از ژست کاربری خارج می‌شود: Safari و Firefox سپس پنجره را مسدود می‌کنند. SDK آن را فوری‌تر باز می‌کند و وقتی وعده شما حل می‌شود بارگذاری می‌کند.
• • redirectUrl کانال بازگشت است. ما امضاکننده را با اضافه کردن certyneo_status (completed یا declined) و certyneo_envelope به آن ارجاع می‌دهیم. همان اسکریپت را در این صفحه بازگشت بارگذاری کنید: این اسکریپت است که پنجره پورتال باز مانده را از پس‌زمینه مطلع می‌کند.
• • در حالت یکپارچه، دکمه‌های عمل خود ما غیرفعال می‌شوند. مشتری شما هرگز دعوتی برای ایجاد حساب Certyneo نمی‌بیند.
• • اگر مرورگر پنجره را رد کند، SDK به‌طور خودکار به تغییر مسیر تمام‌صفحه می‌رود. مسیر برای امضاکننده یکسان است و صفحه بازگشت شما دقیقاً همان پارامترها را دریافت می‌کند.
• • عمداً هیچ فراخوان «کاربر کنار گذاشت» وجود ندارد: وضعیت پنجره از صفحه شما قابل‌خواندن نیست، و چنین فراخوانی به‌اشتباه فعال می‌شود. امضایی که انجام نشود در انتظار تا webhook باقی می‌ماند.

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

احراز هویت

هر درخواست کلید API را در سرصفحه Authorization حمل می‌کند. کلیدها از تنظیمات → کلیدهای API تولید می‌شوند و تنها یک بار نمایش داده می‌شوند.

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

• • قالب: sk_live_… در تولید، sk_test_… برای صندوق شن و ماسه. سرصفحه: Authorization: Bearer <کلید>.
• • دامنه‌ها: envelopes، documents، webhooks، seals — در خواندن (:read) یا نوشتن (:write). نوشتن خواندن را شامل می‌شود؛ دامنه * تمام حقوق را می‌دهد.
• • کلیدهای sk_test_ منابع سندباکس ایجاد می‌کنند که از سهمیه و صورت‌حساب مستثنی هستند. ایمیل واقعی به گیرنده ارسال نمی‌شود، مگر اینکه آدرس او با ایمیل حساب ارسال‌کننده یکسان باشد — این برای آزمایش کل جریان روی خودتان مفید است.
• • خطاها: ۴۰۱ کلید نامعتبر، ۴۰۳ دامنه ناکافی، ۴۲۹ محدودیت سرعت تجاوز شده، ۴۰۲ سهمیه ماهانه رسیده است.

شکل پاسخ‌ها

نکته‌ای که باید قبل از نوشتن کلاینت خود بدانید: مجموعه‌ها در یک شیء data کپسوله شده‌اند، در حالی که منابع واحد به صورت مسطح برگردانده می‌شوند. خواندن response.data.data بر روی یک منبع واحد بنابراین 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": [ /* … */ ]
}

پیش برفتن

• API امضای الکترونیکی: قیمت و مستندات
• ادغام‌های بومی (HubSpot، Zapier، Make، Power Automate…)
• ارسال دسته‌ای اسناد برای امضا، بدون کد
• راه‌حل امضای الکترونیکی Certyneo را کشف کنید