مستندات اتصال به Partner API
دریافت کاتالوگ، خرید با کیف پول ریالی، پیگیری سفارش و دریافت اطلاعات کارت.
شروع اتصال
دامنه رسمی API: partner.melligift.net. تمام مسیرهای این صفحه به آدرس پایه زیر افزوده میشوند.
- درخواستها را از سرور کلاینت و با HTTPS ارسال کنید. کلید محرمانه را در مرورگر، اپلیکیشن عمومی یا مخزن کد قرار ندهید.
- کاتالوگ و قیمت محصول را دریافت کنید؛ سپس خرید را با مرجع و کلید یکتا ثبت کنید.
- تکمیل سفارش را از وبهوک یا مسیر پیگیری دریافت و اطلاعات کارت را جداگانه بخوانید.
نمونههای پاسخ فقط ساختار API را نشان میدهند. شناسهها و مبالغ واقعی را از پاسخ دریافت کنید. تمام مبالغ پرداختی به ریال و به صورت رشته عددی هستند؛ تاریخهای پاسخ در قالب ISO 8601 ارائه میشوند.
مرجع مسیرها
تمام مسیرها نیازمند کلید معتبر و امضای درخواست هستند. مقادیر :id و :external_reference را با شناسه واقعی جایگزین و برای قرار گرفتن در مسیر URL encode کنید.
| متد | مسیر | دسترسی | پاسخ موفق | کاربرد |
|---|---|---|---|---|
GET | /status | کلید معتبر | 200 | وضعیت سرویس و دسترسی خرید |
GET | /wallet | wallet:read | 200 | موجودی قابل استفاده به ریال |
GET | /catalog | catalog:read | 200 / 304 | فهرست محصولات و مبالغ قابل خرید |
GET | /catalog/products/:id | catalog:read | 200 | جزئیات و قیمت محصول |
POST | /orders | orders:create | 202 | ثبت یا بازیابی همان درخواست خرید |
GET | /orders | orders:read | 200 | فهرست سفارشها |
GET | /orders/:id | orders:read | 200 | جزئیات یک سفارش |
GET | /orders/by-reference/:external_reference | orders:read | 200 | بازیابی سفارش با مرجع همکار |
GET | /orders/:id/redemption | redemption:read | 200 | دریافت اطلاعات کارت |
GET | /webhooks/endpoints | orders:read | 200 | فهرست مقصدهای وبهوک |
POST | /webhooks/endpoints | orders:read | 201 | ثبت مقصد وبهوک |
PATCH | /webhooks/endpoints/:id | orders:read | 200 | ویرایش مقصد وبهوک |
DELETE | /webhooks/endpoints/:id | orders:read | 200 | حذف مقصد وبهوک |
POST | /webhooks/endpoints/:id/test | orders:read | 201 | درخواست ارسال رویداد آزمایشی |
ساختار پاسخ
داده پاسخ موفق در data قرار دارد. request_id شناسه پیگیری درخواست است. فیلدهای اضافی پاسخ را نادیده بگیرید و شناسهها را بدون تغییر نگهداری کنید.
{
"success": true,
"request_id": "req_example",
"timestamp": "2026-10-10T09:00:00.000Z",
"data": {
"available_balance": "25000000",
"currency": "IRR"
}
}{
"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-Type | application/json برای درخواستهای دارای بدنه |
Idempotency-Key | برای POST /orders الزامی؛ یک کلید یکتا برای هر خرید مستقل |
X-Request-Id | اختیاری؛ حروف لاتین، عدد و . _ : -، حداکثر ۱۲۸ کاراکتر |
رشته امضا از ۹ مقدار زیر تشکیل میشود؛ مقادیر با \n (LF) جدا میشوند و انتهای رشته newline ندارد. امضا برابر HMAC-SHA256(secret, stringToSign) با خروجی hex است.
| خط | مقدار | توضیح |
|---|---|---|
1 | MG-HMAC-SHA256-V1 | مقدار ثابت |
2 | X-API-Key | شناسه کلید، عین مقدار هدر |
3 | METHOD | متد با حروف بزرگ: GET، POST، PATCH یا DELETE |
4 | PATH | مسیر کامل بدون دامنه و کوئری؛ مانند /api/v1/partner/orders |
5 | QUERY | کوئری مرتبشده، بدون ?؛ در صورت نبود کوئری، رشته خالی |
6 | X-Timestamp | عین مقدار هدر زمان |
7 | X-Nonce | عین مقدار هدر nonce |
8 | Idempotency-Key | عین مقدار هدر؛ در صورت نبود هدر، رشته خالی |
9 | SHA256(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 قرار دهید. درخواست خرید به صورت خودکار تکرار نمیشود.
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);node example.mjsکد کامل کلاینت
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
وضعیت و امکان خرید را دریافت کنید. این مسیر به دسترسی اختصاصی نیاز ندارد؛ کلید معتبر و امضا الزامی هستند.
{
"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 موجودی قابل استفاده به ریال است؛ استعلام موجودی به معنی تضمین پذیرش خرید بعدی نیست.
{
"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 قرار دارند. کاتالوگ صفحهبندی ندارد؛ لیست ممکن است خالی باشد.
{
"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 دریافت میشود.
{
"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
}
]
}
}ثبت سفارش
/ordersorders:createهدر Idempotency-Key الزامی است. پیش از نخستین ارسال، کلید، مرجع و بدنه خرید را در سامانه خود ذخیره کنید. هر خرید مستقل باید کلید و مرجع مستقل داشته باشد.
| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
external_reference | string | بله | مرجع یکتا در حساب همکار؛ حداکثر ۱۲۸ کاراکتر |
product_id | string | بله | شناسه دریافتی از کاتالوگ |
face_value | number | بله | مبلغ اسمی مثبت |
face_value_currency | string | بله | ارز مبلغ اسمی، مانند USD |
quantity | integer | بله | در نسخه جاری فقط 1 |
expected_total | string | بله | عین price_irr؛ مبلغ نهایی مورد انتظار به ریال |
currency | string | بله | مقدار IRR |
{
"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"
}{
"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 از نمونه کلاینت ساخته میشود.
// 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. یک سفارش را با یکی از دو مسیر زیر دریافت کنید:
GET /orders/:id
GET /orders/by-reference/:external_reference{
"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 | اختیاری؛ یکی از وضعیتهای جدول بالا |
GET /api/v1/partner/orders?limit=20&page=1&status=PROCESSING{
"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
}
}دریافت اطلاعات کارت
/orders/:id/redemptionredemption:readپس از تکمیل سفارش و آماده شدن اطلاعات تحویل، این مسیر را فراخوانی کنید. اطلاعات کارت را در گزارشهای عمومی یا لاگهای عادی ثبت نکنید.
{
"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 توصیه میشود.
{
"url": "https://your-domain.example/webhooks/melligift",
"description": "رویدادهای سفارش"
}فیلد url الزامی و حداکثر ۲۰۴۸ کاراکتر است. description اختیاری و حداکثر ۲۵۵ کاراکتر است. آدرس نمونه را با مقصد واقعی خود جایگزین کنید.
{
"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 برای ارسال پذیرفته میشود |
{
"enabled": false
}{
"success": true,
"request_id": "req_example",
"timestamp": "2026-10-10T09:00:00.000Z",
"data": {
"event_id": "evt_test_example",
"message": "رویداد آزمایشی وبهوک در صف ارسال قرار گرفت."
}
}پاسخ درخواست تست، دریافت رویداد توسط مقصد را تایید نمیکند. رسیدن پیام endpoint.verified به گیرنده خود را بررسی کنید.
دریافت و اعتبارسنجی
| هدر | مقدار |
|---|---|
Content-Type | application/json |
x-melli-event-id | شناسه رویداد؛ برای تشخیص ارسال تکراری |
x-melli-timestamp | زمان ارسال به ثانیه یونیکس |
x-melli-signature | hex از HMAC-SHA256(secret, timestamp + '.' + rawBody) |
امضا را با کلید همان مقصد و بدنه اصلی پیش از تبدیل به JSON بررسی کنید. timestamp هدر زمان ارسال است؛ آن را با timestamp داخل JSON جایگزین نکنید. پنجره پذیرش زمان در نمونه گیرنده ۳۰۰ ثانیه است؛ مقدارmaxAgeSeconds باید عدد صحیح نامنفی باشد.
{
"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.completed | order_id، external_reference، status، fulfilled_at، redemption_available |
order.failed | order_id، external_reference، status، failure_reason، refunded_amount_irr، currency |
order.in_review | order_id، external_reference، status، reason |
endpoint.verified | endpoint_id، message؛ رویداد آزمایشی مقصد |
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 بدهید و پردازش سفارش را جداگانه انجام دهید.کد کامل اعتبارسنجی وبهوک
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 بازیابی کنید. برای پایان بازپرداخت نیز وضعیت سفارش را استعلام کنید.
خطاها و رفتار کلاینت
| HTTP | error.code | اقدام |
|---|---|---|
400 | VALIDATION_ERROR | نوع، مقدار و فیلدهای بدنه یا کوئری را اصلاح کنید |
401 | AUTHENTICATION_FAILED | کلید، هدرها، مسیر و امضای درخواست را بررسی کنید |
401 | REQUEST_EXPIRED | ساعت کلاینت را همگام و درخواست را با زمان و nonce تازه امضا کنید |
401 | REPLAY_DETECTED | برای هر ارسال، nonce تازه تولید کنید |
403 | SCOPE_DENIED | دسترسی لازم برای کلید فعال نیست؛ با پشتیبانی هماهنگ کنید |
403 | PARTNER_DISABLED | حساب یا دسترسی خرید غیرفعال است |
403 | TERMS_NOT_ACCEPTED | شرایط همکاری باید تایید شوند |
403 | PARTNER_IP_NOT_ALLOWED | درخواست را از IP مجاز حساب ارسال کنید |
403 | PARTNER_DOMAIN_NOT_ALLOWED | از دامنه رسمی Partner API استفاده کنید |
404 | PRODUCT_NOT_FOUND | شناسه محصول یا مبلغ قابل خرید را دوباره از کاتالوگ دریافت کنید |
404 | ORDER_NOT_FOUND | شناسه یا مرجع سفارش در این حساب یافت نشد |
409 | PRICE_CHANGED | قیمت محصول را دوباره استعلام کنید؛ details.current_total در صورت وجود، قیمت جدید است |
409 | INSUFFICIENT_BALANCE | موجودی کیف پول کافی نیست |
409 | IDEMPOTENCY_CONFLICT | کلید با بدنه متفاوت یا مرجع تکراری ارسال شده؛ ابتدا سفارش قبلی را بازیابی کنید |
409 | TOO_MANY_OPEN_ORDERS | تا کاهش سفارشهای در حال پردازش منتظر بمانید |
409 | REDEMPTION_NOT_READY | اطلاعات کارت هنوز قابل دریافت نیست؛ وضعیت سفارش را پیگیری کنید |
429 | RATE_LIMITED | تا پایان Retry-After به ثانیه منتظر بمانید |
503 | PURCHASE_DISABLED | خرید موقتاً متوقف است؛ بعداً وضعیت سرویس را بررسی کنید |
503 | PARTNER_API_DISABLED | سرویس همکاران موقتاً در دسترس نیست |
500 | INTERNAL_SERVER_ERROR | نتیجه خرید را با مرجع بازیابی و request_id را برای پشتیبانی نگهداری کنید |
در خطای ارتباطی یا timeout خرید، نتیجه را ناموفق قطعی فرض نکنید. ابتدا با external_reference استعلام کنید؛ در صورت تکرار ارسال، همان بدنه و Idempotency-Key را حفظ کنید. retryable بهتنهایی مجوز ایجاد خرید جدید نیست.
برای پیگیری فنی، request_id، زمان درخواست، مسیر و کد HTTP را ارسال کنید. کلید محرمانه، امضا و اطلاعات کارت را در پیام پشتیبانی درج نکنید.
SDK و پلاگینهای آماده
برای اتصال سریعتر، SDK و پلاگین آماده برای این بسترها موجود است:
- SDK برای Node.js
- SDK برای PHP
- پکیج Laravel
- پلاگین وردپرس
برای دریافت هر کدام، به پشتیبانی تلگرام @melligift پیام بدهید.
