واجهة المطوّرين — Mystoq API & Webhooks

مقدّمة

واجهة Mystoq البرمجيّة تتبع نمط REST، تُرجع JSON، وتُؤمَّن عبر مفاتيح API. كلّ طلب يُنفَّذ في نطاق متجرك وحده. أنشئ مفتاحك من لوحة التحكّم ← المطوّرون.

المصادقة

مرّر مفتاحك في ترويسة Authorization بصيغة Bearer. المفتاح بالشكل msq_<prefix>_<secret> ويُعرَض مرّة واحدة عند إنشائه.

# كلّ الطلبات تحتاج هذه الترويسة
Authorization: Bearer msq_ab12cd34_your_secret_here

احفظ المفتاح في مكان آمن. صلاحية read للقراءة فقط، وwrite مطلوبة لإنشاء الطلبات.

الأساس والحدود

العنوان الأساس	`https://mystoq.com/api/v1`
الصيغة	JSON (`Accept: application/json`)
حدّ المعدّل	120 طلبًا في الدقيقة لكلّ مفتاح
الترقيم	معاملات `page` و `per_page`

المنتجات

GET/v1/products

قائمة منتجات متجرك المنشورة (مرقّمة).

# مثال
curl "https://mystoq.com/api/v1/products?per_page=2" \
  -H "Authorization: Bearer msq_ab12cd34_secret" \
  -H "Accept: application/json"

// الاستجابة
{
  "data": [
    { "id": 1027, "name": "جاكيت نسائي", "price": 2000,
      "compare_price": 2800, "stock": 100, "status": "active" }
  ],
  "meta": { "current_page": 1, "per_page": 2 }
}

GET/v1/products/{id}

تفاصيل منتج واحد.

الطلبات

GET/v1/orders

قائمة الطلبات (تدعم التصفية بـ status وdate).

GET/v1/orders/{id}

تفاصيل طلب واحد مع عناصره وبيانات الزبون.

إنشاء طلب

POST/v1/orders

إنشاء طلب برمجيًّا (يتطلّب صلاحية write). تمرّ كلّ القواعد الداخليّة: إعادة حساب السعر، حجز المخزون، والحماية من الاحتيال.

curl -X POST "https://mystoq.com/api/v1/orders" \
  -H "Authorization: Bearer msq_ab12cd34_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "أحمد بن علي",
    "phone": "0555123456",
    "wilaya_id": 16,
    "items": [ { "product_id": 1027, "quantity": 1 } ]
  }'

النجاح يُرجع كائن الطلب مع id وreference والإجماليّ. تُطلَق أحداث Webhooks تلقائيًّا.

Webhooks

سجّل رابطًا (https) من لوحة التحكّم لتصلك إشعارات POST فوريّة عند وقوع الأحداث.

الحدث	يقع عند
`order.created`	إنشاء طلب جديد في متجرك
`order.updated`	تغيّر حالة طلب (يتضمّن `old_status` و`new_status`)

// جسم الطلب المُرسَل إلى رابطك
{
  "event": "order.created",
  "created_at": "2026-07-11T20:00:00Z",
  "data": {
    "id": 5821, "reference": "ORD-5821", "status": "pending",
    "total": 2500, "customer": { "name": "أحمد", "phone": "0555…" }
  }
}

التحقّق من التوقيع

كلّ طلب يحمل ترويسة X-Mystoq-Signature = sha256=HMAC(secret, rawBody). تحقّق منها لتضمن أنّ الطلب من Mystoq.

// Node.js — مثال التحقّق
const crypto = require("crypto");
const expected = "sha256=" +
  crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
if (expected === req.headers["x-mystoq-signature"]) { /* موثوق */ }

أعِد بحالة 2xx خلال 8 ثوانٍ. عند الفشل نعيد المحاولة حتّى 4 مرّات بفواصل متزايدة.

الأخطاء

الرمز	المعنى
`200 / 201`	نجاح
`401`	مفتاح غير صالح أو مفقود
`403`	المفتاح لا يملك الصلاحية المطلوبة (write)
`422`	بيانات غير صالحة
`429`	تجاوز حدّ المعدّل

واجهة Mystoq للمطوّرين