رفتن به محتوای اصلی
Certyneo
API REST — eIDAS

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

امضای الکترونیکی eIDAS را در برنامه خود در چند ساعت ادغام کنید. REST، webhooks قابل‌اعتماد، SDK Node/Python/Ruby، sandbox رایگان نامحدود.

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

Sandbox رایگان · 99.95% بالا بودن سیستم · میزبانی حاکمیتی EU

REST + OpenAPI 3.1

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

Webhooks قابل اعتماد

تلاش مجدد خودکار با backoff نمایی، امضای HMAC SHA-256، ژورنال رویدادهای قابل مشاهده. نیاز به polling کدنویسی نیست.

انطباق eIDAS بومی

امضاهای AES، AES-Q و QES موجود از طریق پرچم API. مسیر حسابرسی واجد شرایط شامل است، گواهی‌های TSP واجد شرایط اتحادیه اروپا.

تاخیر < 200 میلی‌ثانیه

API در استرزبورگ (اتحادیه اروپا) میزبان شده است، p95 < 200 میلی‌ثانیه از اروپا. SLA 99.95% وقت فعالیت، وضعیت عمومی زمان واقعی.

شروع در 5 دقیقه

اولین پاکت خود را با یک درخواست HTTP ایجاد کنید.

cURL — ایجاد یک پاکت
curl https://api.certyneo.com/v1/envelopes \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contrat de prestation",
    "documents": [{"file_url": "https://your.app/contract.pdf"}],
    "recipients": [{"email": "client@example.com", "name": "Jane Doe"}],
    "webhook_url": "https://your.app/webhooks/sign"
  }'

یک درخواست POST برای ایجاد پاکت، افزودن سند، امضاکننده و URL webhook کافی است. API یک sign_url آماده برای اشتراک‌گذاری برمی‌گرداند.

SDK Node.js رسمی
import Certyneo from '@certyneo/sdk';

const client = new Certyneo({ apiKey: process.env.CERTYNEO_API_KEY });

const envelope = await client.envelopes.create({
  title: 'Contrat de prestation',
  documents: [{ file_url: 'https://your.app/contract.pdf' }],
  recipients: [{ email: 'client@example.com', name: 'Jane Doe' }],
});

console.log(envelope.sign_url); // ready to share with the signer

SDK Node TypeScript تایپ‌کاری کامل، مدیریت خودکار خطاها با تلاش مجدد، و سازنده پاکت روان فراهم می‌کند. همچنین در Python و Ruby موجود است.

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

شش رویداد (envelope.sent, viewed, signed, completed, declined, expired) با امضای HMAC قابل تأیید و تلاش مجدد خودکار.

envelope.completed
{
  "event": "envelope.completed",
  "envelope_id": "env_3a2f...",
  "signed_at": "2026-05-25T14:32:18Z",
  "evidence_url": "https://api.certyneo.com/v1/envelopes/env_3a2f.../audit-trail.pdf",
  "signers": [
    { "email": "client@example.com", "signed": true, "ip": "82.x.x.x" }
  ]
}
  • امضای HMAC SHA-256 هر payload — تأیید صحت در سمت سرور.
  • تلاش مجدد خودکار در صورت شکست: 5 تلاش در 24 ساعت با backoff نمایی.
  • ژورنال رویدادهای قابل مشاهده از داشبورد: هر تلاش، وضعیت HTTP برگردانده شده، body را ببینید.
  • URL webhook قابل تنظیم برای هر پاکت (override) یا عمومی در پروژه.

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

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

طراحی شده توسط و برای توسعه‌دهندگان، از قراردادهای REST مدرن پیروی می‌کند: pagination مبتنی بر cursor، idempotency keys، versioning توسط URL، OpenAPI 3.1 برای تولید خودکار کلاینت‌های شما. بدون SOAP، بدون XML، بدون شگفتی.

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

مقررات eIDAS سه سطح امضا را تعریف می‌کنند: ساده (SES)، پیشرفته (AES) و محدود (QES). API Certyneo امکان انتخاب سطح توسط envelope را از طریق فیلد `signature_level` فراهم می‌کند. مقدار پیش‌فرض AES است (برای 95% موارد B2B کافی است). QES برای اسناد نیاز به هم‌ارزی قانونی دقیق با امضای دستنویس دستی (اسناد موثق، مناقصات عمومی) در دسترس است.

