المصادقة

رمزا الوصول والتحديث

POST /v1/auth/anonymous يُصدر زوج رموز لمتجر المفتاح. رمز الوصول يعيش 15 دقيقة ويُرسَل في ترويسة Authorization: Bearer؛ ورمز التحديث يعيش 30 يومًا ويُستعمل مرة واحدة — كل تحديث يستهلك الرمز المقدَّم ويُصدر زوجًا جديدًا، وإعادة استعمال رمز مستهلك مرفوضة.

curl -X POST https://api.matgrk.com/v1/auth/anonymous \
  -H "X-Api-Key: mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transport": "bearer", "scope": ["catalogue:read", "cart:write"]}'

curl -X POST https://api.matgrk.com/v1/auth/refresh \
  -H "X-Api-Key: mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "REFRESH_TOKEN"}'

النقل بالكوكيز

مرِّر "transport": "cookie" بدلًا من ذلك فتوضع الرموز في كوكيز httpOnly وsecure — ولا يحمل جسم الاستجابة حينها أي رمز، فلا تستطيع سكربتات الصفحة قراءته. والتحديث عبر الكوكي لا يحتاج جسمًا.

النطاقات

يحمل الرمز النطاقات التي صدر بها، وكل مسار يتحقق من نطاق واحد معلَن. طلب النطاقات عند الإصدار لا يستطيع إلا التضييق — الاسم غير المعلَن مرفوض، والطلب خارج نطاقات الرمز يُجاب بـ 403 INSUFFICIENT_SCOPE.

• catalogue:readقراءة المنتجات والتصنيفات والعلامات
• search:readاقتراحات البحث وسياقه
• cart:readقراءة سلة التسوق الحالية
• cart:writeإنشاء السلة وتعديلها
• checkout:writeالتسعير واختيار طريقة التسليم وإتمام الطلب
• account:readقراءة ملف المتسوق وعناوينه
• account:writeالتسجيل وتسجيل الدخول وإدارة العناوين
• orders:readقراءة طلبات المتسوق

جلسات المتسوقين

كل جلسة تبدأ مجهولة. مسارات /v1/account/* — التسجيل وتسجيل الدخول ورموز التحقق — تربط متسوقًا بالجلسة، فتتبعه سلته وعناوينه وطلباته من هناك.