ساعت یازده شب است و خریدار در سایت فروش اقساطی شما لپتاپش را انتخاب کرده، مدارکش را بارگذاری کرده و پای مرحلهٔ نهایی ایستاده است. دقیقاً در همین لحظه یک پیام آشنا نیمی از فروشهای آنلاین را تا صبح از بین میبرد: «قرارداد را پرینت بگیرید، امضا کنید و اسکن آن را بفرستید».
حالا تصویر مقابل را ببینید. احراز هویت مشتری همانجا داخل فرم سایت یا اپلیکیشن خود شما انجام میشود و سامانه در چند ثانیه تأیید میکند شمارهٔ موبایل واقعاً به نام همان کد ملی است. قرارداد با مشخصات رسمی او ساخته میشود و صفحهٔ امن امضا باز میشود. هشت ثانیه پس از ثبت امضا هم مشتری مستقیم به سایت شما برمیگردد و فایل پلمبشدهٔ قرارداد خودکار به سرورتان تحویل داده میشود.
در این معماری، مشتری حس نمیکند از محصول شما بیرون رفته است و تیم عملیات هم درگیر پیگیری تلفنی و بایگانی دستی نمیشود. ما در الامضا این مسیر را طوری طراحی کردهایم که همهچیز در نرمافزار خود شما بگذرد و فقط لحظهٔ امضا روی صفحهٔ امن ما ثبت شود.
کدام مسیر اتصال برای کسبوکار شما ساخته شده است؟
پیش از نوشتن حتی یک خط کد، انتخاب مسیر درست به یک پرسش ساده برمیگردد: فایل قرارداد را چه کسی میسازد؟ پاسخ همین پرسش مشخص میکند که باید سراغ وبسرویس مستقیم بروید، از ترکیب فرمساز و وبسرویس استفاده کنید یا اصلاً سراغ افزونهٔ بدون کدنویسی وردپرس بروید.
معیار | API مستقیم | فرمساز + API | افزونهٔ وردپرس |
|---|---|---|---|
مناسب | اپ و نرمافزار با سند متغیر | قالب ثابت مثل استخدام و اجاره | سایت وردپرس و فروشگاه ووکامرس |
کدنویسی | بله، سمت سرور | کم؛ فقط ارسال داده | خیر؛ نصب و چند کلیک |
منبع سند | فایل PDF یا تصویر شما | قالب ساختهشده در فرمساز | فرم سایت یا سفارش ووکامرس |
هدایت امضا | لینک امضا در اپ و پیامک | لینک امضا در پاسخ و پیامک | فرم یکنفره آنی؛ بقیه پیامک |
اگر نرمافزار شما برای هر معامله یک PDF کاملاً اختصاصی تولید میکند، API مستقیم یعنی گفتوگوی بیواسطهٔ سرور شما با الامضا بهترین انتخاب است. اگر متن قرارداد ثابت است و فقط نام، مبلغ و کد ملی عوض میشود، ترکیب فرمساز و API زحمت تولید PDF را از دوش تیم فنی برمیدارد. حتی میتوانید این مسیرها را ترکیب کنید تا فرم در وردپرس پر شود و نرمافزار مالی شما فایل نهایی را با وبهوک بگیرد.
احراز هویت مشتری در دو ایستگاه؛ چرا صفحهٔ امضا جدا باز میشود؟
در یک اتصال اصولی، بررسی هویت در دو ایستگاه انجام میشود: ایستگاه اول در فرم خود شما پیش از ساخت قرارداد است و ایستگاه دوم در لحظهٔ امضا که همیشه برقرار است. در ایستگاه اول میتوانید چهار استعلام رسمی را مستقیم به فرم خودتان بیاورید تا پیش از ساختن پرونده، جلوی خطای تایپی یا سیمکارت امانتی گرفته شود.
نوع استعلام | ورودی مشتری | خروجی رسمی سامانه |
|---|---|---|
تطبیق شاهکار | شمارهٔ موبایل و کد ملی | تأیید مالکیت خط به نام همان کد ملی |
استعلام ثبتاحوال | کد ملی و تاریخ تولد | نام، نام خانوادگی، نام پدر و وضعیت حیات |
استعلام شخص حقوقی | شناسهٔ ملی شرکت | نام ثبتشده و رسمی شرکت |
استعلام کد پستی | کد پستی دهرقمی | نشانی دقیق ثبتشده |
ایستگاه دوم در لحظهٔ امضاست و ما عمداً آن را روی صفحهٔ امن خودمان نگه داشتهایم. وقتی امضاکننده را اضافه میکنید، مالکیت سیمکارت با شاهکار سنجیده میشود و روی صفحهٔ امضا کد پیامکی زنده از او گرفته میشود. امضاکنندهٔ بار اول مشخصاتش را با ثبتاحوال تطبیق میدهد، اما کاربر دارای حساب احرازشده در مراجعههای بعدی بلافاصله پس از کد پیامکی امضا میکند. علت حقوقی این طراحی را ما در امضای الکترونیک بدون احراز هویت چقدر اعتبار دارد؟ با جزئیات شکافتهایم.
اعتبار حقوقی و تفاوت امضای الکترونیک و دیجیتال در وبسرویس
وبسرویس فقط پل رساندن کاربر به اتاق امضاست؛ بنابراین سندی که از دل اپلیکیشن شما بیرون میآید موبهمو همان اعتبار حقوقی قراردادهای پنل الامضا را دارد. قانون تجارت الکترونیکی ایران قاعدهٔ پایه را صریح گذاشته است:
ماده ۷ — هرگاه قانون، وجود امضاء را لازم بداند امضای الکترونیکی مکفی است.
ما در الامضا حتی روی امضای الکترونیک عادی (signature_method=electronic) هم هر سند تکمیلشده را بهصورت پیشفرض با مهر سازمانی و مهر زمانی معتبر پلمب میکنیم. به همین دلیل هرگونه دستکاری بعدی فایل PDF فوراً آشکار میشود و سند کد رهگیری ۱۶ کاراکتری میگیرد.
اگر حوزهٔ کاری شما نیازمند گواهی شخصی یعنی signature_method=digital باشد، تعرفهٔ امضای هر قرارداد بین الکترونیک و دیجیتال در الامضا هیچ تفاوتی ندارد. تنها فرقش این است که کاربر یکبار با احراز ویدیویی چهره، گواهی ابری شخصی با اعتبار حدود شش ماه میگیرد. با همان یک گواهی میتوان بینهایت قرارداد دیجیتال را بدون پرداخت هزینهٔ مجدد گواهی امضا کرد و شروع صدور آن هم با POST /certificates/onboarding از داخل اپ شما ممکن است. جزئیات این دو سطح را در تفاوت امضای الکترونیک و امضای دیجیتال و مبانی قضایی را در اعتبار قانونی امضای الکترونیک در دادگاه و احراز هویت غیرحضوری چیست؟ بخوانید.
معماری ارتباط اپ، سرور شما و الامضا در یک نگاه
از اینجا به بعد وارد جزئیات فنی میشویم که تیم محصول و برنامهنویس در کنار هم به آن نیاز دارند. جریان کامل یک قرارداد میان سه بازیگر حرکت میکند: اپلیکیشن یا سایتی که دست مشتری است، سرور شما که کلید خصوصی ارتباط را نگه میدارد و سرور الامضا.

