در یک نگاه#
فرض کنید فروشگاه یا پلتفرمی دارید و میخواهید کاربرانتان قرارداد را آنلاین امضا کنند، بیآنکه خودتان سیستم امضا بسازید. کار سه طرف دارد:
سرور شما
از ما قرارداد و «پیوند امضا» میگیرد.
کاربر شما
پیوند را باز میکند، متن را میخواند و امضا میکند.
سامانه امضا
پس از امضا، خودکار به سرور شما خبر میدهد.
پیش از شروع#
این سه کار را مدیر سازمان یکبار در پنل انجام میدهد.
یک قالب قرارداد بسازید و منتشر کنید
هر جایی از متن که برای هر کاربر فرق میکند، یک جای خالی (جاینگهدار) بگذارید؛ مثل{{company_name}}. شناسه قالب و نام جای خالیها را بردارید.یک کلید API بسازید
در سازمان مناتصال API. کلید دو تکه دارد: شناسه (ak_…) که مثل نام کاربری است، و راز (sk_…) که مثل رمز است و فقط یکبار نشان داده میشود.نشانی وبهوک را ثبت کنید
آدرسی با https روی سرور شما که پس از هر امضا به آن خبر میدهیم. دکمه «ارسال آزمایشی» یک خبر نمونه میفرستد.
امضای هر درخواست#
خود راز هیچوقت فرستاده نمیشود. بهجایش هر درخواست با راز «مهر» میخورد تا ما بدانیم درخواست واقعاً از شماست و در راه تغییر نکرده.
هر درخواست سه سرآیند دارد:
| سرآیند | چه چیزی |
|---|---|
X-Api-Key | شناسه کلید شما |
X-Timestamp | زمان همین لحظه به ثانیه (Unix)؛ ساعت سرورتان باید درست باشد |
X-Signature | مهر درخواست: v1= و پس از آن HMAC-SHA256 چهار خط زیر با راز |
مهر از این چهار خط ساخته میشود که با یک خط جدید از هم جدا شدهاند:
| خط | چه چیزی | نمونه |
|---|---|---|
| ۱ | مقدار سرآیند X-Timestamp | 1793000000 |
| ۲ | متد HTTP با حروف بزرگ | POST |
| ۳ | مسیر و رشته پرسوجو، دقیقاً همانطور که فرستاده میشود | /api/v1/partner/contracts |
| ۴ | SHA-256 بدنه، هگز با حروف کوچک | 5741c0… |
ساخت قرارداد و پیوند امضا#
با یک درخواست، قرارداد ساخته میشود، آماده امضا میشود و پیوند امضا برمیگردد.
/api/v1/partner/contractsساخت قرارداد برای یک امضاکننده
POST /api/v1/partner/contracts
Content-Type: application/json
Idempotency-Key: merchant-1001
{
"templateId": "01a13ac9-465e-7266-a5c2-d2742cd4202e",
"title": "قرارداد پذیرندگی",
"values": { "company_name": "فروشگاه نمونه", "national_id": "10101234567" },
"signer": {
"displayName": "فروشگاه نمونه",
"mobileNumber": "09121234567",
"nationalCode": "0012345678",
"externalUserId": "merchant-1001"
},
"externalReference": "onboarding-1001",
"returnUrl": "https://shop.example.com/after-sign",
"expiresInMinutes": 60
}| فیلد | یعنی | |
|---|---|---|
templateId | الزامی | کدام قالب |
title | الزامی | عنوان قرارداد |
values | الزامی | مقدار جای خالیهای قالب؛ جای خالیای که قالب به اطلاعات امضاکننده گره زده (نام، کد ملی) لازم نیست و اگر بیاید باید با همان یکی باشد |
signer.displayName | الزامی | نام امضاکننده |
signer.mobileNumber | الزامی | شماره همراه؛ کد تأیید به همین شماره پیامک میشود |
signer.externalUserId | اختیاری | شناسه کاربر در سامانه شما؛ در خبر امضا برمیگردد |
signer.nationalCode | اختیاری | کد ملی امضاکننده؛ اگر قالب آن را در متن دارد الزامی است. امضاکننده پیش از امضا همین کد را وارد میکند |
externalReference | اختیاری | شماره سفارش یا پرونده در سامانه شما |
returnUrl | اختیاری | کاربر پس از امضا به این نشانی برمیگردد (https) |
expiresInMinutes | اختیاری | مهلت پیوند به دقیقه؛ از ۵ دقیقه تا ۳ روز (۴۳۲۰)، پیشفرض ۱ ساعت (۶۰) |
پاسخ
{
"contractId": "…",
"partyId": "…",
"sessionId": "…",
"url": "https://sign-app.beta.sellerzone.ir/s/…",
"expiresAtUtc": "…",
"replayed": false
}- کاربر را به
urlبفرستید. صفحه امضا روی دامنه برند شما باز میشود؛ در نمونه بالا نشانی محیط آزمایشی آمده است. contractIdوpartyIdرا نگه دارید؛ اگر پیوند منقضی شد، برای پیوند تازه لازماند.
سرآیند Idempotency-Key
برای هر قرارداد یک کلید یکتا بفرستید، مثلاً شماره پرونده. اگر پاسخ به شما نرسید، همان درخواست را با همان کلید دوباره بفرستید: قرارداد دوم ساخته نمیشود و همان قبلی با پیوند تازه برمیگردد.
گرفتن نتیجه امضا#
کاربر پیوند را باز میکند، بار اول هویتش تأیید میشود، امضا میکند و کد پیامکشده را میزند. بعد دو اتفاق میافتد:
کاربر برمیگردد
مرورگربهreturnUrlکه فرستاده بودید. این فقط برای راحتی کاربر است؛ به آن بهعنوان نشانه امضا اعتماد نکنید.سرور شما خبر میگیرد
Webhookیک درخواست POST به نشانی وبهوک شما میآید. نشانه قطعی امضا همین است.
دو نوع خبر
| خبر | کی میآید |
|---|---|
signing_session.completed | پس از امضای هر امضاکننده |
contract.completed | وقتی همه امضاکنندههای قرارداد امضا کردهاند |
{
"id": "0199…",
"type": "signing_session.completed",
"createdAt": "2026-10-14T14:12:30+00:00",
"data": {
"sessionId": "…", "contractId": "…",
"externalUserId": "customer-42", "externalReference": "order-1001",
"signerMobileMasked": "0912***4567",
"contentHash": "5741…", "signedAt": "2026-10-14T14:12:29+00:00",
"partyId": "…"
}
}{
"id": "0199…",
"type": "contract.completed",
"createdAt": "2026-10-14T14:12:40+00:00",
"data": {
"contractId": "…", "contentHash": "5741…", "completedAt": "2026-10-14T14:12:29+00:00",
"signers": [
{ "partyId": "…", "externalUserId": "merchant-1001", "sessionId": "…", "signedAt": "2026-10-14T14:12:29+00:00" }
]
}
}زمانها در خبر همیشه میلادی و به وقت UTC (بهصورت ISO 8601) میآیند. اگر در سامانه خودتان تاریخ شمسی نشان میدهید، تبدیلش با شماست.
با خبر چه کنید
مطمئن شوید از طرف ما آمده
سرآیندX-Webhook-Signatureرا با راز Webhook بسنجید. نمونه کد آماده پایین صفحه این کار را میکند.تکراری را کنار بگذارید
شناسه id هر خبر را نگه دارید؛ یک خبر ممکن است دوبار برسد.سریع جواب دهید
ظرف ۱۰ ثانیه پاسخ 200 بدهید و کار سنگین را بعداً انجام دهید.
وقتی امضاکننده شرکت است#
اگر طرف قرارداد یک شرکت با چند صاحب امضاست، بهجای signer بخش legalParty را بفرستید.
"legalParty": {
"legalName": "شرکت نمونه",
"nationalId": "10101234567",
"signatureType": "Simple",
"signatories": [
{
"displayName": "علی رضایی",
"position": "مدیرعامل",
"nationalCode": "0012345678",
"mobileNumber": "09121234567",
"externalUserId": "ceo-1001"
},
{
"displayName": "سارا احمدی",
"position": "عضو هیئتمدیره",
"nationalCode": "0087654321",
"mobileNumber": "09351234567"
}
]
}- همه صاحبان امضا (۱ تا ۱۰ نفر) باید امضا کنند و هر کدام پیوند خودش را میگیرد.
- هر نفر پیش از امضا کد ملیاش را میزند؛ باید با کد ملیای که شما فرستادهاید یکی باشد.
- مهر شرکت لازم است و نفر اول آن را میزند.
نمونه کد آماده#
ساخت قرارداد و سنجش خبر امضا. سه مقدار SIGN_API_BASE، SIGN_API_KEY و SIGN_API_SECRET را در تنظیمات سرورتان بگذارید.
import crypto from "node:crypto";
async function issueContract(payload, idempotencyKey) {
const path = "/api/v1/partner/contracts";
const body = JSON.stringify(payload);
const ts = Math.floor(Date.now() / 1000).toString();
const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
const signature = "v1=" + crypto.createHmac("sha256", process.env.SIGN_API_SECRET)
.update(`${ts}\nPOST\n${path}\n${bodyHash}`).digest("hex");
const res = await fetch(process.env.SIGN_API_BASE + path, {
method: "POST",
body,
headers: {
"Content-Type": "application/json",
"X-Api-Key": process.env.SIGN_API_KEY,
"X-Timestamp": ts,
"X-Signature": signature,
"Idempotency-Key": idempotencyKey,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
return res.json(); // { contractId, partyId, sessionId, url, … }
}
function verifyWebhook(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`).digest("hex");
return parts.v1?.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
&& Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
}وقتی چیزی درست پیش نرفت#
| اگر… | چه کنید |
|---|---|
| پاسخ درخواست نرسید | همان درخواست را با همان Idempotency-Key دوباره بفرستید. |
| پیوند منقضی شد | برای همان طرف پیوند تازه بخواهید: POST /api/v1/partner/signing-sessions با contractId و partyId. |
| خبر امضا نرسید | وضعیت را خودتان بخوانید: GET /api/v1/partner/signing-sessions/{sessionId} |
| درخواستها رد میشوند (429) | بیش از ۳۰۰ درخواست در دقیقه با یک کلید فرستادهاید؛ کمی صبر کنید. |
خطاهای رایج
هر خطا یک code دارد؛ برنامهتان را روی همین کد بنویسید، نه روی متن پیام.
integration.auth.signature_invalid
integration.auth.timestamp_out_of_range
integration.auth.invalid_key
contracts.template.not_published
contracts.template.placeholder_missing
contracts.idempotency_key_reused
features.disabled
ابزارها و مرجع کامل#
همه مسیرها زیر نشانی پایه زیرند.
https://emzamoon.ir/apiنشانی پایه API
فهرست کامل مسیرها، مدلها و همه کدهای خطا در سند OpenAPI است و از روی همان میشود کلاینت ساخت. در محیط آزمایشی، مرجع تعاملی هم هست که درخواستها را همانجا امتحان میکنید:
سند OpenAPI
مرجع تعاملی