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

بدء سريع

ثلاث خطوات من الصفر إلى أوّل طلب برمجيّ:

1. أنشئ مفتاح API من لوحة التحكّم ← المطوّرون (اختَر صلاحية read أو write).
2. مرّر المفتاح في ترويسة Authorization: Bearer مع كلّ طلب.
3. استدعِ GET /v1/products ثمّ سجّل رابط Webhook لاستقبال الأحداث.

مقدّمة

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

المصادقة

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

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

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

المنتجات

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

المعاملات (اختياريّة)

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

// الاستجابة
{
  "data": [
    { "id": 1027, "name": "Women's jacket", "slug": "womens-jacket",
      "price": 2000, "compare_price": 2800, "sku": "JCK-01",
      "stock": 100, "status": "active", "category_id": 4,
      "images": ["https://…/p1.jpg"] }
  ],
  "meta": { "current_page": 1, "per_page": 2, "total": 57, "last_page": 29 }
}

تفاصيل منتج واحد. يُرجع 404 إن لم يوجد أو لم يكن منشورًا.

الطلبات

قائمة طلبات متجرك (مرقّمة، الأحدث أوّلًا).

المعاملات (اختياريّة)

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

// استجابة الطلب
{
  "data": {
    "id": 5821, "reference": "ORD-5821", "status": "pending",
    "payment_method": "cod", "payment_status": "unpaid",
    "subtotal": 2000, "shipping_cost": 500, "discount": 0, "total": 2500,
    "delivery_type": "home", "wilaya_id": 16, "commune": "Bab Ezzouar",
    "customer": { "name": "Ahmed Ben Ali", "phone": "0555123456" },
    "items": [ { "product_id": 1027, "name": "Women's jacket", "price": 2000, "qty": 1, "total": 2000 } ],
    "created_at": "2026-07-18T20:00:00Z"
  }
}

إنشاء طلب

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

حقول الجسم

curl -X POST "https://mystoq.com/api/v1/orders" \
  -H "Authorization: Bearer msq_ab12cd34_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "name": "Ahmed Ben Ali", "phone": "0555123456", "wilaya_id": 16, "commune": "Bab Ezzouar" },
    "items": [ { "product_id": 1027, "qty": 1 } ],
    "payment_method": "cod",
    "delivery_type": "home"
  }'

Webhooks

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

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

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

كلّ طلب Webhook يحمل ترويسة 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"]) { /* موثوق */ }

الأخطاء