دو قاعدهٔ طلایی تمام امنیت و پایداری این نمودار را میسازد. اول اینکه توکن دسترسی فقط روی سرور شما میماند و اپ موبایل یا کد جاوااسکریپت مرورگر هرگز مستقیم با الامضا حرف نمیزند. دوم اینکه بازگشت کاربر به redirect_url فقط نشانهٔ پایان کار در ظاهر برنامه است؛ چون ممکن است اینترنت کاربر لحظهٔ آخر قطع شود یا قرارداد امضاکنندهٔ دومی هم داشته باشد. خبر قطعی تکمیل سند را همیشه از وبهوک یا استعلام مستقیم وضعیت بگیرید.
شروع پیادهسازی بدون هزینه با توکن آزمایشی
برای اینکه کل مسیر را بدون هزینه تست کنید، از منوی API ← «توکنهای API» ← «توکن جدید» یک کلید در حالت «تست (Sandbox)» بسازید. در حالت آزمایشی مبلغی از کیف پول کسر نمیشود و استعلامهای هویتی پاسخ موفق شبیهسازیشده میدهند. پیامک دعوت هم هنگام تعریف امضاکننده ارسال نمیشود، اما آدرسها و ساختار JSON دقیقاً همان محیط واقعی است.

هنگام ساخت توکن، دسترسیها را به حداقل مورد نیاز مثل contracts:write، signers:write، contracts:read و webhooks:manage محدود کنید و اگر سرورتان IP ثابت دارد، آن را در بخش «IP Whitelist» بنویسید. رشتهٔ توکن فقط یکبار نمایش داده میشود و پیشوند متنی ندارد. بنابراین برای تشخیص محیط هرگز رشتهٔ توکن را تجزیه نکنید و وضعیت را از /api/v1/me یا هدر X-Emza-Mode بخوانید:
curl https://elemza.com/api/v1/me \
-H "Authorization: Bearer $ELEMZA_TOKEN"{
"data": {
"token": {
"name": "sample-mobile-app (test)",
"mode": "test",
"scopes": ["contracts:read", "contracts:write", "signers:write", "webhooks:manage", "forms:read", "forms:write"],
"ip_whitelist": [],
"expires_at": null
}
}
}پیشنهاد ما در تیم فنی این است که سرویس شما هنگام راهاندازی data.token.mode را بررسی کند تا توکن آزمایشی هرگز روی سرور عملیاتی جا نماند.
گام اول در کد: بارگذاری سند و ساخت پروندهٔ قرارداد
وقتی نرمافزار شما برای هر سفارش یک فایل PDF یا تصویر اختصاصی (تا سقف ۴ مگابایت) تولید میکند، ابتدا پروندهٔ قرارداد را همراه با Idempotency-Key و نشانی بازگشت https میسازید:
curl -X POST https://elemza.com/api/v1/contracts \
-H "Authorization: Bearer $ELEMZA_TOKEN" \
-H "Idempotency-Key: order-1042-contract" \
-F "title=Equipment lease - order 1042" \
-F "signature_method=electronic" \
-F "redirect_url=https://app.example.com/orders/1042/signed" \
-F "file=@contract.pdf"پاسخ با کد 202 برمیگردد؛ یعنی پرونده ثبت شده و صفحات سند در حال آمادهسازی است:
{
"data": {
"code": "KHAM7WG6NGPSJ3GB",
"title": "Equipment lease - order 1042",
"status": "draft",
"signature_method": "electronic",
"page_count": 1,
"processing_status": "pending",
"_links": {
"processing": "https://elemza.com/api/v1/contracts/KHAM7WG6NGPSJ3GB/processing",
"signers": "https://elemza.com/api/v1/contracts/KHAM7WG6NGPSJ3GB/signers"
}
}
}هدر Idempotency-Key جلوی ساخت قرارداد تکراری در زمان قطعی شبکه را میگیرد و ما پاسخ هر کلید را تا ۲۴ ساعت نگه میداریم. توجه کنید که اگر درخواستی خطا گرفت و داده را اصلاح کردید، باید کلید تازهای بفرستید؛ چون ارسال بدنهٔ متفاوت با کلید قبلی خطای 409 برمیگرداند. همچنین شناسهٔ سفارش خودتان را مستقیم داخل مسیر redirect_url بگذارید.
گام دوم در کد: افزودن امضاکننده و دریافت لینک امضا
بهمحض آماده شدن فایل که با وبهوک contract.processing.completed یا مقدار ready: true در مسیر processing مشخص میشود، مشخصات امضاکننده را ارسال میکنید تا signing_url تولید شود:
curl -X POST https://elemza.com/api/v1/contracts/KHAM7WG6NGPSJ3GB/signers \
-H "Authorization: Bearer $ELEMZA_TOKEN" \
-H "Idempotency-Key: order-1042-signers" \
-H "Content-Type: application/json" \
-d '{"signers":[{"first_name":"Reza","last_name":"Karimi","mobile":"09120000001","national_code":"1234567891","order":1}]}'{
"data": [
{
"full_name": "Reza Karimi",
"mobile": "0912****001",
"national_code": "123****891",
"order": 1,
"status": "waiting",
"step": "authentication",
"signing_url": "https://elemza.com/signature/verify/cKLvO5mgBHLNLyQU/eyJpdiI6..."
}
],
"meta": { "contract_status": "waiting_signature" }
}شمارهٔ موبایل و کد ملی را حتماً با ارقام انگلیسی بفرستید. در صورت وجود هرگونه اشکال در دادهها، ساختار خطای استاندارد 422 دقیقاً فیلد مشکلدار و کد پیگیری درخواست یعنی request_id را برمیگرداند:
{
"type": "https://docs.elemza.com/errors/validation",
"status": 422,
"code": "validation",
"title_en": "Request body validation failed",
"errors": [{ "field": "signers.0.mobile", "code": "invalid" }],
"request_id": "01M5WM9KCK41H13FZHXBAZWXQG"
}پیادهسازی سریعتر با بستهٔ رسمی PHP و مستندات OpenAPI
اگر سمت سرورتان PHP 8.1 به بالاست، بستهٔ «SDK رسمی PHP» را از پنل دریافت کنید. این بسته بهطور خودکار برای تمام درخواستهای نوشتنی Idempotency-Key میسازد و تلاش مجدد را مدیریت میکند:
use Elemza\Sdk\ElemzaClient;
$elemza = new ElemzaClient(getenv('ELEMZA_TOKEN'));
$contract = $elemza->contracts()->create(
['title' => 'Equipment lease - order 1042',
'signature_method' => 'electronic',
'redirect_url' => 'https://app.example.com/orders/1042/signed'],
[__DIR__ . '/contract.pdf'],
);
// once the file has been processed:
$signers = $elemza->signers()->add($contract['code'], [[
'first_name' => 'Reza', 'last_name' => 'Karimi',
'mobile' => '09120000001', 'national_code' => '1234567891', 'order' => 1,
]]);
$signingUrl = $signers[0]['signing_url'];برای سایر زبانها، مرجع کامل همراه با فایل OpenAPI و مجموعهٔ Postman را در مستندات API الامضا گذاشتهایم. هنگام تست صفحهٔ امضا در محیط آزمایشی، لازم نیست موبایل و کد ملی واقعی خودتان را بدهید؛ چون در این محیط نه پیامکی به گوشی کسی میرود و نه استعلام هویتی انجام میشود. کد تأیید روی خود صفحه نمایش داده میشود و سند نهایی هم با مهر «آزمایشی» به دستتان میرسد.
باز کردن صفحهٔ امضا در موبایل و وب بدون خروج کاربر
بهترین تجربه در اپلیکیشنهای موبایل، باز کردن signing_url در مرورگر داخلی اپ (Custom Tabs در اندروید و SFSafariViewController در iOS) به همراه تنظیم App Links یا Universal Links روی redirect_url است. اگر از WebView داخلی استفاده میکنید، جاوااسکریپت، کوکی و DOM storage را فعال بگذارید و برای قراردادهایی که احراز ویدیویی امضای دیجیتال دارند دسترسی دوربین و میکروفون را هم بدهید.
در وباپلیکیشنها باز کردن لینک در همان پنجره سرراستترین الگوست؛ در مقابل، ما بارگذاری صفحهٔ امضا داخل iframe را برای محافظت امنیتی از امضاکننده بستهایم. پس از ثبت امضا، کاربر صفحهٔ تأیید را میبیند و اگر redirect_url داده باشید، ظرف ۸ ثانیه خودکار یا با لمس دکمهٔ «بازگشت» به نرمافزار شما برمیگردد.
دریافت آنی نتیجه با وبهوک و تأیید امضای پیام
بهجای پرسش مکرر از سرور، نشانی https خودتان را در بخش «وبهوکها» یا با POST /webhooks ثبت کنید. با این کار رویدادهایی مثل آماده شدن فایل، امضای هر نفر و تکمیل نهایی (contract.completed) آنی به سرورتان میرسد:
{
"id": "01M5WCQ8H3T6V9K2N4R7Y1A5E0",
"api_version": "v1",
"name": "contract.completed",
"occurred_at": "2026-10-26T11:42:07.512Z",
"attempt": 1,
"data": {
"code": "KHAM7WG6NGPSJ3GB",
"title": "Equipment lease - order 1042",
"completed_at": "2026-10-26T11:42:07.000Z",
"signed_pdf_url": "https://elemza.com/api/v1/contracts/KHAM7WG6NGPSJ3GB/dl?expires=...&signature=...",
"signers_count": 1
}
}فیلد signed_pdf_url یک لینک دانلود امضاشده با اعتبار ۲۴ ساعته است تا سرورتان فایل پلمبشده را دانلود و بایگانی کند. پیش از پردازش هر وبهوک، هدر X-Emza-Signature را روی بدنهٔ خام پیام و بازهٔ زمانی پنجدقیقهای بررسی کنید:

