تكامل ERP

كيف تعمل التهيئة

1. أنشئ متجرًا كمسودة من معالجك — الاسم والعنوان (slug) واللغات وبلد الفوترة والباقة واسم المدير وبريده. العملة تُشتق من بلد الفوترة ولا تُرسَل أبدًا. العنوان المحجوز يُجاب بـ 409 ويمكن إعادة المحاولة.
2. هيّئه بخطوات PATCH بعدد شاشات معالجك؛ لا شيء يعمل بعد.
3. افحص الجاهزية — مورد المتجر يحمل قائمة جاهزية يعرضها معالجك.
4. فعِّل. استدعاء واحد قابل للإعادة: يعمل المتجر على باقته، ويُنشأ حساب المدير، وتُجهَّز تدفقات البيانات أدناه تلقائيًا.
5. يصل المديرَ بريد فيه كلمة مرور مؤقتة وعنوان لوحة التحكم؛ وأول تسجيل دخول يفرض تغييرها. كلمة المرور لا تُعاد في استجابة الواجهة أبدًا.

تدفقات البيانات

المصادقة

مفتاح شريك واحد (pk_live_…، يظهر مرة واحدة وتُحفظ خلاصته الرقمية) يشتري رموز وصول لمدة 15 دقيقة ورمز تحديث يُستخدم لمرة واحدة لمدة 30 يومًا مرتبطًا بالمفتاح نفسه، بالنطاقات التي طلبها تكاملك: stores:manage وcatalog:write وstock:write وorders:read وwebhooks:manage وbilling:read. رمز الشريك لا يتصرف إلا في المتاجر التي أنشأها ذلك الشريك — المسار يسمّي المتجر، ورابطة الشريك بالمتجر هي الإذن.

• تتم إدارة المفاتيح بواسطة فريق الشريك نفسه عبر https://partners.matgrk.com (إصدار — يظهر مرة واحدة — وتدوير وإلغاء؛ مع إمكانية استعراض جلسات API النشطة لكل مفتاح وإنهاء أي منها). المفتاح المُلغى يُرفض فورًا؛ والوصول الممنوح مسبقًا ينتهي في غضون 15 دقيقة.
• SESSION_ENDED (401) عند التحديث: أنهيت الجلسة في بوابة الشركاء؛ ولا يُستهلك رمز التحديث — اطلب رمزًا جديدًا باستخدام المفتاح.
• PARTNER_SUSPENDED (403): أثناء إيقاف الشريك، تحمل رموزه نطاق billing:read فقط؛ وتجيب كل العمليات الأخرى بهذا الرمز.
• حد الطلبات لكل مفتاح: 300 طلب في الدقيقة افتراضيًا، وبحد أقصى ضعف متوسط المعدل في الثانية في أي ثانية واحدة (10 في الثانية عند 300/دقيقة)؛ وترويسات x-ratelimit-*، وترويسة Retry-After عند الخطأ 429.

رموز الشريكمتاحة الآن

• POST/partner/v1/auth/tokenإصدار جلسة شريك
• POST/partner/v1/auth/refreshتدوير جلسة الشريك

المتاجر والتهيئةمتاحة الآن

النطاق المطلوب: stores:manage

• GET/partner/v1/slugs/{slug}/availabilityالتحقق من عنوان المتجر
• POST/partner/v1/storesإنشاء متجر كمسودة

  {
    "name": "متجر النور",
    "slug": "alnoor",
    "locales": ["ar", "en"],
    "billing_country": "SA",
    "plan": "pro",
    "admin": {
      "name": "…",
      "email": "owner@example.com",
      "phone": "+9665…"
    }
  }

  {
    "data": {
      "store_id": "01JB…",
      "status": "draft"
    }
  }

• GET/partner/v1/storesمتاجر الشريك المرتبطة
• GET/partner/v1/stores/{id}متجر مرتبط واحد مع قائمة الجاهزية
• PATCH/partner/v1/stores/{id}تهيئة مسودة
• DELETE/partner/v1/stores/{id}التخلي عن مسودة
• POST/partner/v1/stores/{id}/activateتفعيل متجر — يُنشأ المدير وتُرسل كلمة المرور وتُجهَّز التدفقات؛ قابل للإعادة

  {
    "data": {
      "store_id": "01JB…",
      "status": "active",
      "dashboard_url": "https://app.matgrk.com",
      "store_url": "https://matgrk.com/stores/alnoor",
      "admin": { "email": "owner@example.com", "password_delivery": "email" },
      "flows": { "stock": "01JB…", "orders": "01JB…" }
    }
  }

