پرش به محتوای اصلی
امضامون

راهنمای توسعه‌دهندگان

اتصال سامانه شما به امضا: گام‌ها، نمونه کد آماده و راه‌حل خطاهای رایج.

فهرست مطالب
  1. در یک نگاه
  2. پیش از شروع
  3. امضای هر درخواست
  4. ساخت قرارداد و پیوند امضا
  5. گرفتن نتیجه امضا
  6. وقتی امضاکننده شرکت است
  7. نمونه کد آماده
  8. وقتی چیزی درست پیش نرفت
  9. ابزارها و مرجع کامل

در یک نگاه#

فرض کنید فروشگاه یا پلتفرمی دارید و می‌خواهید کاربرانتان قرارداد را آنلاین امضا کنند، بی‌آنکه خودتان سیستم امضا بسازید. کار سه طرف دارد:

۱

سرور شما

از ما قرارداد و «پیوند امضا» می‌گیرد.

۲

کاربر شما

پیوند را باز می‌کند، متن را می‌خواند و امضا می‌کند.

۳

سامانه امضا

پس از امضا، خودکار به سرور شما خبر می‌دهد.

پیش از شروع#

این سه کار را مدیر سازمان یک‌بار در پنل انجام می‌دهد.

  1. یک قالب قرارداد بسازید و منتشر کنید

    هر جایی از متن که برای هر کاربر فرق می‌کند، یک جای خالی (جای‌نگهدار) بگذارید؛ مثل {{company_name}}. شناسه قالب و نام جای خالی‌ها را بردارید.
  2. یک کلید API بسازید

    در سازمان مناتصال API. کلید دو تکه دارد: شناسه (ak_…) که مثل نام کاربری است، و راز (sk_…) که مثل رمز است و فقط یک‌بار نشان داده می‌شود.
  3. نشانی وب‌هوک را ثبت کنید

    آدرسی با https روی سرور شما که پس از هر امضا به آن خبر می‌دهیم. دکمه «ارسال آزمایشی» یک خبر نمونه می‌فرستد.

امضای هر درخواست#

خود راز هیچ‌وقت فرستاده نمی‌شود. به‌جایش هر درخواست با راز «مهر» می‌خورد تا ما بدانیم درخواست واقعاً از شماست و در راه تغییر نکرده.

هر درخواست سه سرآیند دارد:

سرآیندچه چیزی
X-Api-Keyشناسه کلید شما
X-Timestampزمان همین لحظه به ثانیه (Unix)؛ ساعت سرورتان باید درست باشد
X-Signatureمهر درخواست: v1= و پس از آن HMAC-SHA256 چهار خط زیر با راز

مهر از این چهار خط ساخته می‌شود که با یک خط جدید از هم جدا شده‌اند:

خطچه چیزینمونه
۱مقدار سرآیند X-Timestamp1793000000
۲متد HTTP با حروف بزرگPOST
۳مسیر و رشته پرس‌وجو، دقیقاً همان‌طور که فرستاده می‌شود/api/v1/partner/contracts
۴SHA-256 بدنه، هگز با حروف کوچک5741c0…

ساخت قرارداد و پیوند امضا#

با یک درخواست، قرارداد ساخته می‌شود، آماده امضا می‌شود و پیوند امضا برمی‌گردد.

POST/api/v1/partner/contracts

ساخت قرارداد برای یک امضاکننده

HTTPنمونه درخواست
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اختیاریمهلت پیوند به دقیقه؛ از ۵ دقیقه تا ۳ روز (۴۳۲۰)، پیش‌فرض ۱ ساعت (۶۰)

پاسخ

JSONپاسخ 201
{
  "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وقتی همه امضاکننده‌های قرارداد امضا کرده‌اند
JSONنمونه: signing_session.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": "…"
  }
}
JSONنمونه: contract.completed
{
  "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) می‌آیند. اگر در سامانه خودتان تاریخ شمسی نشان می‌دهید، تبدیلش با شماست.

با خبر چه کنید

  1. مطمئن شوید از طرف ما آمده

    سرآیند X-Webhook-Signature را با راز Webhook بسنجید. نمونه کد آماده پایین صفحه این کار را می‌کند.
  2. تکراری را کنار بگذارید

    شناسه id هر خبر را نگه دارید؛ یک خبر ممکن است دوبار برسد.
  3. سریع جواب دهید

    ظرف ۱۰ ثانیه پاسخ 200 بدهید و کار سنگین را بعداً انجام دهید.

وقتی امضاکننده شرکت است#

اگر طرف قرارداد یک شرکت با چند صاحب امضاست، به‌جای signer بخش legalParty را بفرستید.

JSONبخش 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
مهر درخواست درست نیست. معمولاً مهر روی متن دیگری ساخته شده، مثلاً JSON پیش از آنکه دوباره ساخته شود یا با فاصله‌گذاری دیگر. دقیقاً همان متنی را مهر کنید که می‌فرستید.
integration.auth.timestamp_out_of_range
ساعت سرور شما بیش از ۵ دقیقه با ساعت ما فرق دارد. ساعت سرور را همگام کنید.
integration.auth.invalid_key
کلید ناشناخته است یا باطل شده. شناسه کلید را در پنل بررسی کنید.
contracts.template.not_published
قالب هنوز منتشر نشده است؛ از پنل منتشرش کنید.
contracts.template.placeholder_missing
مقدار یکی از جای خالی‌های قالب در values نیامده است.
contracts.idempotency_key_reused
همان Idempotency-Key را با درخواست دیگری فرستاده‌اید؛ برای هر قرارداد کلید تازه بگذارید.
features.disabled
این امکان برای سازمان شما خاموش است. مدیر سازمان از «قابلیت‌های سازمان» روشنش می‌کند، یا با پشتیبانی تماس بگیرید.

ابزارها و مرجع کامل#

همه مسیرها زیر نشانی پایه زیرند.

https://emzamoon.ir/api

نشانی پایه API

فهرست کامل مسیرها، مدل‌ها و همه کدهای خطا در سند OpenAPI است و از روی همان می‌شود کلاینت ساخت. در محیط آزمایشی، مرجع تعاملی هم هست که درخواست‌ها را همان‌جا امتحان می‌کنید: