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

مستندات اتصال به Partner API

دریافت کاتالوگ، خرید با کیف پول ریالی، پیگیری سفارش و دریافت اطلاعات کارت.

شروع اتصال

دامنه رسمی API: partner.melligift.net. تمام مسیرهای این صفحه به آدرس پایه زیر افزوده می‌شوند.

Base URLhttps://partner.melligift.net/api/v1/partner
  1. درخواست‌ها را از سرور کلاینت و با HTTPS ارسال کنید. کلید محرمانه را در مرورگر، اپلیکیشن عمومی یا مخزن کد قرار ندهید.
  2. کاتالوگ و قیمت محصول را دریافت کنید؛ سپس خرید را با مرجع و کلید یکتا ثبت کنید.
  3. تکمیل سفارش را از وب‌هوک یا مسیر پیگیری دریافت و اطلاعات کارت را جداگانه بخوانید.

نمونه‌های پاسخ فقط ساختار API را نشان می‌دهند. شناسه‌ها و مبالغ واقعی را از پاسخ دریافت کنید. تمام مبالغ پرداختی به ریال و به صورت رشته عددی هستند؛ تاریخ‌های پاسخ در قالب ISO 8601 ارائه می‌شوند.

مرجع مسیرها

تمام مسیرها نیازمند کلید معتبر و امضای درخواست هستند. مقادیر :id و :external_reference را با شناسه واقعی جایگزین و برای قرار گرفتن در مسیر URL encode کنید.

مسیرهای Partner API
متدمسیردسترسیپاسخ موفقکاربرد
GET/statusکلید معتبر200وضعیت سرویس و دسترسی خرید
GET/walletwallet:read200موجودی قابل استفاده به ریال
GET/catalogcatalog:read200 / 304فهرست محصولات و مبالغ قابل خرید
GET/catalog/products/:idcatalog:read200جزئیات و قیمت محصول
POST/ordersorders:create202ثبت یا بازیابی همان درخواست خرید
GET/ordersorders:read200فهرست سفارش‌ها
GET/orders/:idorders:read200جزئیات یک سفارش
GET/orders/by-reference/:external_referenceorders:read200بازیابی سفارش با مرجع همکار
GET/orders/:id/redemptionredemption:read200دریافت اطلاعات کارت
GET/webhooks/endpointsorders:read200فهرست مقصدهای وب‌هوک
POST/webhooks/endpointsorders:read201ثبت مقصد وب‌هوک
PATCH/webhooks/endpoints/:idorders:read200ویرایش مقصد وب‌هوک
DELETE/webhooks/endpoints/:idorders:read200حذف مقصد وب‌هوک
POST/webhooks/endpoints/:id/testorders:read201درخواست ارسال رویداد آزمایشی

ساختار پاسخ

داده پاسخ موفق در data قرار دارد. request_id شناسه پیگیری درخواست است. فیلدهای اضافی پاسخ را نادیده بگیرید و شناسه‌ها را بدون تغییر نگهداری کنید.

نمونه پاسخ موفق — 200
JSON
{
  "success": true,
  "request_id": "req_example",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "data": {
    "available_balance": "25000000",
    "currency": "IRR"
  }
}
نمونه پاسخ خطا — 409
JSON
{
  "success": false,
  "request_id": "req_example",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "error": {
    "code": "PRICE_CHANGED",
    "message": "قیمت محصول تغییر کرده است.",
    "action_hint": "قیمت محصول را دوباره دریافت کنید.",
    "retryable": false,
    "details": {
      "expected_total": "8500000",
      "current_total": "8600000",
      "currency": "IRR"
    }
  }
}

پاسخ 304 بدنه ندارد. برای درخواست دارای خطا، error.code، وضعیت HTTP و در صورت وجود Retry-After را بررسی کنید. فیلدdetails اختیاری است.

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

برای هر درخواست، هدرهای زیر را ارسال کنید. از متن کامل کلید محرمانه دریافتی به عنوان کلید امضا استفاده کنید؛ پیشوند آن را حذف یا مقدار آن را decode نکنید.

هدرهای درخواست
هدرمقدار
X-API-Keyشناسه کلید دریافتی برای حساب همکار
X-Timestampزمان جاری یونیکس به ثانیه؛ ساعت سرور کلاینت باید همگام باشد
X-Nonceمقدار تصادفی تازه برای هر درخواست؛ UUID توصیه می‌شود
X-Signature-Versionمقدار 1
X-Signatureامضای درخواست طبق قرارداد این بخش؛ رشته hex
Content-Typeapplication/json برای درخواست‌های دارای بدنه
Idempotency-Keyبرای POST /orders الزامی؛ یک کلید یکتا برای هر خرید مستقل
X-Request-Idاختیاری؛ حروف لاتین، عدد و . _ : -، حداکثر ۱۲۸ کاراکتر

رشته امضا از ۹ مقدار زیر تشکیل می‌شود؛ مقادیر با \n (LF) جدا می‌شوند و انتهای رشته newline ندارد. امضا برابر HMAC-SHA256(secret, stringToSign) با خروجی hex است.

قرارداد رشته امضا
خطمقدارتوضیح
1MG-HMAC-SHA256-V1مقدار ثابت
2X-API-Keyشناسه کلید، عین مقدار هدر
3METHODمتد با حروف بزرگ: GET، POST، PATCH یا DELETE
4PATHمسیر کامل بدون دامنه و کوئری؛ مانند /api/v1/partner/orders
5QUERYکوئری مرتب‌شده، بدون ?؛ در صورت نبود کوئری، رشته خالی
6X-Timestampعین مقدار هدر زمان
7X-Nonceعین مقدار هدر nonce
8Idempotency-Keyعین مقدار هدر؛ در صورت نبود هدر، رشته خالی
9SHA256(rawBody)hex از بایت‌های UTF-8 بدنه ارسالی؛ برای بدنه خالی، SHA256 رشته خالی
  • بدنه را یک بار به JSON تبدیل کنید؛ همان بایت‌های UTF-8 را برای محاسبه امضا و ارسال استفاده کنید. تغییر فاصله‌ها، ترتیب فیلدها یا خط جدید، بدنه متفاوت ایجاد می‌کند.
  • برای GET و DELETE بدون بدنه، رشته خالی را استفاده کنید. مسیر امضا باید شامل /api/v1/partner باشد.
  • در کوئری، نام کلیدها را به ترتیب صعودی مرتب کنید؛ نام و مقدار را جداگانه با encodeURIComponent تبدیل و با & متصل کنید. فاصله به %20 تبدیل می‌شود. پارامتر تکراری، آرایه یا شیء ارسال نکنید.
  • برای نمونه، کوئری فهرست سفارش‌ها به شکل limit=20&page=2&status=PROCESSING امضا و ارسال می‌شود.
  • هر ارسال، حتی تکرار خرید یا دریافت پاسخ 304، به زمان، nonce و امضای تازه نیاز دارد. اختلاف مجاز ساعت ۶۰ ثانیه است؛ ساعت سرور را همگام نگه دارید.

نمونه کامل تولید امضا و ارسال درخواست در بخش بعد قرار دارد.

نمونه کلاینت Node.js

نمونه زیر با Node.js 20 یا جدیدتر و بدون وابستگی اضافه اجرا می‌شود. کلیدها را در متغیرهای محیطی PARTNER_API_KEY و PARTNER_API_SECRET قرار دهید. درخواست خرید به صورت خودکار تکرار نمی‌شود.

دریافت کاتالوگ — ذخیره در example.mjs
JavaScript
import { PartnerClient } from './partner-client.mjs';

const client = new PartnerClient({
  apiKey: process.env.PARTNER_API_KEY,
  secret: process.env.PARTNER_API_SECRET,
});

const { data, etag } = await client.request('GET', '/catalog');
console.log(data.products);

// درخواست بعدی، با همان کلاینت و ETag قبلی
const next = await client.request('GET', '/catalog', { etag });
if (!next.notModified) console.log(next.data.products);
اجرا
Shell
node example.mjs
کد کامل کلاینت
partner-client.mjs
JavaScript
import { createHash, createHmac, randomUUID } from 'node:crypto';

export class PartnerClient {
  #apiKey;
  #secret;
  #baseUrl;

