مستندات فنی وب‌سرویس همکاران (Partner API)

راهنمای پیاده‌سازی سریع B2B جهت استعلام کاتالوگ گیفت‌کارت‌ها، تسویه با والت ریالی و تحویل آنی کارت.

Base URL

https://partner.melligift.net/v1/partner

۱. امنیت و احراز هویت

احراز هویت و امضای دیجیتال (HMAC-SHA256)

هر درخواست باید حاوی هدرهای زیر باشد. امضا با کلید سکرت شما به روش HMAC-SHA256 تولید می‌شود.

هدر (Header)	مقدار نمونه	توضیح
`X-API-Key`	`pk_live_xxxxxx`	شناسه کلید شما (از پنل همکاران)
`X-Timestamp`	`1726830000`	زمان ارسال به ثانیه یونیکس (حداکثر اختلاف مجاز ۶۰ ثانیه)
`X-Nonce`	`UUIDv4`	رشته تصادفی یکتا برای هر درخواست (ضد تکرار)
`X-Signature-Version`	`1`	نسخه امضا (همیشه عدد `1`)
`X-Signature`	`هش هگزادسیمال`	محاسبه HMAC-SHA256 طبق فرمول زیر

نحوه ساخت رشته متنی امضا (دقیقاً ۹ خط، جدا شده با Enter یا \n):

خط ۱:MG-HMAC-SHA256-V1(مقدار ثابت نسخه پروتکل)

خط ۲:{X-API-Key}(کلید عمومی همکار)

خط ۳:{METHOD}(متد با حروف بزرگ: GET یا POST)

خط ۴:{PATH}(مسیر بدون دامین: مثلاً /v1/partner/catalog)

خط ۵:{QUERY}(کوئری مرتب‌شده یا خط خالی در صورت نبودن)

خط ۶:{X-Timestamp}(زمان ارسال به ثانیه)

خط ۷:{X-Nonce}(رشته رندوم UUID)

خط ۸:{Idempotency-Key}(کلید یکتا در POST یا خط خالی در GET)

خط ۹:{SHA256(BODY)}(هش بادی JSON، یا هش رشته خالی در متد GET)

نمونه رشته نهایی برای یک درخواست GET ساده:

MG-HMAC-SHA256-V1
pk_live_a1b2c3d4e5
GET
/v1/partner/catalog

1726830000
9c8a7b6c-5d4e-3f2a-1b0c-9d8e7f6a5b4c

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

کد آماده تولید امضا در زبان‌های مختلف:

// در جاوااسکریپت / Node.js:
const stringToSign = [
  'MG-HMAC-SHA256-V1',
  apiKey,
  method.toUpperCase(),
  path,
  query || '',
  timestamp,
  nonce,
  idempotencyKey || '',
  crypto.createHash('sha256').update(body ? JSON.stringify(body) : '').digest('hex')
].join('\n');

const signature = crypto.createHmac('sha256', secretKey).update(stringToSign).digest('hex');

* کاراکتر \n همان اینتر (Line Feed) است. تابع join('\n') آرایه ۹ عنصری بالا را دقیقاً به شکل خط به خط به هم متصل می‌کند.

۲. کنترل ترافیک

سهمیه درخواست‌ها (Rate Limit)

سهمیه مصرفی به صورت چرخه‌های ۶۰ ثانیه‌ای بر اساس نوع مسیر محاسبه می‌شود:

۶۰ در دقیقه

کاتالوگ و محصولات (GET /catalog)

۳۰ در دقیقه

ثبت و رهگیری سفارش (POST /orders)

۲۰ در دقیقه

دریافت کد تحویل (GET /redemption)

نحوه مدیریت خطای ۴۲۹ (Too Many Requests):در صورت عبور از سقف، سرور پاسخ 429 به همراه هدر Retry-After: ثانیه می‌دهد. کافی است کلاینت شما به مدت مقدار این هدر مکث کند و سپس دوباره درخواست را بفرستد.

GET/catalogاسکوپ: catalog:read

کاتالوگ محصولات با کش هوشمند (ETag)

دریافت لیست کلیه گیفت‌کارت‌های فعال با قیمت ویژه همکار.

قیمت همکار (price_irr):قیمت‌ها به ریال است. عدد price_irr قیمت نهایی است.

کش هوشمند ETag:برای صرفه‌جویی و دریافت پاسخ زیر ۱۰ میلی‌ثانیه، مقدار ETag دریافتی را در درخواست‌های بعدی در هدر If-None-Match بفرستید. در صورت عدم تغییر، سرور پاسخ سبک 304 Not Modified با حجم صفر بایت می‌دهد.

نمونه پاسخ سرور (200 OK):