$secret = getenv('ELEMZA_WEBHOOK_SECRET');
$body = file_get_contents('php://input'); // raw untouched body
$timestamp = $_SERVER['HTTP_X_EMZA_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_EMZA_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (! hash_equals($expected, $signature) || abs(time() - (int) $timestamp) > 300) {
http_response_code(401);
exit;
}
$event = json_decode($body, true); // deduplicate by $event['id'], push to queue
http_response_code(200);در PHP SDK همین بررسی با یک خط SignatureVerifier::fromGlobals($secret) انجام میشود و در Node.js هم به همین سادگی با express.raw پیادهسازی خواهد شد:
const crypto = require('crypto');
app.post('/elemza/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const ts = req.get('X-Emza-Timestamp') || '';
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.ELEMZA_WEBHOOK_SECRET)
.update(ts + '.').update(req.body).digest('hex');
const a = Buffer.from(req.get('X-Emza-Signature') || '');
const b = Buffer.from(expected);
const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
if (!valid || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);
const event = JSON.parse(req.body); // event.name and event.id
res.sendStatus(200); // process asynchronously in queue
});تابآوری وبهوک در زمان قطعی سرور شما
هر ارسال وبهوک ۱۰ ثانیه منتظر پاسخ مستقیم 200 (بدون ریدایرکت) میماند؛ پس عملیات سنگین مثل دانلود PDF را به صف پسزمینه بسپارید. اگر سرور شما موقتاً در دسترس نباشد، ما بهترتیب یک دقیقه، ده دقیقه و یک ساعت بعد دوباره پیام را میفرستیم. حتی پس از چهار بار عدم پاسخ هم دادهای گم نمیشود و میتوانید از پنل وبهوکها یا با POST /webhook-deliveries/{id}/replay رویدادهای جامانده را بازپخش کنید.
مسیر دوم: ساخت خودکار قرارداد از قالب ثابت در فرمساز
اگر قراردادهای شما قالب ثابتی دارند، یکبار متن و متغیرها را در فرمساز الامضا بچینید و ساختار فیلدها را از GET /forms/{slug}/schema بخوانید. اگر در فرم خودتان استعلام شاهکار یا ثبتاحوال گذاشتهاید، پیش از ثبت نهایی آن را از سرورتان فراخوانی کنید:
POST /api/v1/forms/{slug}/verify-field
Content-Type: application/json
{ "field": "identity_check", "values": { "mobile": "09120000001", "national_code": "1234567891" } }سپس مقدار امضاشدهٔ data.value را عیناً کنار سایر دادهها و کلید داخلی خودتان (reference) به مسیر ثبت پاسخ بفرستید. فقط دقت کنید که فیلد آدرس همیشه یک شیء ساختیافته است و فایلهای پیوست ابتدا به /uploads ارسال میشوند:
POST /api/v1/forms/{slug}/submissions
Content-Type: application/json
{
"reference": "crm-lead-5531",
"data": {
"identity_check": "...",
"full_name": "Reza Karimi",
"national_code": "1234567891",
"mobile": "09120000001",
"address": { "province": "...", "city": "...", "street": "...", "unit": "...", "postal_code": "1234567890" }
}
}در پاسخ 201، وقتی data.outcome.state برابر completed باشد، قرارداد ساخته شده و لینک امضای هر طرف همانجا در پاسخ برمیگردد.
مسیر سوم: اتصال وردپرس و ووکامرس بدون کدنویسی
اگر سایتتان روی وردپرس ۶ و PHP 8.1 به بالاست، افزونهٔ رسمی ما را از پنل یا صفحهٔ افزونهٔ وردپرس نصب کنید و توکن را در تنظیمات قرار دهید. سپس فرم دلخواه را با کد کوتاه [elemza_form] یا بلوک ویرایشگر و المنتور وسط برگه بگذارید. فرم دقیقاً با رنگ و ظاهر سایت خودتان نمایش داده میشود و در فرمهای تکامضایی، کاربر بلافاصله پس از تکمیل فرم به صفحهٔ امضا میرود. برای سرعت بیشتر صف ارسال هم اجرای ۵ دقیقهای wp-cron.php را روی هاست فعال کنید.

