eMatjarak

أول طلب لك على الواجهة

خمس عشرة دقيقة من البداية إلى النهاية. تحتاج شيئاً واحداً قبل أن تبدأ، وهو شيء لا تستطيع إنشاءه بنفسك: مفتاح من التاجر صاحب المتجر الذي تتكامل معه.

  1. اطلب من التاجر مفتاحاً ورمز متجر

    يصدرهما من لوحة تحكمه في الإعدادات ← المطوّر. اطلب أضيق مجموعة صلاحيات يحتاجها تكاملك فعلاً — تستطيع طلب المزيد لاحقاً دائماً، والمفتاح الذي يقرأ فقط مفتاح لا يستطيع تعطيل متجره.

  2. انتبه أن المفتاح يظهر مرة واحدة

    يُخزَّن مُجزّأً، فلا توجد طريقة لعرضه ثانية. وإن فُقد يقوم التاجر بتدويره ويعطيك مفتاحاً جديداً. ضعه مباشرة في مخزن أسرارك لا في ملف إعدادات ستدفعه إلى المستودع.

  3. أرسل طلباً موثّقاً واحداً

    كل استدعاء هو POST إلى المسار نفسه، ويحمل الترويستين. ابدأ بشيء غير مؤذٍ يثبت أن المفتاح والرمز صحيحان معاً.

  4. اقرأ بيانات حقيقية

    اجلب أحدث طلبات المتجر. فإن أعادت بيانات، فبيانات اعتمادك وصلاحياتك صحيحة وتستطيع البدء بالبناء.

  5. استقبل الأحداث بدل الاستجواب

    سجّل رابطاً آمناً، وتحقق من توقيع ما يصلك، وكُفَّ عن سؤال الواجهة إن كان شيء قد تغيّر.

الطلب الأول

bash
curl https://api.ematjarak.example/admin-api \
  -H 'content-type: application/json' \
  -H 'ms-api-key: YOUR_KEY' \
  -H 'ms-store-token: STORE_TOKEN' \
  -d '{"query":"{ activeChannel { code } }"}'
  • ms-api-key — مفتاح التاجر. أرسله مع كل طلب.
  • ms-store-token — رمز المتجر، ويعطيك إياه التاجر مع المفتاح. وكلاهما مطلوب؛ فالمفتاح دون رمز لا يحدد متجراً.
خطأ 401 هنا يعني أن المفتاح خاطئ أو ملغى أو يخص متجراً غير الذي يشير إليه الرمز. تحقق من الاثنين قبل أن تفترض أن الخدمة متوقفة.

قراءة الطلبات

graphql
query {
  orders(options: { take: 5, sort: { orderPlacedAt: DESC } }) {
    totalItems
    items {
      id
      code                # show this to people, not the id
      state
      orderPlacedAt       # ISO 8601, UTC
      totalWithTax        # integer, minor units
      currencyCode
      customer { emailAddress }
    }
  }
}

أمران في هذه الاستجابة يوقعان الكثيرين في اليوم الأول: المبالغ أعداد صحيحة بالوحدات الصغرى لا كسور عشرية، وكل التواريخ بتوقيت UTC. وكلاهما مشروح في صفحة الاصطلاحات، والخطأ فيهما ينتج مجاميع تزيد أو تنقص مئة ضعف وشحنات تبدو في يوم خاطئ.

أول ويب هوك

يسجّل التاجر رابطك الآمن ويختار الأحداث التي يريدها. نرسل إليه طلب POST بجسم JSON موقّع ونعيد المحاولة عند الفشل. تحقق من التوقيع قبل أن تثق بأي شيء في الجسم، وردّ بسرعة — ونفّذ عملك الفعلي بعد أن تكون قد أقررت بالاستلام.

الويب هوك غير متاحة في الخطة المجانية. فإن كان التاجر عليها فاستجوب الواجهة على فترات معقولة وعُد إلى هذا حين يرقّي خطته — فالبناء على رابط لن يُستدعى أبداً وقت ضائع.

إلى أين بعد ذلك

المبالغ والتواريخ والمعرّفات والتصفّحالصلاحيات والتدوير والإلغاءكل عملية يستطيع المفتاح استدعاءهاالتحقق من التسليمات ومعالجتها