REST API — eIDAS

API امضای الکترونیکی برای توسعه‌دهندگان

امضای الکترونیکی eIDAS را در برنامه خود ادغام کنید: API REST، webhook های امضاشده با HMAC، امضای جاسازی‌شده در iframe و کلیدهای تست رایگان از همان حساب رایگان.

ایجاد حساب توسعه‌دهنده مستندات API

کلیدهای تست رایگان · SLA با 99,9 % (Business و Enterprise) · میزبانی در اتحادیه اروپا

REST + مشخصات OpenAPI

endpoint های قابل پیش‌بینی، JSON تمیز، کدهای استاندارد HTTP. مشخصات OpenAPI قابل دانلود است تا کلاینت‌های خودتان را تولید کنید.

Webhooks قابل اعتماد

5 تلاش با فاصله‌های فزاینده، امضای HMAC SHA-256، رویدادهای ناموفق از داشبورد قابل ارسال مجدد هستند. نیازی به کدنویسی polling نیست.

انطباق eIDAS بومی

امضای ساده، پیشرفته (OTP پیامکی) و واجد شرایط، که برای هر پاکت با فیلد signatureLevel انتخاب می‌شود. یک مسیر حسابرسی دارای مهر زمانی به هر سند امضاشده پیوست می‌شود.

میزبانی در اتحادیه اروپا

سرورها در آلمان، فرانسه و اسپانیا. محدودیت‌های نرخ درخواست برای هر طرح منتشر شده و هدرهای X-RateLimit در هر پاسخ. SLA با 99,9 % روی Business و Enterprise.

شروع با سه فراخوانی

PDF را بارگذاری کنید، پاکت را بسازید و آن را ارسال کنید: سه درخواست HTTP کافی است.

cURL — بارگذاری، ساخت، ارسال

# 1. Upload the PDF
curl https://certyneo.com/api/v1/documents \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -F "file=@contrat.pdf"
# → { "id": "cm8doc...", "status": "READY", ... }

# 2. Create the envelope (draft)
curl https://certyneo.com/api/v1/envelopes \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Contrat de prestation",
    "documentIds": ["cm8doc..."],
    "recipients": [{ "email": "client@example.com", "name": "Jane Doe" }]
  }'
# → { "id": "cm8env...", "status": "DRAFT", ... }

# 3. Send the invitations
curl -X POST https://certyneo.com/api/v1/envelopes/cm8env.../send \
  -H "Authorization: Bearer $CERTYNEO_API_KEY"

POST /documents شناسه PDF را برمی‌گرداند، POST /envelopes یک پیش‌نویس با امضاکنندگان آن می‌سازد و سپس POST /envelopes/:id/send دعوت‌نامه‌ها را ارسال می‌کند. پس از آن، پیشرفت کار از طریق webhook می‌رسد.

Node.js — تابع fetch بومی، بدون وابستگی

// Node 18+ — native fetch, no dependency
import { readFile } from "node:fs/promises";

const API = "https://certyneo.com/api/v1";
const auth = { Authorization: `Bearer ${process.env.CERTYNEO_API_KEY}` };

// 1. Upload the PDF
const form = new FormData();
const pdf = new Blob([await readFile("contrat.pdf")], { type: "application/pdf" });
form.append("file", pdf, "contrat.pdf");
const doc = await (await fetch(`${API}/documents`, { method: "POST", headers: auth, body: form })).json();

// 2. Create the envelope (draft)
const envelope = await (await fetch(`${API}/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: "Jane Doe" }],
  }),
})).json();

// 3. Send the invitations
await fetch(`${API}/envelopes/${envelope.id}/send`, { method: "POST", headers: auth });

به هیچ SDK نیازی نیست: API با fetch بومی Node 18 یا هر کلاینت HTTP فراخوانی می‌شود. مشخصات OpenAPI همچنین امکان تولید یک کلاینت نوع‌دار به زبان برنامه‌نویسی شما را می‌دهد.

Webhooks — به زمان واقعی پاسخ دهید

رویدادهای پاکت و گیرنده، امضای HMAC قابل تأیید و بازتاب خودکار.

envelope.completed

{
  "id": "cm8f2h6a10004qr9k5p2wm3xt",
  "event": "envelope.completed",
  "data": {
    "envelopeId": "cm7x2k9p40001qz8h3f7bn2ld",
    "subject": "Contrat de prestation",
    "status": "COMPLETED",
    "completedAt": "2026-09-26T08:42:13.000Z",
    "recipientCount": 1,
    "recipients": [
      { "email": "client@example.com", "name": "Jane Doe", "role": "SIGNER", "status": "SIGNED" }
    ],
    "signedDocumentUrl": "https://storage.certyneo.com/signed/...pdf?X-Amz-Expires=604800&..."
  },
  "timestamp": "2026-09-26T08:42:13.521Z"
}

امضای HMAC SHA-256 هر payload — تأیید صحت در سمت سرور.
تلاش مجدد خودکار در صورت شکست موقت: ۵ تلاش در حدود ۱ ساعت و ۲۰ دقیقه با عقبنشینی نمایی.
رویدادهای ناموفق در داشبورد فهرست می‌شوند و با یک کلیک قابل اجرای مجدد هستند. پس از 5 شکست پیاپی، endpoint معلق می‌شود و به شما اطلاع داده می‌شود.
تا 5 endpoint در Standard، تا 15 در Business و تا 50 در Business Pro، که هر کدام مشترک رویدادهای انتخابی شما هستند.

چرا یک API اختصاصی برای امضای الکترونیکی؟

ادغام امضای الکترونیکی در محصول شما موضوع پیش‌پا افتاده نیست. شما به تضمین‌هایی در مورد انطباق قانونی (eIDAS)، قابلیت اعتماد فنی (webhook‌هایی که واقعاً می‌رسند)، و حاکمیت داده‌ها (میزبانی اروپایی برای اجتناب از Cloud Act) نیاز دارید. API Certyneo هر سه مورد را پوشش می‌دهد.

این API توسط توسعه‌دهندگان و برای توسعه‌دهندگان طراحی شده و از قراردادهای REST پیروی می‌کند: نسخه در URL (/api/v1)، صفحه‌بندی با page و limit، خطاهای JSON با کدی قابل خواندن توسط ماشین، و مشخصات OpenAPI برای تولید کلاینت‌ها. نه SOAP، نه XML، نه غافلگیری.

انطباق eIDAS توضیح‌داده شده برای توسعه‌دهندگان

مقررات eIDAS سه سطح امضا تعریف می‌کند: ساده (SES)، پیشرفته (AES) و واجد شرایط (QES). API شرکت Certyneo امکان انتخاب سطح هر پاکت را با فیلد signatureLevel فراهم می‌کند: SIMPLE (پیش‌فرض)، ADVANCED یا QUALIFIED. امضای ساده بیشتر قراردادهای تجاری رایج را پوشش می‌دهد؛ QES زمانی به کار می‌رود که یک متن قانونی یا گیرنده، هم‌ارزی با امضای دست‌نویس را الزامی کند.

از نظر فنی، سطح پیشرفته به‌طور خودکار OTP پیامکی را فعال می‌کند و برای هر امضاکننده شماره تلفن می‌خواهد. مسیر حسابرسی طبق استاندارد RFC 3161 مهر زمانی می‌خورد. QES بر پایه یک گواهی واجد شرایط است که یک ارائه‌دهنده خدمات اعتماد واجد شرایط در اتحادیه اروپا صادر کرده است. همه چیز از طریق API کنترل می‌شود.

معماری ادغام توصیه‌شده

الگوی ادغام رایج‌ترین این جریان را دنبال می‌کند:

بک‌اند شما PDF را بارگذاری می‌کند (POST /api/v1/documents)، پاکت را به‌صورت پیش‌نویس می‌سازد (POST /api/v1/envelopes) و سپس آن را ارسال می‌کند (POST /api/v1/envelopes/:id/send).
امضاکننده دعوت‌نامه خود را از طریق ایمیل دریافت می‌کند، یا مستقیماً در رابط کاربری شما با امضای جاسازی‌شده در iframe امضا می‌کند (POST /api/v1/envelopes/:id/embed-url، از طرح Standard به بعد).
پس از تکمیل امضا، Certyneo webhook شما را با رویداد envelope.completed فراخوانی می‌کند.
شما پایگاه داده خود را به‌روز می‌کنید و کاربر را مطلع می‌کنید (ایمیل، in-app، و غیره).

کلیدهای تست رایگان

کلیدهای sk_test_ در همه طرح‌ها، از جمله طرح رایگان، در دسترس هستند و پاکت‌های تست از سهمیه ماهانه شما کم نمی‌کنند. در طرح رایگان، فقط می‌توان آن‌ها را به آدرس ایمیل خودتان فرستاد و به 20 درخواست در ساعت محدودند؛ طرح‌های پولی از 200 تا 1 000 درخواست در ساعت می‌روند. داده‌های تست پس از 30 روز پاک می‌شوند. نخستین کلید تست یک حساب رایگان، علاوه بر این، یک ماه طرح Standard را هدیه می‌دهد.

و اگر شما نمی‌خواهید کد بنویسید

همه‌چیزی که این API انجام می‌دهد می‌تواند بدون نوشتن یک خط کد نیز از طریق یک جریان کنترل شود: ایجاد یک پاکت، ارسال آن، واکنش به یک امضا، دریافت PDF مختوم شده و مسیر حسابرسی آن. همان پایه، با یک طراح بصری به جای مشتری HTTP. مشاهده ادغام Power Automate و Microsoft 365.

مهاجرت از DocuSign یا Yousign

اگر از قبل یکپارچه‌سازی با DocuSign یا Yousign دارید، واژگان نزدیک است: envelopes → envelopes، recipients → recipients، webhook های وضعیت → webhooks. راهنمای مهاجرت از DocuSign و Yousign به Certyneo مراحل را از خروجی گرفتن از قالب‌ها تا جابه‌جایی webhook ها شرح می‌دهد.

آیا از Adobe Acrobat Sign (پیشتر EchoSign، سپس Adobe Sign) مهاجرت می‌کنید؟ نقشه برداری به همان میزان مستقیم است — agreements → envelopes، participants → recipients، webhooks → webhooks. مقایسه Certyneo و Adobe Acrobat Sign →

قیمت API امضای الکترونیکی: کجا اشتراک بخریم؟

برای خرید اشتراک API امضا نیازی به پیش‌فاکتور یا سفارش خرید نیست: کلیدهای تست رایگان‌اند، کلید API از داشبورد ساخته می‌شود و دسترسی به API REST تولید از طرح Standard با 19 €/ماه شامل است — همراه با webhook ها و بدون هزینه برای هر امضای ساده.

Standard — ۱۹ €/ماه: ۱۰۰ پوش/ماه، API REST + webhooks، ۱۰ کاربر
Business — ۳۹ €/ماه: ۳۰۰ پوش/ماه، ارسال گروهی، فرم‌های وب
Business Pro — ۹۹ €/ماه: ۱۰۰۰ پوش/ماه، API فرکانس بالا (۳۰۰ درخواست/دقیقه)، کاربران نامحدود

امضای واجد شرایط (QES) به‌ازای هر مورد محاسبه و هنگام ارسال پرداخت می‌شود: 9,90 € برای هر امضا با اشتراک، که پس از تمام شدن QES های گنجانده‌شده در Business و Business Pro از کارت ثبت‌شده کسر می‌شود، و 14,90 € بدون اشتراک.

برای حجم‌های بزرگ یا نیاز به تعهد قراردادی (SLA، DPA اختصاصی، صورت‌حساب سالانه)، طرح Enterprise از طریق تیم فروش خریداری می‌شود. در هر صورت، قیمت‌ها عمومی هستند — آن‌ها را قبل از تعهد مقایسه کنید.

برای رفتن بیشتر

سؤالات متداول — API

حد نرخ API چقدر است؟

محدودیت برای هر کلید، در هر دقیقه و بسته به طرح اعمال می‌شود: 60 درخواست در Standard، 120 در Business، 300 در Business Pro و 1 000 در Enterprise. هر پاسخ هدرهای X-RateLimit-Limit، X-RateLimit-Remaining و X-RateLimit-Reset را دارد؛ در صورت تجاوز، API کد 429 را با هدر Retry-After برمی‌گرداند.

هزینه API چقدر است؟

کلیدهای تست (sk_test_) در همه طرح‌ها رایگان‌اند. دسترسی به API REST تولید از طرح Standard با 19 €/ماه (100 پاکت/ماه) شامل است، سپس Business با 39 €/ماه و Business Pro با 99 €/ماه با سهمیه‌های افزایشی؛ امضای واجد شرایط (QES) به‌ازای هر مورد محاسبه می‌شود، 9,90 € با اشتراک. برای حجم‌های بیشتر، طرح Enterprise از طریق تیم فروش تهیه می‌شود.

آیا SLA وجود دارد؟

بله: 99,9 % دسترس‌پذیری ماهانه روی طرح‌های Business و Enterprise، همراه با اعتبار روی صورت‌حساب از 10 تا 50 % بسته به میزان انحراف ثبت‌شده. وضعیت سرویس به‌طور پیوسته در صفحه وضعیت Certyneo منتشر می‌شود.

از کدام احراز هویت استفاده می‌کنید؟

یک کلید API در هدر Authorization (Bearer sk_live_… یا sk_test_…). کلیدها از داشبورد ساخته و باطل می‌شوند، با اثر فوری. برای یک برنامه شخص ثالث که از طرف کاربران شما عمل می‌کند، OAuth 2.0 با جریان authorization code و PKCE در دسترس است.

چگونه امضای HMAC یک webhook را تأیید کنم؟

هر webhook هدر امضای X-Certyneo-Signature را دارد: مقدار HMAC SHA-256 به‌صورت هگزادسیمال از بدنه خام درخواست، که با secret نقطه پایانی شما محاسبه شده است. آن را در سمت سرور روی بدنه تغییرنیافته دوباره محاسبه کنید و در زمان ثابت مقایسه کنید (crypto.timingSafeEqual در Node، hmac.compare_digest در Python).

آیا SDK رسمی وجود دارد؟

هنوز منتشر نشده است. API را می‌توان مستقیماً از طریق HTTP از هر زبانی فراخوانی کرد و مشخصات OpenAPI امکان تولید یک کلاینت نوع‌دار با openapi-generator یا ابزاری مشابه را می‌دهد. بدون کدنویسی نیز Certyneo روی Make، n8n، Postman و RapidAPI در دسترس است.

آیا می‌توانم بدون پرداخت تست کنم؟

بله: یک حساب رایگان بسازید و از داشبورد یک کلید sk_test_ تولید کنید. نخستین کلید تست یک حساب رایگان همچنین یک ماه طرح Standard را هدیه می‌دهد. مجموعه Postman امکان اجرای نخستین فراخوانی‌ها را بدون نوشتن کد فراهم می‌کند.

هزینه API EchoSign (که اکنون Adobe Acrobat Sign شده است) چقدر است؟

شرکت Adobe در سال 2011 سرویس EchoSign را خرید و نام آن را به Adobe Sign و سپس Adobe Acrobat Sign تغییر داد: API آن هنوز وجود دارد، اما قیمتش عمومی نیست و از طریق پیش‌فاکتور سازمانی تیم فروش Adobe، معمولاً بر اساس بسته‌های تراکنش سالانه، تعیین می‌شود. در مقابل، Certyneo قیمت‌های خود را اعلام می‌کند: دسترسی API تولید از طرح Standard با 19 €/ماه شامل است، به‌صورت آنلاین و بدون پیش‌فاکتور خریداری می‌شود و کلیدهای تست رایگان امکان ارزیابی API پیش از پرداخت را می‌دهند.

آیا برای ادغام امضای الکترونیکی آماده‌اید؟

کلیدهای تست رایگان، مشخصات OpenAPI، webhook های امضاشده. همین حالا شروع کنید.

خواندن مستندات صحبت کردن با توسعه‌دهنده Certyneo