مستندات API — اتصال ووکامرس و سایت اختصاصی

احراز هویت

از پنل کسب‌وکار خود، مسیر «اتصال ووکامرس» یک کلید API بسازید. کلید فقط یک‌بار در لحظه ساخت نمایش داده می‌شود — آن را در سمت سرور فروشگاه‌تان ذخیره کنید، هرگز در کد سمت کاربر (مرورگر) قرار ندهید.

هر درخواست باید کلید را در هدر زیر ارسال کند:

Authorization: Bearer mxi_live_XXXXXXXXXXXXXXXXXXXXXXXX

هر کلید فقط به داده‌های همان کسب‌وکاری دسترسی دارد که آن را ساخته — امکان دسترسی به کوپن یا سفارش کسب‌وکار دیگر با هیچ کلیدی وجود ندارد.

اعتبارسنجی کوپن (بدون مصرف)

برای نمایش مبلغ تخفیف در سبد خرید، پیش از پرداخت این endpoint را صدا بزنید — کوپن مصرف نمی‌شود.

POST/api/v1/coupons/validate

curl -X POST https://maix.ir/api/v1/coupons/validate \
  -H "Authorization: Bearer mxi_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"code": "ABC123"}'

پاسخ موفق:

{
  "valid": true,
  "code": "ABC123",
  "campaignTitle": "کمپین فروش تابستانه",
  "expiresAt": "2026-10-01T00:00:00.000Z",
  "rewardType": "PERCENT",
  "rewardPercent": 20
}

مصرف کوپن

فقط بعد از پرداخت موفق سفارش این endpoint را صدا بزنید — این عملیات کوپن را یک‌بار برای همیشه مصرف می‌کند و برگشت‌پذیر نیست.

POST/api/v1/coupons/redeem

curl -X POST https://maix.ir/api/v1/coupons/redeem \
  -H "Authorization: Bearer mxi_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"code": "ABC123"}'

ثبت سفارش (برای باشگاه وفاداری)

بعد از هر پرداخت موفق (حتی بدون کوپن)، سفارش را ثبت کنید تا در باشگاه وفاداری کسب‌وکار شما به‌صورت خودکار محاسبه شود.

POST/api/v1/orders

curl -X POST https://maix.ir/api/v1/orders \
  -H "Authorization: Bearer mxi_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "wc-order-10245",
    "customerPhone": "09120000000",
    "amount": 450000,
    "couponCode": "ABC123"
  }'

وب هوک‌ها

از پنل کسب‌وکار، آدرس وب هوک خود را ثبت کنید (باید https باشد). با مصرف هر کوپن، رویداد coupon.redeemed به آن آدرس ارسال می‌شود.

POST https://your-site.com/maix-webhook
Content-Type: application/json
X-Maix-Event: coupon.redeemed
X-Maix-Signature: <HMAC-SHA256 hex>

{
  "event": "coupon.redeemed",
  "timestamp": "2026-09-18T10:00:00.000Z",
  "data": { "code": "ABC123", "campaignTitle": "...", ... }
}

برای تایید اصالت، بدنه خام درخواست را با secret خودتان (نمایش‌داده‌شده در پنل هنگام ساخت وب هوک) با HMAC-SHA256 امضا و با هدر X-Maix-Signature مقایسه کنید:

// Node.js
const crypto = require("crypto");
const expected = crypto.createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");
if (expected !== req.headers["x-maix-signature"]) {
  return res.status(401).end();
}

اتصال ووکامرس

ساده‌ترین راه، یک اسنیپت کوچک PHP در functions.php یا یک افزونه سبک است که:

1. روی فیلد کوپن سفارشی در صفحه پرداخت، کد را با /api/v1/coupons/validate بررسی و تخفیف را اعمال می‌کند.
2. در هوک woocommerce_order_status_completed، کوپن را با /api/v1/coupons/redeem مصرف می‌کند.
3. همان‌جا، سفارش را با /api/v1/orders ثبت می‌کند.

add_action('woocommerce_order_status_completed', function ($order_id) {
    $order = wc_get_order($order_id);
    $code  = $order->get_meta('_marketist_coupon_code');
    $phone = $order->get_billing_phone();

    $api_key = get_option('marketist_api_key');
    $base    = 'https://maix.ir/api/v1';

    if ($code) {
        wp_remote_post("$base/coupons/redeem", [
            'headers' => [
                'Authorization' => "Bearer $api_key",
                'Content-Type'  => 'application/json',
            ],
            'body' => json_encode(['code' => $code]),
        ]);
    }

    wp_remote_post("$base/orders", [
        'headers' => [
            'Authorization' => "Bearer $api_key",
            'Content-Type'  => 'application/json',
        ],
        'body' => json_encode([
            'externalId'    => (string) $order_id,
            'customerPhone' => $phone,
            'amount'        => (int) $order->get_total(),
            'couponCode'    => $code ?: null,
        ]),
    ]);
});

کدهای خطا

نکات امنیتی

• کلید API را فقط سمت سرور نگه دارید؛ هرگز در جاوااسکریپت سمت مرورگر قرار ندهید.
• اگر کلید لو رفت، از پنل «باطل کردن» بزنید و یک کلید جدید بسازید.
• آدرس وب هوک باید https باشد و امضای HMAC هر درخواست را حتماً بررسی کنید.
• مصرف کوپن (/coupons/redeem) برگشت‌پذیر نیست — فقط بعد از تایید قطعی پرداخت صدا بزنید.