  constructor({ apiKey, secret, baseUrl = 'https://partner.melligift.net/api/v1/partner' } = {}) {
    if (typeof apiKey !== 'string' || !apiKey || /[^\x21-\x7e]/.test(apiKey) ||
        typeof secret !== 'string' || !secret.trim()) {
      throw new Error('Valid API credentials are required');
    }
    let url;
    try {
      if (typeof baseUrl !== 'string') throw new Error();
      url = new URL(baseUrl);
      if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) {
        throw new Error();
      }
    } catch {
      throw new Error('baseUrl must be an HTTPS URL without credentials, query or fragment');
    }
    this.#apiKey = apiKey;
    this.#secret = secret;
    this.#baseUrl = url.href.replace(/\/+$/, '');
  }

  async request(method, path, { query = {}, body, idempotencyKey = '', etag, timeoutMs = 15000 } = {}) {
    if (typeof method !== 'string' || !['GET', 'POST', 'PATCH', 'DELETE'].includes(method.toUpperCase()) ||
        typeof path !== 'string' || !path.startsWith('/') || path.startsWith('//') ||
        /[\\?#\s\u0000-\u001f\u007f]/.test(path)) {
      throw new Error('Invalid request method or path');
    }
    if (!query || typeof query !== 'object' || Array.isArray(query) ||
        Object.values(query).some((value) => value != null &&
          (!['string', 'number', 'boolean'].includes(typeof value) ||
            (typeof value === 'number' && !Number.isFinite(value))))) {
      throw new Error('Query values must be strings, finite numbers or booleans');
    }
    if (typeof idempotencyKey !== 'string' || /[^\x21-\x7e]/.test(idempotencyKey) ||
        (etag !== undefined && (typeof etag !== 'string' || /[^\x20-\x7e]/.test(etag))) ||
        !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) {
      throw new Error('Invalid request headers or timeout');
    }
    method = method.toUpperCase();
    const url = new URL(this.#baseUrl + path);
    if (url.href !== this.#baseUrl + path) throw new Error('Request path must be URL-encoded without dot segments');
    const canonicalQuery = Object.keys(query).sort()
      .filter((key) => query[key] !== undefined && query[key] !== null)
      .map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(String(query[key]))}`)
      .join('&');
    url.search = canonicalQuery;

    let rawBody;
    try {
      rawBody = body === undefined ? '' : JSON.stringify(body);
      if (typeof rawBody !== 'string') throw new Error();
    } catch {
      throw new Error('Request body must be JSON-serializable');
    }
    const timestamp = String(Math.floor(Date.now() / 1000));
    const nonce = randomUUID();
    const canonical = [
      'MG-HMAC-SHA256-V1', this.#apiKey, method, url.pathname, canonicalQuery,
      timestamp, nonce, idempotencyKey,
      createHash('sha256').update(rawBody, 'utf8').digest('hex'),
    ].join('\n');

    const headers = {
      'Accept': 'application/json',
      'X-API-Key': this.#apiKey,
      'X-Timestamp': timestamp,
      'X-Nonce': nonce,
      'X-Signature-Version': '1',
      'X-Signature': createHmac('sha256', this.#secret).update(canonical, 'utf8').digest('hex'),
    };
    if (body !== undefined) headers['Content-Type'] = 'application/json';
    if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
    if (etag) headers['If-None-Match'] = etag;

    const signal = AbortSignal.timeout(timeoutMs);
    let response;
    try {
      response = await fetch(url, {
        method, headers,
        ...(body !== undefined ? { body: rawBody } : {}),
        signal,
        redirect: 'error',
      });
    } catch {
      const error = new Error(signal.aborted ? 'Request timed out' : 'Request could not be completed');
      error.code = signal.aborted ? 'TIMEOUT' : 'CONNECTION_ERROR';
      throw error;
    }
    const metadata = {
      status: response.status,
      etag: response.headers.get('etag'),
      requestId: this.#redact(response.headers.get('x-request-id')),
      rateLimit: response.headers.get('x-ratelimit-limit'),
      rateRemaining: response.headers.get('x-ratelimit-remaining'),
      rateResetSeconds: response.headers.get('x-ratelimit-reset'),
    };
    if (response.status === 304) return { ...metadata, notModified: true };

    const envelope = await response.json().catch(() => null);
    if (!response.ok || envelope?.success !== true) {
      const message = envelope?.error?.message;
      const retryAfter = Number(response.headers.get('retry-after') || 0);
      const error = new Error(typeof message === 'string' ? this.#redact(message) : `HTTP ${response.status}`);
      Object.assign(error, {
        status: response.status,
        code: this.#redact(envelope?.error?.code),
        requestId: this.#redact(envelope?.request_id || metadata.requestId),
        retryable: envelope?.error?.retryable === true,
        retryAfterSeconds: Number.isFinite(retryAfter) && retryAfter >= 0 ? Math.ceil(retryAfter) : 0,
        details: this.#redact(envelope?.error?.details),
      });
      throw error;
    }
    return { ...metadata, requestId: this.#redact(envelope.request_id), data: envelope.data };
  }

  #redact(value, depth = 0) {
    if (typeof value === 'string') {
      for (const credential of [this.#secret, this.#apiKey]) value = value.split(credential).join('[redacted]');
      return value.replace(/https?:\/\/[^\s<>"']+/gi, '[redacted]').slice(0, 2048);
    }
    if (value === null || typeof value !== 'object') return value;
    if (depth > 4) return '[truncated]';
    if (Array.isArray(value)) return value.slice(0, 20).map((item) => this.#redact(item, depth + 1));
    return Object.fromEntries(Object.entries(value).slice(0, 40).map(([key, item]) => {
      const name = key.replace(/[^a-z]/gi, '').toLowerCase();
      const sensitive = /secret|signature|authorization|cookie|token|pin|serial|redemption|credential|body|headers|password|apikey|cardnumber/.test(name) ||
        ['code', 'link', 'additionalinfo', 'instructions'].includes(name);
      return [this.#redact(key), sensitive ? '[redacted]' : this.#redact(item, depth + 1)];
    }));
  }
}

در زبان‌های دیگر نیز همین قرارداد هدرها، مسیر، کوئری و بایت‌های بدنه را رعایت کنید. مبلغ ریالی را با محاسبات اعشاری دقیق پردازش کنید؛ تبدیل آن به عدد ممیز شناور ممکن است دقت را کاهش دهد.

محدودیت درخواست‌ها

سقف درخواست برای هر حساب تنظیم می‌شود و بین کلیدهای همان حساب مشترک است. مقدار معتبر هر پاسخ را از هدرها بخوانید.

گروه‌های سهمیه درخواست
گروهمسیرهای دارای سهمیه مشترک
خواندنکاتالوگ، جزئیات محصول، وضعیت، موجودی و فهرست مقصدهای وب‌هوک
سفارشثبت، فهرست و پیگیری سفارش؛ ثبت، ویرایش، حذف و تست مقصد وب‌هوک
تحویلدریافت اطلاعات کارت
هدرهای محدودیت درخواست
هدرمعنا
X-RateLimit-Limitسقف درخواست در بازه جاری
X-RateLimit-Remainingتعداد درخواست باقی‌مانده
X-RateLimit-Resetثانیه باقی‌مانده تا بازه بعد؛ زمان یونیکس نیست
Retry-Afterدر پاسخ 429: مدت انتظار به ثانیه

بازه سهمیه ۶۰ ثانیه است. پس از خطای 429، تا پایان Retry-After منتظر بمانید و درخواست را با امضای تازه ارسال کنید. پاسخ 304 و پیگیری سفارش نیز از سهمیه مصرف می‌کنند.

وضعیت سرویس و موجودی

GET /status

وضعیت و امکان خرید را دریافت کنید. این مسیر به دسترسی اختصاصی نیاز ندارد؛ کلید معتبر و امضا الزامی هستند.

پاسخ وضعیت — 200
JSON
{
  "success": true,
  "request_id": "req_example",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "data": {
    "status": "OPERATIONAL",
    "purchase_enabled": true,
    "server_time": "2026-10-10T09:00:00.000Z",
    "message": null
  }
}

وضعیت سرویس می‌تواند OPERATIONAL، PURCHASE_PAUSED، SUSPENDED یا MAINTENANCE باشد. برای ثبت خرید،purchase_enabled را بررسی کنید. غیرفعال بودن سرویس ممکن است با خطای 503 پاسخ داده شود.

GET /wallet

دسترسی: wallet:read. فیلد available_balance موجودی قابل استفاده به ریال است؛ استعلام موجودی به معنی تضمین پذیرش خرید بعدی نیست.

پاسخ موجودی — 200
JSON
{
  "success": true,
  "request_id": "req_example",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "data": {
    "available_balance": "25000000",
    "currency": "IRR"
  }
}

کاتالوگ و قیمت محصول

GET /catalog

دسترسی: catalog:read. محصولات در data.products قرار دارند. کاتالوگ صفحه‌بندی ندارد؛ لیست ممکن است خالی باشد.

پاسخ کاتالوگ — 200
JSON
{
  "success": true,
  "request_id": "req_example",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "data": {
    "products": [
      {
        "id": "7b224e31-4077-4a02-b625-5f376971a9d4",
        "name": "گیفت کارت اپل آمریکا",
        "brand": "Apple",
        "brand_key": "apple",
        "region_code": "US",
        "currency": "USD",
        "denominations": [
          {
            "face_value": "10",
            "face_value_currency": "USD",
            "price_irr": "8500000",
            "tax_irr": "0",
            "is_available": true
          }
        ]
      }
    ]
  }
}
فیلدهای محصول و مبلغ کارت
فیلدمعنا
idشناسه محصول؛ برای خرید و اتصال تصویر در سامانه همکار
name / brand / brand_keyنام محصول، نام برند و کلید برند
region_codeکد ریجن؛ ممکن است null باشد
currencyارز محصول؛ برای خرید
denominationsمبالغ عرضه‌شده برای محصول؛ فقط از گزینه‌های همین فهرست خرید کنید
face_value / face_value_currencyمبلغ اسمی به صورت رشته و ارز آن
price_irrقیمت نهایی یک کارت به ریال، شامل مالیات
tax_irrسهم مالیات از price_irr؛ دوباره به قیمت اضافه نشود
is_availableقابل انتخاب بودن مبلغ کارت؛ موجودی و قیمت هنگام ثبت خرید بررسی می‌شوند

دریافت تغییرات با ETag

مقدار کامل هدر ETag را همراه کاتالوگ ذخیره کنید. در درخواست بعدی، همان مقدار را در If-None-Match ارسال کنید. در پاسخ304 از کاتالوگ ذخیره‌شده استفاده کنید و بدنه را JSON نخوانید. این داده را بین حساب‌های مختلف مشترک نکنید.

GET /catalog/products/:id

دسترسی: catalog:read. پیش از ثبت خرید، جزئیات محصول را دریافت کنید. قیمت دریافت‌شده تضمین ثبات قیمت تا زمان خرید نیست. پذیرش تغییر قیمت تابع تنظیم حساب است؛ مبلغ نهایی را ازtotal_irr پاسخ خرید بخوانید. در صورت نپذیرفتن تغییر قیمت، خطای PRICE_CHANGED دریافت می‌شود.

پاسخ جزئیات محصول — 200
JSON
{
  "success": true,
  "request_id": "req_example",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "data": {
    "id": "7b224e31-4077-4a02-b625-5f376971a9d4",
    "name": "گیفت کارت اپل آمریکا",
    "brand": "Apple",
    "brand_key": "apple",
    "region_code": "US",
    "currency": "USD",
    "denominations": [
      {
        "face_value": "10",
        "face_value_currency": "USD",
        "price_irr": "8500000",
        "tax_irr": "0",
        "is_available": true
      }
    ]
  }
}

ثبت سفارش

POST/ordersorders:create

هدر Idempotency-Key الزامی است. پیش از نخستین ارسال، کلید، مرجع و بدنه خرید را در سامانه خود ذخیره کنید. هر خرید مستقل باید کلید و مرجع مستقل داشته باشد.

فیلدهای ثبت سفارش
فیلدنوعالزامیتوضیح
external_referencestringبلهمرجع یکتا در حساب همکار؛ حداکثر ۱۲۸ کاراکتر
product_idstringبلهشناسه دریافتی از کاتالوگ
face_valuenumberبلهمبلغ اسمی مثبت
face_value_currencystringبلهارز مبلغ اسمی، مانند USD
quantityintegerبلهدر نسخه جاری فقط 1
expected_totalstringبلهعین price_irr؛ مبلغ نهایی مورد انتظار به ریال
currencystringبلهمقدار IRR
بدنه ثبت سفارش
JSON
{
  "external_reference": "INV-10928",
  "product_id": "7b224e31-4077-4a02-b625-5f376971a9d4",
  "face_value": 10,
  "face_value_currency": "USD",
  "quantity": 1,
  "expected_total": "8500000",
  "currency": "IRR"
}
پاسخ پذیرش سفارش — 202
JSON
{
  "success": true,
  "request_id": "req_example",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "data": {
    "order_id": "5e4c461e-e717-46e4-8f5c-07e4e57b4d37",
    "external_reference": "INV-10928",
    "status": "PROCESSING",
    "total_irr": "8500000",
    "tax_irr": "0",
    "currency": "IRR",
    "created_at": "2026-10-10T09:00:00.000Z"
  }
}

پاسخ 202 پذیرش درخواست خرید را اعلام می‌کند؛ تحویل کارت باید جداگانه پیگیری شود. total_irr مبلغ نهایی پذیرفته‌شده و tax_irr سهم مالیات از همان مبلغ است. تکرار درخواست پذیرفته‌شده می‌تواند وضعیت فعلی همان سفارش را برگرداند.

نمونه ساخت درخواست از محصول انتخاب‌شده

ورودی‌های این قطعه شامل محصول و مبلغ انتخابی کاربر، مرجع سفارش و کلید یکتای ذخیره‌شده برای خرید هستند. متغیر client از نمونه کلاینت ساخته می‌شود.

ساخت و ارسال درخواست خرید
JavaScript
// selectedProductId و selectedDenomination از انتخاب کاربر در کاتالوگ هستند.
const { data: product } = await client.request(
  'GET', '/catalog/products/' + encodeURIComponent(selectedProductId),
);
const card = product.denominations.find((item) =>
  item.face_value === selectedDenomination.face_value &&
  item.face_value_currency === selectedDenomination.face_value_currency &&
  item.is_available,
);
if (!card) throw new Error('مبلغ انتخابی قابل خرید نیست');

const body = {
  external_reference: externalReference,
  product_id: product.id,
  face_value: Number(card.face_value),
  face_value_currency: card.face_value_currency,
  quantity: 1,
  expected_total: card.price_irr,
  currency: 'IRR',
};

// پیش از ارسال، body و idempotencyKey را برای همین خرید ذخیره کنید.
const { data: order } = await client.request('POST', '/orders', {
  body, idempotencyKey,
});

تکرار خرید پس از قطعی

  • همان بدنه، external_reference و Idempotency-Key را حفظ کنید؛ فقط زمان، nonce و امضا را تازه تولید کنید.
  • کلید جدید برای خریدی که نتیجه‌اش نامشخص است نسازید. ابتدا سفارش را با مرجع بازیابی کنید.
  • استفاده مجدد از کلید با بدنه متفاوت یا استفاده از مرجع ثبت‌شده با کلید دیگر، خطای IDEMPOTENCY_CONFLICT می‌دهد.
  • در خطای قطعی PRICE_CHANGED، قیمت را دوباره دریافت کنید و پس از تایید خرید، درخواست تازه بسازید. برای نتیجه نامعلوم، ابتدا مسیر بازیابی را استفاده کنید.

پیگیری و بازیابی سفارش

دسترسی: orders:read. یک سفارش را با یکی از دو مسیر زیر دریافت کنید:

مسیرهای پیگیری
HTTP
GET /orders/:id
GET /orders/by-reference/:external_reference
پاسخ جزئیات سفارش — 200
JSON
{
  "success": true,
  "request_id": "req_example",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "data": {
    "order_id": "5e4c461e-e717-46e4-8f5c-07e4e57b4d37",
    "external_reference": "INV-10928",
    "product_id": "7b224e31-4077-4a02-b625-5f376971a9d4",
    "product_name": "گیفت کارت اپل آمریکا",
    "face_value": "10",
    "face_value_currency": "USD",
    "total_irr": "8500000",
    "tax_irr": "0",
    "currency": "IRR",
    "status": "PROCESSING",
    "refund_status": "NONE",
    "refunded_amount_irr": null,
    "redemption_available": false,
    "created_at": "2026-10-10T09:00:00.000Z",
    "updated_at": "2026-10-10T09:00:00.000Z",
    "next_poll_after_seconds": 10
  }
}
وضعیت‌های سفارش
statusرفتار کلاینت
PROCESSINGسفارش در حال پردازش است؛ ثبت دوباره خرید لازم نیست
COMPLETEDسفارش تکمیل شده است؛ در صورت redemption_available=true اطلاعات کارت را دریافت کنید
FAILEDسفارش ناموفق است؛ وضعیت بازپرداخت را جداگانه بررسی کنید
IN_REVIEWسفارش در حال بررسی است

در وضعیت PROCESSING، پیش از پیگیری بعدی حداقل به اندازه next_poll_after_seconds ثانیه منتظر بمانید و سهمیه مشترک سفارش‌ها را رعایت کنید. در وضعیت‌های دیگر این فیلد می‌تواند null باشد. دریافت وب‌هوک، نیاز به پیگیری مداوم را کاهش می‌دهد.

بازپرداخت مستقل از وضعیت سفارش است: refund_status یکی ازNONE، PENDING یا COMPLETED است؛refunded_amount_irr می‌تواند null باشد. برای تشخیص پایان بازپرداخت، وضعیت آن را بررسی کنید.

GET /orders

پارامترهای فهرست سفارش‌ها
پارامترمقدار
pageعدد صحیح از 1؛ پیش‌فرض 1
limitعدد صحیح از 1 تا 100؛ پیش‌فرض 50
statusاختیاری؛ یکی از وضعیت‌های جدول بالا
نمونه درخواست فهرست
HTTP
GET /api/v1/partner/orders?limit=20&page=1&status=PROCESSING
پاسخ فهرست — 200
JSON
{
  "success": true,
  "request_id": "req_example",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "data": {
    "orders": [
      {
        "order_id": "5e4c461e-e717-46e4-8f5c-07e4e57b4d37",
        "external_reference": "INV-10928",
        "product_id": "7b224e31-4077-4a02-b625-5f376971a9d4",
        "product_name": "گیفت کارت اپل آمریکا",
        "face_value": "10",
        "face_value_currency": "USD",
        "total_irr": "8500000",
        "tax_irr": "0",
        "currency": "IRR",
        "status": "PROCESSING",
        "refund_status": "NONE",
        "refunded_amount_irr": null,
        "redemption_available": false,
        "created_at": "2026-10-10T09:00:00.000Z",
        "updated_at": "2026-10-10T09:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

دریافت اطلاعات کارت

GET/orders/:id/redemptionredemption:read

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

پاسخ اطلاعات کارت — 200
JSON
{
  "success": true,
  "request_id": "req_example",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "data": {
    "order_id": "5e4c461e-e717-46e4-8f5c-07e4e57b4d37",
    "external_reference": "INV-10928",
    "pin": "EXAMPLE-CARD-CODE",
    "redemption_payload": {
      "code": "EXAMPLE-CARD-CODE",
      "pin": null,
      "serial": null,
      "link": null,
      "expiration_date": null,
      "instructions": null,
      "additional_info": null
    },
    "cards": [],
    "fulfilled_at": "2026-10-10T09:00:00.000Z"
  }
}
فیلدهای دریافت کارت
فیلدمعنا
pinمقدار اصلی کد یا PIN؛ ممکن است null باشد
redemption_payloadاطلاعات تحویل؛ ممکن است null باشد
code / pin / serial / linkکد، PIN، سریال یا لینک دریافت؛ همه محصولات الزاماً PIN ندارند
expiration_date / instructionsتاریخ انقضا و راهنمای استفاده، در صورت ارائه
additional_infoاطلاعات تکمیلی تحویل؛ ممکن است null باشد
cardsآرایه اطلاعات کارت‌ها؛ ممکن است خالی باشد
fulfilled_atزمان ثبت وضعیت تحویل

فیلدهای داخل redemption_payload را بر اساس نوع تحویل بخوانید و مقدارهای null را مدیریت کنید. هر عضو cards می‌تواند code، pin، serial، link، additional_info، face_value و face_value_currency داشته باشد. پیش از آماده شدن تحویل، پاسخ 409 REDEMPTION_NOT_READY دریافت می‌شود.

وب‌هوک سفارش

وب‌هوک، تغییر وضعیت سفارش را به مقصد HTTPS ثبت‌شده ارسال می‌کند. داده کارت داخل رویداد قرار ندارد؛ پس از order.completed، اطلاعات کارت را با درخواست امضاشده از مسیر redemption دریافت کنید.

ثبت مقصد

دسترسی تمام مسیرهای مدیریت وب‌هوک: orders:read. مقصد باید از اینترنت قابل دسترس باشد؛ آدرس localhost یا شبکه خصوصی پذیرفته نمی‌شود. استفاده از HTTPS روی پورت 443 توصیه می‌شود.

POST /webhooks/endpoints — بدنه درخواست
JSON
{
  "url": "https://your-domain.example/webhooks/melligift",
  "description": "رویدادهای سفارش"
}

فیلد url الزامی و حداکثر ۲۰۴۸ کاراکتر است. description اختیاری و حداکثر ۲۵۵ کاراکتر است. آدرس نمونه را با مقصد واقعی خود جایگزین کنید.

پاسخ ثبت مقصد — 201
JSON
{
  "success": true,
  "request_id": "req_example",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "data": {
    "id": "a5330601-f68c-4c03-887d-a65f2606bb97",
    "url": "https://your-domain.example/webhooks/melligift",
    "description": "رویدادهای سفارش",
    "enabled": true,
    "secret": "whsec_EXAMPLE_NOT_A_REAL_SECRET",
    "created_at": "2026-10-10T09:00:00.000Z"
  }
}

کلید secret فقط هنگام ایجاد مقصد ارائه می‌شود؛ آن را ذخیره کنید. این کلید مخصوص اعتبارسنجی وب‌هوک است و با کلید محرمانه API تفاوت دارد.

مدیریت و آزمایش مقصد

مدیریت مقصدهای وب‌هوک
درخواستبدنه و پاسخ
GET /webhooks/endpointsبدون بدنه؛ data آرایه مقصدها شامل id، url، description، enabled، secret_preview، created_at و updated_at است
PATCH /webhooks/endpoints/:idحداقل یکی از url، description یا enabled را ارسال کنید؛ پاسخ شامل مشخصات مقصد است
DELETE /webhooks/endpoints/:idبدون بدنه؛ data شامل success و message است
POST /webhooks/endpoints/:id/testبدون بدنه؛ رویداد endpoint.verified برای ارسال پذیرفته می‌شود
نمونه غیرفعال کردن مقصد — بدنه PATCH
JSON
{
  "enabled": false
}
پاسخ درخواست تست — 201
JSON
{
  "success": true,
  "request_id": "req_example",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "data": {
    "event_id": "evt_test_example",
    "message": "رویداد آزمایشی وب‌هوک در صف ارسال قرار گرفت."
  }
}

پاسخ درخواست تست، دریافت رویداد توسط مقصد را تایید نمی‌کند. رسیدن پیام endpoint.verified به گیرنده خود را بررسی کنید.

دریافت و اعتبارسنجی

هدرهای وب‌هوک
هدرمقدار
Content-Typeapplication/json
x-melli-event-idشناسه رویداد؛ برای تشخیص ارسال تکراری
x-melli-timestampزمان ارسال به ثانیه یونیکس
x-melli-signaturehex از HMAC-SHA256(secret, timestamp + '.' + rawBody)

امضا را با کلید همان مقصد و بدنه اصلی پیش از تبدیل به JSON بررسی کنید. timestamp هدر زمان ارسال است؛ آن را با timestamp داخل JSON جایگزین نکنید. پنجره پذیرش زمان در نمونه گیرنده ۳۰۰ ثانیه است؛ مقدارmaxAgeSeconds باید عدد صحیح نامنفی باشد.

نمونه بدنه وب‌هوک order.completed
JSON
{
  "event_id": "evt_example",
  "event_type": "order.completed",
  "timestamp": "2026-10-10T09:00:00.000Z",
  "data": {
    "order_id": "5e4c461e-e717-46e4-8f5c-07e4e57b4d37",
    "external_reference": "INV-10928",
    "status": "COMPLETED",
    "fulfilled_at": "2026-10-10T09:00:00.000Z",
    "redemption_available": true
  }
}
رویدادهای وب‌هوک
event_typeفیلدهای data
order.completedorder_id، external_reference، status، fulfilled_at، redemption_available
order.failedorder_id، external_reference، status، failure_reason، refunded_amount_irr، currency
order.in_revieworder_id، external_reference، status، reason
endpoint.verifiedendpoint_id، message؛ رویداد آزمایشی مقصد
استفاده از تابع اعتبارسنجی
JavaScript
import { verifyPartnerWebhook } from './partner-webhook.mjs';

// rawBody باید Buffer بدنه اصلی باشد، پیش از تبدیل به JSON.
const event = verifyPartnerWebhook({
  headers: request.headers,
  rawBody,
  secret: process.env.PARTNER_WEBHOOK_SECRET,
});

// event.event_id را همراه رویداد به صورت یکتا ذخیره کنید.
// پس از ثبت پایدار، پاسخ 200 یا 204 بدهید و پردازش سفارش را جداگانه انجام دهید.
کد کامل اعتبارسنجی وب‌هوک
partner-webhook.mjs
JavaScript
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyPartnerWebhook({ headers, rawBody, secret, maxAgeSeconds = 300 } = {}) {
  if (typeof secret !== 'string' || !secret.trim() ||
      !Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds < 0) {
    throw new Error('Invalid webhook verification settings');
  }
  if (!headers || typeof headers !== 'object' || !Buffer.isBuffer(rawBody)) {
    throw new Error('Invalid webhook headers or body');
  }
  const timestamp = headers['x-melli-timestamp'];
  const signature = headers['x-melli-signature'];
  const eventId = headers['x-melli-event-id'];
  if (typeof timestamp !== 'string' || !timestamp || timestamp.length > 16 || /\D/.test(timestamp) ||
      typeof signature !== 'string' || signature.length !== 64 || !/^[a-f\d]{64}$/i.test(signature) ||
      typeof eventId !== 'string' || !eventId.trim()) {
    throw new Error('Invalid webhook headers or body');
  }

  const seconds = Number(timestamp);
  if (!Number.isSafeInteger(seconds) || seconds <= 0 ||
      Math.abs(Math.floor(Date.now() / 1000) - seconds) > maxAgeSeconds) {
    throw new Error('Webhook timestamp is outside the accepted window');
  }

  const expected = createHmac('sha256', secret)
    .update(timestamp + '.', 'utf8').update(rawBody).digest();
  if (!timingSafeEqual(expected, Buffer.from(signature, 'hex'))) {
    throw new Error('Invalid webhook signature');
  }

  let event;
  try {
    event = JSON.parse(rawBody.toString('utf8'));
  } catch {
    throw new Error('Invalid webhook event');
  }
  if (!event || typeof event !== 'object' || Array.isArray(event) ||
      event.event_id !== eventId || typeof event.event_type !== 'string' || !event.event_type.trim()) {
    throw new Error('Invalid webhook event');
  }
  return event;
}

پاسخ گیرنده و ارسال مجدد

  • پس از اعتبارسنجی و ثبت پایدار رویداد، سریع پاسخ 2xx مانند 200 یا 204 بدهید. پردازش طولانی یا دریافت کارت را به بعد از ثبت رویداد منتقل کنید.
  • هر event_id را فقط یک بار پردازش کنید. برای رویداد معتبر تکراری نیز پاسخ موفق بدهید.
  • در صورت timeout، خطای شبکه یا پاسخ ناموفق، ارسال مجدد ممکن است انجام شود. تحویل دقیقاً یک‌باره یا ترتیب رسیدن رویدادها را فرض نکنید.
  • اگر رویداد نرسید یا ترتیب وضعیت‌ها مبهم بود، سفارش را از GET /orders/:id بازیابی کنید. برای پایان بازپرداخت نیز وضعیت سفارش را استعلام کنید.

خطاها و رفتار کلاینت

خطاهای متداول API
HTTPerror.codeاقدام
400VALIDATION_ERRORنوع، مقدار و فیلدهای بدنه یا کوئری را اصلاح کنید
401AUTHENTICATION_FAILEDکلید، هدرها، مسیر و امضای درخواست را بررسی کنید
401REQUEST_EXPIREDساعت کلاینت را همگام و درخواست را با زمان و nonce تازه امضا کنید
401REPLAY_DETECTEDبرای هر ارسال، nonce تازه تولید کنید
403SCOPE_DENIEDدسترسی لازم برای کلید فعال نیست؛ با پشتیبانی هماهنگ کنید
403PARTNER_DISABLEDحساب یا دسترسی خرید غیرفعال است
403TERMS_NOT_ACCEPTEDشرایط همکاری باید تایید شوند
403PARTNER_IP_NOT_ALLOWEDدرخواست را از IP مجاز حساب ارسال کنید
403PARTNER_DOMAIN_NOT_ALLOWEDاز دامنه رسمی Partner API استفاده کنید
404PRODUCT_NOT_FOUNDشناسه محصول یا مبلغ قابل خرید را دوباره از کاتالوگ دریافت کنید
404ORDER_NOT_FOUNDشناسه یا مرجع سفارش در این حساب یافت نشد
409PRICE_CHANGEDقیمت محصول را دوباره استعلام کنید؛ details.current_total در صورت وجود، قیمت جدید است
409INSUFFICIENT_BALANCEموجودی کیف پول کافی نیست
409IDEMPOTENCY_CONFLICTکلید با بدنه متفاوت یا مرجع تکراری ارسال شده؛ ابتدا سفارش قبلی را بازیابی کنید
409TOO_MANY_OPEN_ORDERSتا کاهش سفارش‌های در حال پردازش منتظر بمانید
409REDEMPTION_NOT_READYاطلاعات کارت هنوز قابل دریافت نیست؛ وضعیت سفارش را پیگیری کنید
429RATE_LIMITEDتا پایان Retry-After به ثانیه منتظر بمانید
503PURCHASE_DISABLEDخرید موقتاً متوقف است؛ بعداً وضعیت سرویس را بررسی کنید
503PARTNER_API_DISABLEDسرویس همکاران موقتاً در دسترس نیست
500INTERNAL_SERVER_ERRORنتیجه خرید را با مرجع بازیابی و request_id را برای پشتیبانی نگهداری کنید

در خطای ارتباطی یا timeout خرید، نتیجه را ناموفق قطعی فرض نکنید. ابتدا با external_reference استعلام کنید؛ در صورت تکرار ارسال، همان بدنه و Idempotency-Key را حفظ کنید. retryable به‌تنهایی مجوز ایجاد خرید جدید نیست.

برای پیگیری فنی، request_id، زمان درخواست، مسیر و کد HTTP را ارسال کنید. کلید محرمانه، امضا و اطلاعات کارت را در پیام پشتیبانی درج نکنید.

SDK و پلاگین‌های آماده

برای اتصال سریع‌تر، SDK و پلاگین آماده برای این بسترها موجود است:

  • SDK برای Node.js
  • SDK برای PHP
  • پکیج Laravel
  • پلاگین وردپرس

برای دریافت هر کدام، به پشتیبانی تلگرام @melligift پیام بدهید.

پشتیبانی فنی اتصال

پیگیری دسترسی حساب، کلید API و خطاهای اتصال.

ارتباط با پشتیبانی (@melligift)