• POST/partner/v1/stores/{id}/credential-emailإعادة إرسال بريد اعتماد المدير

دفع الكتالوجمتاحة الآن

النطاق المطلوب: catalog:write

• POST/partner/v1/stores/{id}/catalog/importsإرسال ملف كتالوج (معاينة)
• POST/partner/v1/stores/{id}/catalog/imports/{importId}/applyتطبيق استيراد مُعايَن
• GET/partner/v1/stores/{id}/catalog/imports/{importId}تقدّم الاستيراد وإخفاقاته

المخزونمتاحة الآن

النطاق المطلوب: stock:write

• PUT/partner/v1/stores/{id}/stockدفع مخزون مطلق (الانكماش المفاجئ يُرفض ولا يُطبَّق)

  {
    "rows": [
      { "sku": "TSHIRT-001", "on_hand": 40 },
      { "sku": "TSHIRT-002", "on_hand": 12 }
    ]
  }

• GET/partner/v1/stores/{id}/stockأرصدة المخزون الحالية

  {
    "data": [
      {
        "sku": "TSHIRT-001",
        "on_hand": 40,
        "reserved": 2,
        "available": 38,
        "branches": [
          { "branch_id": "01JB…", "on_hand": 40, "reserved": 2, "available": 38 }
        ]
      }
    ],
    "meta": { "next_after": "TSHIRT-001" }
  }

• GET/partner/v1/stores/{id}/runs/{runId}تشغيل تدفق مُجهَّز

الطلبات المسلَّمة (الاستطلاع والسجل وإعادة المحاولة)متاحة الآن

النطاق المطلوب: orders:read

• GET/partner/v1/stores/{id}/ordersاستطلاع الطلبات المسلَّمة
• GET/partner/v1/stores/{id}/orders/{orderId}طلب مسلَّم واحد (نفس شكل جسم الويب هوك)

  {
    "data": {
      "id": "01JB…",
      "type": "order.delivered",
      "occurred_at": "2026-09-27T14:21:34Z",
      "store_id": "01JB…",
      "data": {
        "order_id": "01JB…",
        "order_number": "ORD-000001",
        "delivered_at": "2026-09-27T14:21:34Z",
        "branch": "01JB…",
        "lines": [
          { "sku": "TSHIRT-001", "quantity": 2, "price_minor": 11500, "tax_minor": 1500 }
        ],
        "total_minor": 24500,
        "tax_minor": 3000,
        "currency": "SAR",
        "payment_state": "paid",
        "shopper_ref": "01JB…"
      }
    }
  }

• GET/partner/v1/stores/{id}/deliveriesسجل الإرسال الصادر
• POST/partner/v1/stores/{id}/deliveries/{deliveryId}/retryاستئناف إرسال مستنفد (نطاق webhooks:manage)

الويب هوكمتاحة الآن

النطاق المطلوب: webhooks:manage

• GET/partner/v1/stores/{id}/webhooksنقطة استقبال الطلبات المسلَّمة
• POST/partner/v1/stores/{id}/webhooksتسجيل نقطة استقبال الطلبات المسلَّمة
• DELETE/partner/v1/stores/{id}/webhooksإزالة نقطة استقبال الطلبات المسلَّمة

وسيلة نقل الطلبات وملفات الطلباتمتاحة الآن

النطاق المطلوب: orders:read, webhooks:manage

• GET/partner/v1/stores/{id}/orders-transportإعدادات وسيلة نقل الطلبات للمتجر (نطاق webhooks:manage)
• PUT/partner/v1/stores/{id}/orders-transportتحديد وسيلة نقل الطلبات للمتجر (استطلاع أو ويب هوك أو ملف؛ ملف: نقطة إيداع matgrk أو وجهة لدى الشريك؛ jsonl أو csv) (نطاق webhooks:manage)
• GET/partner/v1/stores/{id}/order-filesقائمة ملفات الطلبات في نقطة إيداع matgrk (نطاق orders:read)
• GET/partner/v1/stores/{id}/order-files/{name}تنزيل ملف طلبات واحد (بالبايتات الدقيقة) (نطاق orders:read)
• DELETE/partner/v1/stores/{id}/order-files/{name}تأكيد استلام (حذف) ملف طلبات (نطاق webhooks:manage)

الفوترةمتاحة الآن

النطاق المطلوب: billing:read

• GET/partner/v1/billing/invoicesفواتير الشريك
• GET/partner/v1/billing/invoices/{invoiceId}فاتورة شريك واحدة
• GET/partner/v1/billing/suspensionإيقاف الشريك (معاينة أثناء الجدولة)