در فروشگاههای ووکامرس هم افزونه بلافاصله پس از پرداخت سفارش دستبهکار میشود. اقلام سبد خرید، مبلغ و مشخصات خریدار مستقیم روی متغیرهای قرارداد مینشیند و لینک امضا پیامک میشود. حتی اگر دادهای مثل کد ملی در صفحهٔ تسویهحساب نبوده باشد، یک فرم تکمیلی آماده در صفحهٔ تشکر از خرید به مشتری نشان میدهد تا قرارداد بدون دخالت اپراتور بسته شود.
پرتکرارترین خطاهای اتصال در عمل و گام آخر پیش از انتشار
وقتی ما لاگ درخواستهای ردشدهٔ وبسرویس را در یک بازهٔ سهماهه کالبدشکافی کردیم، نتیجه روشن بود. هیچکدام از خطاها به پیچیدگی امضا ربطی نداشت و نزدیک نیمی از کل ردشدنها فقط به توکن و قالب فیلدها برمیگشت.

حدود ۳ مورد از هر ۱۰ خطا به نبود یا اشتباه بودن هدر Authorization: Bearer مربوط بود که سهچهارم آن به خاطر باز کردن مستقیم آدرس API در مرورگر رخ داده بود. حدود ۲ از ۱۰ مورد به دلیل ارسال ارقام فارسی در موبایل یا رشتهٔ متنی بهجای شیء آدرس رد شده بودند. همچنین ۱٫۵ از ۱۰ مورد شناسهٔ فرم را بهجای خواندن از GET /forms از روی آدرس پنل کپی کرده بودند. برای جلوگیری از خطای کسری موجودی (402) پیش از ارسالهای انبوه از GET /cost-estimate و /quota استفاده کنید و بهجای پرسش پیاپی به وبهوک تکیه کنید.
پیش از تغییر توکن به حالت «تولید (Live)»، چهار نکتهٔ پایانی را کنترل کنید. بررسی خودکار data.token.mode هنگام شروع سرویس فعال باشد و کیف پول یا بستهٔ حساب شارژ باشد. همچنین اگر قراردادها شرکتی است legal_entity_id یا شرکت پیشفرض تنظیم شده باشد، وبهوک زیر ۱۰ ثانیه پاسخ 200 بدهد و request_id خطاها در لاگ سرور ذخیره شود. مرجع کامل تمام مسیرها در مستندات API در اختیار شماست.