مستندات API

احراز هویت

در پنل کسب‌وکار یک کلید API بسازید (فقط یک‌بار نمایش داده می‌شود) و آن را سمت سرور نگه دارید. هر درخواست باید این هدر را داشته باشد؛ هر کلید فقط به داده‌های کسب‌وکار خودش دسترسی دارد.

Authorization: Bearer mxi_live_XXXXXXXXXXXXXXXXXXXXXXXX

اعتبارسنجی کوپن

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

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
}

مصرف کوپن

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

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 ارسال می‌شود. بدنهٔ خام را با secret خودتان HMAC-SHA256 کنید و با هدر X-Maix-Signature مقایسه کنید.

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

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

کدهای خطا

امنیت

• کلید را فقط سمت سرور نگه دارید، نه در مرورگر.
• در صورت لو رفتن، کلید را باطل و کلید جدید بسازید.
• امضای HMAC هر وب‌هوک را حتماً بررسی کنید.
• مصرف کوپن را فقط پس از تأیید قطعی پرداخت صدا بزنید.

پشتیبانی: support@maix.ir