وصول الأدوار إلى نقاط النهاية

توثّق هذه الصفحة نقاط نهاية WCPOS REST المتاحة لكل من الأدوار الافتراضية الثلاثة المستخدمة في سير عمل نقطة البيع:

• administrator
• shop_manager
• cashier

لتهيئة الأدوار والصلاحيات الموجّهة للمستخدم، راجع الوصول إلى نقطة البيع.

ملخّص

نموذج الوصول الافتراضي هو:

• administrator — وصول كامل إلى نقطة البيع والإدارة.
• shop_manager — وصول كامل إلى نقطة البيع والإدارة، باستثناء إجراءات امتدادات الإضافات التي تتطلّب صلاحيات تثبيت الإضافات.
• cashier — وصول إلى سير عمل البيع الاعتيادي في نقطة البيع، لكن دون وصول إلى الإدارة أو الإعدادات أو السجلات أو إدارة المتجر.

تُتحقّق مصفوفة نقاط النهاية عبر اختبارات تكامل تستخدم مسار المصادقة نفسه الذي يستخدمه تطبيق نقطة البيع (رموز وصول WCPOS من نوع bearer، وليس مجرد wp_set_current_user()). تؤكّد تأكيدات نقاط النهاية المسموح بها أن الدور لا يتلقّى 401 أو 403. قد تُعيد بعض نقاط النهاية بيانات عادية أو أخطاء عمل مثل 400 أو 404 عندما يستخدم الاختبار تجهيزات بسيطة — ومع ذلك تثبت تلك الاستجابات أن المستخدم اجتاز طبقة المصادقة/الأذونات.

مصفوفة وصول نقاط النهاية للإضافة المجانية

المجال	أمثلة على نقاط النهاية	Admin	Shop Manager	Cashier	ملاحظات
فهرس الإعدادات	GET /wcpos/v1/settings	✅	✅	✅	فهرس إعدادات نقطة البيع العام/القابل للقراءة
المتاجر	GET /wcpos/v1/stores	✅	✅	✅	بيانات إقلاع نقطة البيع
ملف الكاشير	GET /wcpos/v1/cashier/{id}	✅	✅	✅	بيانات الكاشير الخاصة
متاجر الكاشير	GET /wcpos/v1/cashier/{id}/stores	✅	✅	✅	وصول المتجر للكاشير الحالي
المنتجات	GET /wcpos/v1/products	✅	✅	✅	تصفّح الكتالوج
المتغيّرات	GET /wcpos/v1/products/variations	✅	✅	✅	تصفّح الكتالوج
الفئات	GET /wcpos/v1/products/categories	✅	✅	✅	فلاتر الكتالوج
الوسوم	GET /wcpos/v1/products/tags	✅	✅	✅	فلاتر الكتالوج
العلامات التجارية	GET /wcpos/v1/products/brands	✅	✅	✅	فلاتر الكتالوج
الكوبونات	GET /wcpos/v1/coupons	✅	✅	✅	البحث عن كوبونات نقطة البيع
قراءة الطلبات	GET /wcpos/v1/orders	✅	✅	✅	سجلّ طلبات نقطة البيع
إنشاء الطلبات	POST /wcpos/v1/orders	✅	✅	✅	سير عمل البيع
تحديث الطلبات	PATCH /wcpos/v1/orders/{id}	✅	✅	✅	إكمال/تحديث طلبات نقطة البيع
قراءة/إنشاء الدفع	/wcpos/v1/orders/{id}/checkout	✅	✅	✅	تدفّق الدفع
الإيصالات	GET /wcpos/v1/receipts/{order_id}	✅	✅	✅	تحويل الإيصالات
حالات الطلبات	GET /wcpos/v1/data/order_statuses	✅	✅	✅	بيانات حالة نقطة البيع
قراءة العملاء	GET /wcpos/v1/customers	✅	✅	✅	البحث عن العملاء/سردهم
إنشاء العملاء	POST /wcpos/v1/customers	✅	✅	✅	إنشاء عميل في نقطة البيع
تحديث العملاء	PATCH /wcpos/v1/customers/{id}	✅	✅	✅	تعديل عميل في نقطة البيع
الضرائب	GET /wcpos/v1/taxes	✅	✅	✅	بيانات حساب الدفع/الضرائب
فئات الضرائب	GET /wcpos/v1/taxes/classes	✅	✅	✅	بيانات حساب الدفع/الضرائب
طرق الشحن	GET /wcpos/v1/shipping_methods	✅	✅	✅	بيانات الدفع/الشحن
بوابات الدفع	GET /wcpos/v1/payment-gateways	✅	✅	✅	خيارات الدفع
تهيئة البوابة	POST /wcpos/v1/payment-gateways/{id}/bootstrap	✅	✅	✅	إعداد الدفع
القوالب	GET /wcpos/v1/templates	✅	✅	✅	قراءة الإيصالات/القوالب
القالب النشط	GET /wcpos/v1/templates/active	✅	✅	✅	قراءة الإيصالات/القوالب
معرض القوالب	GET /wcpos/v1/templates/gallery	✅	✅	✅	قراءة القوالب
الإعدادات العامة	GET /wcpos/v1/settings/general	✅	✅	❌	للإدارة فقط
إعدادات الدفع	GET /wcpos/v1/settings/checkout	✅	✅	❌	للإدارة فقط
إعدادات رقم الضريبة	GET /wcpos/v1/settings/tax_ids	✅	✅	❌	للإدارة فقط
إعدادات بوابة الدفع	GET /wcpos/v1/settings/payment-gateways	✅	✅	❌	للإدارة فقط
كتالوج/إدارة الامتدادات	GET /wcpos/v1/extensions	✅	✅	❌	للإدارة فقط
السجلات	GET /wcpos/v1/logs	✅	✅	❌	للإدارة فقط