{
  "products": [
    {
      "id": "cm1apple_us_01",
      "name": "گیفت کارت اپل آمریکا",
      "brand": "Apple",
      "region_code": "US",
      "currency": "USD",
      "cover_url": "https://melligift.net/images/products/apple.webp",
      "denominations": [
        {
          "face_value": "10",
          "face_value_currency": "USD",
          "price_irr": "8500000",
          "is_available": true
        },
        {
          "face_value": "25",
          "face_value_currency": "USD",
          "price_irr": "21250000",
          "is_available": true
        }
      ]
    }
  ]
}

GET/catalog/products/:idاسکوپ: catalog:read

استعلام مشخصات و تفکیک قیمت محصول

دریافت قیمت لحظه‌ای و جزئیات تفکیک هزینه (Breakdown) پیش از خرید:

{
  "id": "cm1apple_us_01",
  "name": "گیفت کارت اپل آمریکا",
  "denominations": [
    {
      "face_value": "10",
      "price_irr": "8500000",
      "is_available": true,
      "breakdown": {
        "cost_irr": "8100000",
        "margin_irr": "400000",
        "tax_irr": "0",
        "total_irr": "8500000"
      }
    }
  ]
}

* cost_irr هزینه ارز تامین‌کننده، margin_irr سود همکار، و total_irr مبلغ نهایی کسرشده از والت است.

POST/ordersاسکوپ: orders:create

ثبت سفارش خرید با والت ریالی

کسر از کیف پول و ارسال سفارش به صف تحویل. ارسال هدر Idempotency-Key: UUID الزامی است تا در صورت قطعی اینترنت وجه دوبار کسر نگردد.

بادی ارسالی (JSON Request Body):

{
  "external_reference": "INV-10928",
  "product_id": "cm1apple_us_01",
  "face_value": 10,
  "face_value_currency": "USD",
  "quantity": 1,
  "expected_total": "8500000",
  "currency": "IRR",
  "allow_price_change": false
}

پاسخ سرور (HTTP 202 ACCEPTED):

{
  "order_id": "ord_pt_89410214",
  "external_reference": "INV-10928",
  "status": "PROCESSING",
  "wallet_debited_amount": "8500000",
  "currency": "IRR",
  "created_at": "2026-09-20T10:20:15.112Z"
}

استعلام وضعیت سفارش:

GET/orders/:idیا /orders/by-reference/:external_reference

وقتی فیلد status برابر با COMPLETED شد، کد کارت آماده تحویل است.

GET/orders/:id/redemptionاسکوپ: redemption:read

دریافت امن پین و سریال گیفت کارت

پس از تکمیل سفارش (وضعیت COMPLETED)، پین کارت را از این اندپوینت دریافت کنید (پاسخ فاقد کش و امن است).

{
  "order_id": "ord_pt_89410214",
  "external_reference": "INV-10928",
  "pin": "X89M-92AL-P44K-W10Z",
  "redemption_payload": {
    "code": null,
    "pin": "X89M-92AL-P44K-W10Z",
    "serial": "SN-99824102",
    "link": null,
    "status": "resolved"
  },
  "cards": [],
  "fulfilled_at": "2026-09-20T10:20:18.450Z"
}

POST/webhooks/endpointsاسکوپ: orders:read

وب‌هوک‌های لحظه‌ای (Webhooks)

به جای استعلام مداوم، یک آدرس از سرور خود ثبت کنید تا پس از صدور کارت، رویداد order.completed به شما ارسال شود.

هدرهای ارسالی در وب‌هوک:x-melli-signature: امضای HMAC بدنه با سکرت وب‌هوک شما
x-melli-timestamp: زمان ارسال یونیکس

پاسخ سرور شما:اندپوینت شما باید پاسخ 200 OK در کمتر از ۵ ثانیه بازگرداند.

۸. رفع اشکال

کدهای خطای متداول

کد HTTP	شناسه خطا	راهکار سریع
`401`	`AUTHENTICATION_FAILED`	بررسی فرمول هش HMAC یا تطابق API Key
`401`	`REQUEST_EXPIRED`	تنظیم ساعت سرور با پروتکل NTP (اختلاف بیش از ۶۰ ثانیه)
`401`	`REPLAY_DETECTED`	نانس تکراری است؛ برای هر ریکوئست نانس جدید تولید کنید
`409`	`INSUFFICIENT_BALANCE`	موجودی ریالی والت ناکافی است؛ شارژ کیف پول همکار
`409`	`IDEMPOTENCY_CONFLICT`	این Idempotency-Key قبلاً با مشخصات متفاوتی ارسال شده
`409`	`PRICE_CHANGED`	قیمت ارز محصول تغییر کرده است؛ استعلام مجدد قیمت
`429`	`RATE_LIMITED`	عبور از سقف؛ به مدت مقدار هدر `Retry-After` مکث کنید

محصولات دسته‌بندی گیفت کارت بازی

محصولات دسته‌بندی گیفت کارت اپلیکیشن

محصولات دسته‌بندی پرداخت آنلاین