از نظر فنی، AES احراز هویت قوی امضاکننده (OTP از طریق SMS به صورت پیش‌فرض، KYC ویدیویی به عنوان گزینه) و یک مسیر حسابرسی با مهر زمانی را مستلزم است. QES یک گواهی محدود صادر شده توسط TSP محدود اتحادیه اروپا را اضافه می‌کند. تمام این‌ها توسط API مدیریت می‌شود — شما endpoint را فراخوانی می‌کنید، ما بقیه را مدیریت می‌کنیم.

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

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

  • backend شما POST /v1/envelopes را فراخوانی می‌کند تا envelope را ایجاد کند و sign_url را دریافت می‌کند که باید آن را به کاربر ارائه دهد.
  • شما کاربر را به سمت sign_url تغییر مسیر می‌دهید یا آن را در iframe جاسازی می‌کنید (با branding شما از طریق طرح Pro).
  • پس از تکمیل امضا، Certyneo webhook شما را با رویداد envelope.completed فراخوانی می‌کند.
  • شما پایگاه داده خود را به‌روز می‌کنید و کاربر را مطلع می‌کنید (ایمیل، in-app، و غیره).

Sandbox رایگان نامحدود

محیط sandbox رایگان و نامحدود است. تمام ویژگی‌های تولید در دسترس هستند، به جز اینکه امضاها ارزش قانونی ندارند (PDF با SANDBOX مشخص‌شده است). برای تست‌های خودکار، نمایش‌های کلاینت، توسعه محلی مفید است. کلیدهای sandbox از کلیدهای prod جداگانه هستند، انزوای کامل بین دو کلید.

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

اگر قبلاً یک ادغام DocuSign یا Yousign دارید، نقشه‌برداری API مستقیم است: envelopes → envelopes، recipients → recipients، status webhooks → status webhooks. راهنمای مهاجرت ما هم‌ارزی endpoint به endpoint را مستند می‌کند. برای مهاجرت کامل 1 تا 3 روز بشمارید، بسیار کمتر اگر از wrapper داخلی استفاده می‌کنید.

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

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

1000 درخواست در دقیقه به‌طور پیش‌فرض، قابل‌افزایش با درخواست برای استفاده‌های بالا (کارخانه‌ها، پلتفرم‌های multi-tenant). header X-RateLimit-Remaining در هر پاسخ سهمیه باقی‌مانده را نشان می‌دهد. در صورت تجاوز، API 429 را با Retry-After برمی‌گرداند.

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

sandbox رایگان و نامحدود است. تولید بر اساس پرداخت برای امضا کار می‌کند (از 0.40 یورو برای امضای AES با تخفیف حجم)، بدون اشتراک حداقل. طرح Enterprise شامل SLA تقویت‌شده، IP whitelisting و حساب فنی اختصاصی است.

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

99.95٪ uptime برای طرح‌های Business و Enterprise (حداکثر downtime 4 ساعت در سال). صفحه وضعیت عمومی با تاریخچه حوادث: status.certyneo.com. طرح Enterprise شامل اعتبار خودکار در صورت عدم رعایت SLA است.

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

Bearer token (کلید API) در هدر Authorization. کلیدها می‌توانند از داشبورد چرخش داده شوند و فوراً لغو شوند. برای ادغام‌های OAuth (پلتفرم چند مستاجر)، ما OAuth 2.0 Client Credentials را در طرح Enterprise ارائه می‌دهیم.

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

هر webhook شامل هدر X-Certyneo-Signature است که حاوی HMAC SHA-256 payload است، با امضای webhook secret شما. در طرف سرور، HMAC را دوباره محاسبه کنید و با مقایسه ایمن در زمان (timing-safe comparison) مقایسه کنید. SDK رسمی این کار را به‌طور خودکار از طریق webhook.verify(payload, signature, secret) انجام می‌دهد.

آیا SDK‌ها open source هستند؟

بله. SDK‌های Node، Python و Ruby در GitHub تحت مجوز MIT هستند. می‌توانید fork کنید، مشارکت کنید یا صرفاً آنها را audit کنید. باینری‌ها در npm، PyPI و RubyGems تحت namespace @certyneo / certyneo منتشر می‌شوند.

آیا می‌توانم بدون ثبت‌نام تست کنم؟

بله، از طریق مثال‌های تعاملی مستندات API: /developers/playground. درخواست‌ها در برابر یک نمونه sandbox مشترک اجرا می‌شوند، بدون نیاز به کلید. برای استفاده جدی، یک حساب توسعه‌دهنده رایگان ایجاد کنید (sandbox نامحدود).

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

Sandbox رایگان نامحدود، مستندات کامل، SDK رسمی. اکنون شروع کنید.

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