مصفوفة وصول نقاط النهاية لإضافة Pro

المجال	أمثلة على نقاط النهاية	Admin	Shop Manager	Cashier	ملاحظات
بيانات تعديل المتجر	GET /wcpos/v1/stores/{id}/edit	✅	✅	❌	إدارة المتجر
إنشاء المتجر	POST /wcpos/v1/stores	✅	✅	❌	إدارة المتجر
تحديث المتجر	PATCH /wcpos/v1/stores/{id}	✅	✅	❌	إدارة المتجر
تحديث إعدادات الترخيص	POST /wcpos/v1/settings/license	✅	✅	❌	إدارة Pro
إجراءات الامتدادات	POST /wcpos/v1/extensions/action	✅	❌	❌	تتطلّب صلاحية تثبيت/إدارة الإضافات
استرداد الطلبات	POST /wcpos/v1/orders/{id}/refunds	✅	✅	✅	تُعامَل كعملية نقطة بيع

تغطية انتهاء صلاحية الرمز

السيناريو	Admin	Shop Manager	Cashier	النتيجة المتوقعة
رمز وصول صالح	✅ مُختبر	✅ مُختبر	✅ مُختبر	نقاط النهاية المسموح بها لا تُعيد 401 أو 403
رمز وصول منتهي الصلاحية	✅ مُختبر	✅ مُختبر	✅ مُختبر	يفشل الطلب عند بوابة مصادقة WCPOS بمستخدم 0
رمز تحديث صالح بعد وصول منتهٍ	✅ مُختبر	✅ مُختبر	✅ مُختبر	يُصدَر رمز وصول جديد ويُستعاد الوصول
رمز تحديث منتهي الصلاحية	✅ مُختبر	✅ مُختبر	✅ مُختبر	لا يمكن إصدار رمز وصول جديد

تشخيص حالات الفشل

إذا رأى shop_manager افتراضي خطأ مثل:

Request still unauthorized after token refresh - please log in again

تشير مصفوفة نقاط النهاية إلى أن هذا ليس لأن دور shop_manager الافتراضي يفتقر جوهريًا إلى وصول نقطة البيع. الأسباب المحتملة الواجب التحقّق منها:

1. تلف الدور/الصلاحيات الخاص بالموقع.
2. نقطة نهاية غير مشمولة بالمصفوفة.
3. سلوك إعادة محاولة رمز وصول قديم أو منتهي الصلاحية في العميل.
4. تداخل من إضافة أمان أو مصادقة تابعة لجهة خارجية.
5. قواعد وصول خاصة بـ Pro أو بمتجر محدّد، أو شيفرة مخصّصة.

فشل الأذونات مقابل فشل الرمز

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

عادةً ما يبدو فشل الدور/الصلاحية الحقيقي هكذا:

status: 403
current_user: <actual user id>
access token expired: false

وعادةً ما يبدو فشل الرمز/المصادقة هكذا:

status: 403
current_user: 0
access token expired: true or invalid

استخدم هذا التمييز عند فرز مشكلات الوصول إلى نقطة البيع — فقيمة current_user غير الصفرية تشير إلى الصلاحيات، بينما current_user: 0 تشير إلى طبقة المصادقة/الرمز.