Shukah مقابل Locate

نظرة عامة

لا توجد وثائق لواجهات Shukah في أي مكان. وهذه الصفحة هي المكان الوحيد الذي كُتب فيه جانب Shukah: ما يرسله تطبيق الجوال إلى كل route من routes Shukah، وما يعود منه، وبماذا يختلف route Locate الذي يستبدله. وكل رابط «قارن مع Shukah» في صفحة endpoint يصل إلى قسم هنا.

كيفية الاستخدام:

• ابدأ بالجدولين أدناه. وانقر على route من Shukah للانتقال إلى قسمه.
• اقرأ الفروق الشاملة مرة واحدة. فعناوين URL الأساسية والـ tokens وأجسام الأخطاء والمعرّفات والتواريخ والـ headers تتغير بالطريقة نفسها في كل route، لذا لا تكررها الأقسام الواردة بعدها.
• يحتوي كل قسم على عنوان dev الكامل، والطلب الذي يرسله التطبيق، وأمر curl (محذوف للـ routes التي تحذف حسابًا أو تتلقى دفعة)، واستجابة Shukah الملتقطة، والأخطاء المشاهَدة، وللـ route المستبدَل رابط إلى صفحة Locate وجدول حقلًا بحقل.
• التُقطت عينات Shukah على dev في 2026-10-01 بعميل الاختبار 356259 على dev. وفي 2026-10-02 أرسل تدقيق تطابق (parity audit) المُدخل نفسه إلى Shukah وإلى Locate لكل route أمكن استدعاؤه بأمان، مع headers التطبيق 2.31.5؛ وينص أحد الأقسام على ذلك حين تأتي قيمة من تلك الجولة. وتُستبدل الحقول الشخصية في كل عينة بقيم توضيحية. والقيمة التي لا يُظهرها أي مصدر تُعلَّم بـ «غير موثّق بعد». وحيث تكون توقعات التطبيق نفسه هي المصدر الوحيد لجانب Shukah، ينص القسم على ذلك.
• $SHUKAH_BASE_URL هو https://dev-api.shukah.com و$SHUKAH_TOKEN هو token معتم (opaque) من Shukah. وتستخدم صفحات Locate $AUTH_BASE_URL و$ORDER_BASE_URL و$TOKEN.
• مدخلان من Shukah، تحديث الملف الشخصي و تحديث الإعداد، هما route Shukah نفسه. وهما صفّان لأن Locate تقسمهما إلى routeين.

المصادقة

واجهة Shukah	واجهة Locate	الخدمة	الحالة
GET /maeda/api/reset-otp	GET /api/v1/clients/reset-otp	auth-service	✅ تم الاستبدال
GET /maeda/api/verify-otp	GET /api/v1/clients/verify-otp	auth-service	✅ تم الاستبدال
GET /maeda/api/verify-token	GET /api/v1/clients/verify-token	auth-service	✅ تم الاستبدال
GET /maeda/client	GET /api/v1/clients	auth-service	✅ تم الاستبدال
GET /maeda/address-book	GET /api/v1/clients/address-book	auth-service	✅ تم الاستبدال
GET /maeda/address-book/:id	GET /api/v1/clients/address-book/:id	auth-service	✅ تم الاستبدال
POST /maeda/address-book	POST /api/v1/clients/address-book	auth-service	✅ تم الاستبدال
PUT /maeda/address-book/:id	PUT /api/v1/clients/address-book/:id	auth-service	✅ تم الاستبدال
DELETE /maeda/address-book/:id	DELETE /api/v1/clients/address-book/:id	auth-service	✅ تم الاستبدال
PUT /maeda/client/:client_id	PUT /api/v1/clients/:client_id	auth-service	✅ تم الاستبدال
PUT /maeda/client/:client_id	PUT /api/v1/clients/setting	auth-service	✅ تم الاستبدال
POST /maeda/client/add-device-id	POST /api/v1/clients/add-device-id	auth-service	✅ تم الاستبدال
GET /maeda/client/status	—	—	❌ لم يُستبدل
GET /maeda/client/delete	—	—	❌ لم يُستبدل

النقاط

واجهة Shukah	واجهة Locate	الخدمة	الحالة
GET /maeda/client/points	GET /api/v2/client/points	order-v2 → point-service	✅ تم الاستبدال
GET /maeda/point-rate	GET /api/v2/client/system_configs/point_rates	order-v2	✅ تم الاستبدال 🚩 enableMerchantService
GET /maeda/giftcard-code/use	POST /api/v2/client/gift-card-code	order-v2	✅ تم الاستبدال 🚩 enableMerchantService
GET /maeda/client/point-history	GET /api/v2/client/point-history	order-v2 → point-service	✅ تم الاستبدال
GET /maeda/point-offer	GET /api/v2/client/point-offers	order-v2 → point-service	✅ تم الاستبدال
GET /maeda/point-occasion	GET /api/v2/client/point-occasions	order-v2 → point-service	✅ تم الاستبدال
POST /maeda/point-order	POST /api/v2/client/point-orders	order-v2 → point-service	✅ تم الاستبدال 🚩 POINT_ORDER_POINT_ENABLED
POST /maeda/point-order/get-description	POST /api/v2/client/point-orders/description	order-v2 → point-service	✅ تم الاستبدال
POST /maeda/order/checkout-payment-standalone	POST /api/v2/client/point-orders/:correlation_id/pay/card	order-v2 → point-service	✅ تم الاستبدال 🚩 POINT_ORDER_CARD_ENABLED
POST /maeda/order/checkout-payment-flow	POST /api/v2/client/point-orders/:correlation_id/pay/session	order-v2 → point-service	✅ تم الاستبدال 🚩 POINT_ORDER_CARD_ENABLED
GET /maeda/points-faq	GET /api/v2/client/points-faq	order-v2 → point-service	✅ تم الاستبدال
GET /maeda/point-order	—	—	❌ لم يُستبدل
POST /maeda/order/checkout-payment	—	—	❌ لم يُستبدل
POST /maeda/order/checkout-payment-stcpay	—	—	❌ لم يُستبدل
POST /maeda/order/payfort-token	—	—	❌ لم يُستبدل
POST /maeda/order/payfort-stc-pay-checkout	—	—	❌ لم يُستبدل

حيث تختلف الوثائق عن الشيفرة

ادعاءات في نسخ سابقة من هذه الصفحة تناقضها التقاطات 2026-10-02 أو الشيفرة. وينص كل قسم الآن على ما وُجد.

• 2026-10-02: قال الـ Tokens إن JWT من Locate يعمل على routes النقاط في order-v2. وعلى dev صار يحصل على 401 الآن؛ ولا يعمل هناك إلا token من Shukah.
• 2026-10-02: قال المعرّفات (IDs) وأقسام الدفع الثلاثة إن التطبيق يرسل point_order_id كعدد صحيح. ويرسل التطبيق 2.31.5 سلسلة ("1252" و"1253").
• 2026-10-02: أعطى صيغ الأرقام وقسم الرصيد رصيد Shukah بالقيمة "128712.41"، أي نحو ربع رصيد Locate. وهو الآن "514853.64"، أي أعلى من Locate بـ 447.96 نقطة.
• 2026-10-02: لم يكن لـ reset-otp وتحديث الملف الشخصي وتحديث الإعداد وadd-device-id و قائمة الهدايا المرسَلة التقاط من Shukah. وصار لها الآن.
• 2026-10-02: أعطى verify-otp body الرمز الخاطئ مع type بنمط Yii. وفي body Shukah اليوم type من Symfony.
• 2026-10-02: لم يكن في قسم verify-otp التقاط من Shukah لاستدعاء ناجح. وفيه الآن: 200 {access_token, data}، بالملف الشخصي نفسه بـ 13 مفتاحًا وقيم متساوية كما في Locate، وتبقى الجلسات السابقة صالحة.
• 2026-10-02: أعطت قائمة العناوين 13 و28 عنوانًا، ولا عنوان افتراضيًا على Shukah وكلها افتراضية على Locate، وترتيبًا غير معروف على Shukah. وهي الآن 15 و30، وقيمة 0 على Shukah في الـ 15، وقيمة true على Locate في 28 من 30، وترتيب Shukah حسب position.
• 2026-10-02: لم تُظهر قائمة العناوين فرقًا في image_urls. وقد فقدت Locate روابط الصور للعناوين الأربعة من Shukah التي لها صورة.
• 2026-10-02: لم يُظهر قسم get العنوان فرقًا في is_default أو image_urls. والعنوان نفسه يساوي 0 على Shukah و1 على Locate، وله رابط صورة على Shukah و[] على Locate.
• 2026-10-02: قال قسم سجل النقاط إن أحدث مبالغ الكسب في Shukah (0.5 و0.5 و2.5) بمقياس مختلف عن مقياس Locate. وأحدث صفوف Shukah الآن 2 و2 و2 و2 و 10: لا فجوة في المقياس. وأحدث صف في Shukah هو 2026-10-01 17:00:01 لا 10:40:44، و8 من صفوف الكسب التسعة في Locate ضمن أول 10 صفوف لها description فارغ، لا أربعة من خمسة.
• 2026-10-02: توقع قسما إنشاء طلب النقاط و قائمة الهدايا المرسَلة وجود occasion_id. وترسل Shukah point_occasion_id.
• 2026-10-02: لم يكن في قسم إنشاء طلب النقاط التقاط من Shukah، ولم يُعرف هل يجيب create بصف الطلب. وفيه الآن التقاط: 201 مع المفاتيح الاثني عشر نفسها التي في صفوف الطلبات.
• 2026-10-02: لم يذكر قسم PayFort token أي استدعاء في Locate. ولدى order-v2 relay إلى route Shukah نفسه.
• 2026-10-02: كان GET /maeda/client/status مدرجًا بوصفه معرَّفًا لكن لا يُستدعى أبدًا. وتُظهر حركة الإنتاج 768 استدعاءً في 3 أيام، فصار له الآن قسم.

الفروق الشاملة

عناوين URL الأساسية

	Shukah	Locate
واجهات المصادقة (تسجيل الدخول والملف الشخصي ودفتر العناوين)	Dev https://dev-api.shukah.com/maeda/، وproduction https://api.shukah.com/maeda/ (وهو BASE_URL في التطبيق).	خدمة المصادقة، تُستدعى مباشرة. Dev https://dev.authentication.locate.sa، والبادئة /api/v1. و host الـ production: غير موثّق بعد.
واجهات النقاط	base URL الخاص بـ Shukah نفسه.	order-v2. Dev https://dev.v2.api.order.locate.sa، والبادئة /api/v2/client. وproduction https://v2.api.order.locate.sa/api/v2 (وهو BASE_URL_V2 في production للتطبيق). ويمرّر order-v2 معظم routes النقاط إلى خدمة النقاط، التي لا تُعرَض للتطبيق.

ما الذي يتغير بالنسبة إلى التطبيق:

• بادئتان جديدتان وواحدة اختفت. كل route في Shukah تحت /maeda. ولا يخدمها host المصادقة في Locate: فـ GET /maeda/api/verify-token على host المصادقة يجيب 404 (التُقط على dev، 2026-10-01). وتنتقل routes المصادقة إلى /api/v1/clients/…، وroutes النقاط إلى /api/v2/client/….
• الجزء api/ غير ثابت على Shukah. فـ routes تسجيل الدخول تحتويه (/maeda/api/reset-otp)؛ ودفتر العناوين لا يحتويه (/maeda/address-book). والاستدعاء /maeda/api/address-book على Shukah dev يجيب 404 (التُقط 2026-10-01).
• مسارات النقاط تصبح بصيغة الجمع. point-offer تصبح point-offers، وpoint-occasion تصبح point-occasions، وpoint-order تصبح point-orders.
• ليس للتطبيق base URL لخدمة المصادقة. لا يذكر أي ملف بيئة في التطبيق host المصادقة. أما base URL لـ order-v2 (BASE_URL_V2) فموجود، ويستخدمه بالفعل في بعض استدعاءات وضع Merchant.
• بناء الـ URL. يضم التطبيق base URL ثم / ثم الـ endpoint، ثم query مرتبة بحسب المفتاح. ولا فرق في وجود شرطة مائلة في بداية الـ endpoint.

الـ Tokens

تُصدر Shukah token معتمًا (opaque). وتُصدر Locate JWT (بخوارزمية HS256، والحمولة {client_id, phone}) لا ينتهي أبدًا. ويوضع كلاهما في Authorization: Bearer <token>.

لا يوجد اليوم token واحد يعمل على الخدمتين. أي route في Locate يقبل أي token (dev، التُقط في 2026-10-02 بالـ token كليهما على كل route أمكن استدعاؤه بأمان):

routes الـ Locate	الـ Token
المصادقة: reset-otp وverify-otp وexchange-token وadd-device-id	لا حاجة إلى token.
المصادقة: verify-token وclient lookup وroutes دفتر العناوين الخمسة وupdate profile وupdate setting	JWT من Locate فقط. وtoken من Shukah يحصل على 401 مع {"status":401,"message":"Unauthorization"} (التُقط).
المصادقة: تفاصيل المستخدم (GET /api/v1/users)	يحتاج إلى header اسمه x-auth-from (و422 بدونه). ومع x-auth-from: SHUKAH وكون auth_source على dev هو shukah، يفحص Shukah على dev الـ token: فيمرّ token من Shukah ويُرفض JWT من Locate. ومع ضبط auth_source على locate يحصل كل JWT من Locate على 401 (عيب).
routes النقاط في order-v2 (الرصيد والسجل والأسئلة الشائعة والعروض والمناسبات وطلبات النقاط)	token من Shukah فقط. وJWT من Locate يحصل على 401 {"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid or expired token"}} على routes الرصيد والسجل والأسئلة الشائعة والعروض والمناسبات (التُقط). وتستخدم routes طلبات النقاط الفحص نفسه. وفي 2026-10-01 كان JWT من Locate لا يزال يحصل على 200 على route الرصيد.
معدلات الكسب في order-v2	لا حاجة إلى token: عام. 200 دون token، ومع token من Shukah، ومع JWT من Locate (التُقط).
كود بطاقة الهدية في order-v2	الفحص نفسه الخاص بـ routes النقاط، أي token من Shukah فقط (قراءة شيفرة؛ لم يُستدعَ مع token، لأنه يضيف نقاطًا).

لماذا (من الشيفرة على origin/develop): يشغّل حارس client في خدمة المصادقة jwt.verify، فلا يمرّ token معتم من Shukah. وتسأل خدمة النقاط وorder-v2 خدمة المصادقة عن هوية المستدعي مع x-auth-from: SHUKAH: فحارس order-v2 يكتبها في الشيفرة، وترسلها خدمة النقاط افتراضيًا (إعدادها AUTH_VERIFY_APPLICATION). وإعداد auth_source على dev هو shukah (قُرئ من إعدادات العميل العامة في 2026-10-02)، لذا تمرّر خدمة المصادقة الـ token إلى Shukah على dev، التي ترفض JWT من Locate (استنتاج من 401: لم يُستدعَ verify-token في Shukah على dev مع الـ JWT نفسه). وفي 2026-10-01 كانت Shukah لا تزال تقبله. وضبط auth_source على locate لن يفيد وحده: ففي ذلك الفرع يحصل كل JWT من Locate على 401، بسبب عيب موصوف في تفاصيل المستخدم. فيحتاج التطبيق اليوم إلى الـ token كليهما: الـ JWT لخدمة المصادقة، وtoken من Shukah لـ order-v2.

وتجيب Shukah نفسها على أربعة routes دون token: point-offer وpoint-occasion وpoint-rate و points-faq. أما Locate فتحتاج token للعروض والمناسبات والأسئلة الشائعة.

يحوّل استبدال الـ token token في أي من الاتجاهين (target_platform هو locate أو shukah). ولا يستدعيه التطبيق أبدًا. لذا فالمستخدم المسجَّل الدخول بـ token من Shukah والذي يستدعي verify-token في Locate يحصل على 401، ويحذف التطبيق الـ token المخزَّن عند ذلك 401 (verify-token وحذف الحساب فقط يفعلان ذلك)، مما يسجّل خروج المستخدم. أما routes التي تبقى على Shukah (حذف الحساب، وقائمة الهدايا المرسَلة، ومدفوعات PayFort وFrames) فما زالت تحتاج إلى token تقبله Shukah: فتدفع Locate كل JWT تصدره إلى Shukah بذل أقصى جهد (best effort) (خلف إعداد على الخادم)، أو يستطيع التطبيق الاستبدال بـ token من Shukah عبر target_platform: "shukah". وفي 2026-10-02 لم تعد Shukah على dev تقبل الـ JWT من Locate (انظر أعلاه)، فلا يمكن الاعتماد على ذلك الدفع هناك.

أجسام الأخطاء

تلتقي خمسة أشكال للأخطاء في هذا الترحيل. وهنا body حقيقي واحد لكل منها:

المُرسِل	Body حقيقي	أين التُقط
Shukah (Laravel، فحوص اليوم)	{"name":"Unauthorized","message":"Your request was made with invalid credentials.","code":0,"status":401,"type":"Illuminate\\Auth\\AuthenticationException"}	GET /maeda/api/verify-token دون token، dev، 2026-10-01. وتحمل المفاتيح name وcode وstatus وtype نفسها 404 ({"name":"Not Found","message":"Object not found: 162119",…,"type":"Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException"}، get للعنوان بعد حذفه، 2026-10-01).
Shukah (Yii، التقاط أقدم)	{"name":"Bad Request","message":"Last Name cannot be blank.","code":0,"status":400,"type":"yii\\web\\BadRequestHttpException"}	من استدعاء reset-otp في Shukah، في التقاط يوليو 2026 المحفوظ في الوثيقة المسودة لخدمة المصادقة (api-auth-draft.md، 2026-07-07). وهل ما زالت Shukah ترسله: غير موثّق بعد. وكذلك 400 الخاص بـ reset-otp وclient-lookup في خدمة المصادقة نفسها يستخدم شكل Yii هذا.
خدمة المصادقة	{"status":401,"message":"Unauthorization"}	GET /api/v1/clients/verify-token، دون token، dev، 2026-10-01. و500 هو {"status":500,"message":"Internal server error"} في production. وعلى dev يحمل نص الخطأ الخام وحقل stack.
خدمة النقاط (عبر order-v2)	{"success":false,"error":{"code":"UNAUTHORIZED","message":"Missing or invalid authorization header"}}	GET /api/v2/client/points، دون token، dev، 2026-10-01. ويُضاف مفتاح details لأخطاء التحقق. ويبني order-v2 أجسام 502 و504 بالشكل نفسه.
order-v2 نفسه (Nest)	{"message":"Unauthorized","statusCode":401}	POST /api/v2/client/gift-card-code، دون token، dev، 2026-10-01.

كيف يعرضها التطبيق: الحالة 400 أو أكثر تصبح خطأً رسالته هي body.message، أو الـ body كله كسلسلة JSON عندما لا يوجد message في المستوى الأعلى. وبذلك:

• تُظهر أجسام Shukah وخدمة المصادقة وNest الـ message الخاصة بها. أما المفاتيح name وtype وcode و statusCode فلا تُقرأ أبدًا.
• غلاف خدمة النقاط لا يحتوي message في المستوى الأعلى، لذا سيعرض التطبيق للمستخدم سلسلة JSON الخام {"success":false,"error":{…}} ما لم يقرأ error.message بنفسه.
• الـ body الذي ليس JSON (صفحة 404 بصيغة HTML) يصبح {message: <text>}.
• يفتح التطبيق خطأً عامًا (global error) عند 403 و500 و502 و503 و504 و505 افتراضيًا. وتجيب flags طلبات النقاط بـ 403، فهذا خطأ حرج ما لم تُغيَّر قائمة الحالات.
• تظل إشارة التسجيل تعمل إذا بقي النص كما هو: فيفتح التطبيق شاشة التسجيل عندما يجيب reset-otp بـ 400 وتحتوي الرسالة على Last Name.

المعرّفات (IDs)

الشيء	Shukah	Locate
العميل	client_id عدد صحيح (356259).	العدد نفسه للعميل المرحَّل. والعملاء المسجَّلون في Locate يحصلون على معرّفات من 1,000,000,001.
العنوان	id عدد صحيح (162115).	سلسلة hex من 24 حرفًا (6abbeed8a492ed4862500b74). والقيمة المكوَّنة من أرقام فقط في المسار تُجرَّب أولًا بوصفها معرّف Shukah القديم.
عرض النقاط، مناسبة النقاط	id عدد صحيح، من 1 إلى 5 ومن 1 إلى 7.	سلسلة hex من 24 حرفًا. والعدد الصحيح من Shukah المُرسَل إلى Locate يعطي 400.
طلب النقاط	point_order_id، وهو رقم في قائمة طلبات Shukah. وترسله أجسام الدفع في التطبيق 2.31.5 كسلسلة، "1252" (التُقط على dev، 2026-10-02).	correlation_id من نوع UUID، في مسار routes get والدفع. وpoint_order_id في الـ body يُتجاهل. وorder_no (من 100000) هو الرقم المقروء.
صف سجل النقاط	id عدد صحيح في صفوف المصروفات، وshukah_id في صفوف الكسب.	id من 24 حرف hex في صفوف المصروفات. وshukah_id هو null للصفوف التي كتبتها Locate بنفسها.

يعرّف التطبيق كل معرّف كرقم. ويحوّل استدعاء delete-address لديه المعرّف إلى رقم بعلامة الجمع الأحادية (unary plus)، لذا يصبح المعرّف المكوَّن من 24 حرف hex NaN. أما معرّفات العروض والمناسبات فتصل إلى Locate كنص وتعمل.

ترقيم الصفحات (Pagination)

الاستدعاء	Shukah	Locate
سجل النقاط	لا شيء: السجل كله في مصفوفة واحدة (8,134 صفًا للعميل 356259 في 2026-10-01، 2.3 ث؛ و8,136 في 2026-10-02).	query بالمفتاحين page وlimit. الافتراضي 20، والحد الأقصى 100. لا إجمالي ولا علامة للصفحة التالية. ولا يرسل التطبيق أيًّا منهما.
قائمة الهدايا المرسَلة (GET point-order)	query بالمفتاحين page وper-page. والإجماليات في headers الاستجابة x-pagination-total-count وx-pagination-page-count.	لا route.
قائمة العناوين، العروض، المناسبات، الأسئلة الشائعة، المعدلات	لا شيء.	لا شيء.

التواريخ والمناطق الزمنية

يستخدم الجانبان توقيت ساعة الرياض (Asia/Riyadh، UTC+3، دون توقيت صيفي) لصفوف السجل (ledger)، ودون علامة منطقة زمنية.

القيمة	Shukah	Locate
date_created في سجل النقاط	YYYY-MM-DD HH:mm:ss، بتوقيت الرياض.	الصيغة والمنطقة نفسهما.
pointsExpirationDate	YYYY-MM-DD.	YYYY-MM-DD، تاريخ بتوقيت الرياض.
birth_date	YYYY-MM-DD.	YYYY-MM-DD: تاريخ UTC للقيمة المكتوبة.
date_created لنتيجة بطاقة الهدية	غير موثّق بعد.	yyyy-mm-dd hh:mm:ss، بالتوقيت العربي (UTC+3).
created_at وupdated_at للعنوان	لا يُرجعان.	ISO 8601 بتوقيت UTC (2026-09-29T17:01:10.000Z)، في إجابتَي list وcreate فقط.

صيغ الأرقام

القيمة	Shukah	Locate
رصيد النقاط points	سلسلة بخانتين عشريتين: "514853.64" (2026-10-02).	سلسلة بحتى أربع خانات عشرية، مع حذف الأصفار اللاحقة: "514405.6788". و"0" عند عدم وجود حساب. ويحوّل التطبيق بـ Number(points) || 0.
total_points في السجل	رقم في صفوف الكسب، وسلسلة بخانتين عشريتين في صفوف المصروفات ("684.00"، قاسها فريق خدمة النقاط في 2026-07-17).	رقم في صفوف الكسب وسلسلة بخانتين عشريتين بالضبط في صفوف المصروفات ("360.00").
amount للعرض، money_amount للطلب	amount سلسلة بخانتين عشريتين: "40.00".	amount كذلك؛ وmoney_amount للطلب سلسلة بخانتين عشريتين.
point_amount وpurchased_point_amount للعرض	أعداد صحيحة.	أرقام. ويمكن أن تكون purchased_point_amount بقيمة null عندما لا يكون للعرض سعر بالنقاط.
lat وlng للعنوان	أرقام JSON في كل route.	أرقام في list وcreate، وسلاسل نصية في get وupdate.
is_default للعنوان	0 أو 1 في نوع التطبيق. و0 في كل عنوان وكل route في التقاطات 2026-10-02.	boolean في list وcreate، و0 أو 1 في get وupdate (تؤكده الشيفرة والتقاطات 2026-10-02).
sex وreceive_offers وpush_enabled	أعداد صحيحة (sex بقيمة 0 أو 1 أو 2 أو 9).	أعداد صحيحة. وsex بقيمة 9 تُخزَّن «غير معروف» وتُقرأ لاحقًا 0.

Headers الطلب

الطلب. يرسل التطبيق هذه مع كل استدعاء إلى Shukah (ومع استدعاءات order-v2):

Header أو query	القيمة	Locate
Authorization	Bearer <stored token> عند تسجيل الدخول.	مطلوب في routes المحمية. انظر الـ Tokens.
Accept وContent-Type	application/json.	Content-Type: application/json مطلوب في routes POST الخاصة بـ order-v2 التي تقرأ body.
x-from-application	LOCATE_CLIENT_V2.	تتجاهله خدمة المصادقة. ولا يمرّره order-v2 إلى خدمة النقاط.
from-application وx-from-version	وضع التطبيق وإصداره.	الأمر نفسه: يُتجاهل أو لا يُمرَّر.
language (query)	en-GB، أو ar-SA لأي لغة أخرى.	تتجاهله خدمة المصادقة، عدا reset-otp الذي يخزّن الجزء الذي قبل -. وتتجاهله routes النقاط، وتسمية المناسبة عربية فقط عندما تكون language هي ar بالضبط.
key (query)	maeda، ويُرسل فقط مع reset-otp والبحث بالهاتف.	يُتجاهل.
x-auth-from	SHUKAH، ويرسله فقط المساعد shukahApi في التطبيق، لا العميل الرئيسي.	تضبط خدمة النقاط قيمتها بنفسها عندما تستدعي خدمة المصادقة. ولا يحتاج التطبيق إلى إرساله.

أما التقاطات 2026-10-01 فلم ترسل سوى Accept، إضافةً إلى x-from-application وContent-Type على عمليات الكتابة، مع الـ token، وحصلت على 200. وأرسلت التقاطات 2026-10-02 headers التطبيق 2.31.5 (x-from-application وfrom-application وx-from-version: 2.31.5 وx-user-id وAccept) و ?language=en-GB على الجانبين. ولا يرسل التطبيق x-device-id.

الاستجابة: headers إصدار التطبيق. يقرأ التطبيق new_version وold_version وhas_new_version و is_required_update من استجابة أي استدعاء يحتوي URL الخاص به على api/verify-token أو client/points، ويعرض نافذة التحديث المنبثقة اعتمادًا عليها. وهل ترسلها Shukah: غير موثّق بعد (فالالتقاطات تخزّن headers الطلب فقط). ولا ترسلها أي خدمة من Locate. وURL الخاص بـ verify-token في Locate (/api/v1/clients/verify-token) لا يحتوي api/verify-token، لذا لن يبحث التطبيق هناك. أما URL النقاط في Locate فيحتوي client/points، لكن لا شيء يضبط الـ headers. فإذا كانت Shukah ترسلها اليوم، فستتوقف نافذة التحديث بصمت بعد التحوّل. انظر التحقق من الـ token.

الاستجابة: headers الترقيم. تقرأ قائمة الهدايا المرسَلة x-pagination-total-count و x-pagination-page-count. انظر ترقيم الصفحات.

واجهات المصادقة

GET /maeda/api/reset-otp

البديل في Locate: GET /api/v1/clients/reset-otp

عنوان dev الكامل: https://dev-api.shukah.com/maeda/api/reset-otp

يؤدي route واحد تسجيل الدخول والتسجيل معًا. دون Authorization: فالمستخدم مسجَّل الخروج.

الطلب (من التطبيق). يرسل تسجيل الدخول contact_phone (أرقام فقط، دون +) وkey=maeda و language. ويضيف التسجيل first_name وlast_name وemail_address واختياريًا sex (0 أو 1 أو 2 أو 9) وbirth_date (yyyy-mm-dd) وreceive_offers (يُرسل 1 فقط عندما يوافق المستخدم، ولا يُرسل 0 أبدًا).

# Sends a real SMS to the phone. Use a test-mode number.
curl -s -G "$SHUKAH_BASE_URL/maeda/api/reset-otp" --data-urlencode "contact_phone=$PHONE" --data-urlencode "key=maeda" --data-urlencode "language=en-GB"

استجابة Shukah الملتقطة. 200، 895 ms، لهاتف معروف (التُقط على dev، 2026-10-02؛ وقد أرسل رسالة SMS واحدة). وأجابت Locate بالـ body نفسه. ونوع التطبيق المحلَّل هو {status: any}. أما الوثيقة المسودة لخدمة المصادقة (api-auth-draft.md، 2026-07-07)، من استدعاء إلى Shukah على dev، فتُظهر {"status": true} نفسه للتسجيل.

{
  "status": true
}

الأخطاء المشاهَدة.

• هاتف مفقود، 400، بالعربية ومع type من Laravel (التُقط على dev، 2026-10-01، مع key=maeda ودون language): {"name":"Bad Request","message":"حقل contact phone مطلوب.","code":0,"status":400,"type":"Illuminate\\Validation\\ValidationException"}
• هاتف غير معروف دون حقول تسجيل، 400، في التقاط يوليو 2026 المحفوظ في الوثيقة المسودة لخدمة المصادقة (api-auth-draft.md، 2026-07-07): {"name":"Bad Request","message":"Last Name cannot be blank.","code":0,"status":400,"type":"yii\\web\\BadRequestHttpException"}. وهي إشارة التطبيق لفتح التسجيل. وهل ما زالت Shukah ترسل هذا النص اليوم: غير موثّق بعد.

الحقل	Shukah	Locate	ملاحظة
contact_phone (query)	أرقام فقط، ويحذف التطبيق +.	تُحذف المسافات، ويُطابَق بوجود + في البداية أو بدونه. لا فحص للصيغة.	الفارغ يعطي 400 في الاثنين.
key (query)	maeda.	يُتجاهل.	يمكن للتطبيق مواصلة إرساله.
first_name وlast_name وemail_address (query)	حقول التسجيل.	مطلوبة عندما لا يكون لأي عميل نشط هذا الهاتف. وتُفحص بترتيب: اسم العائلة، فالاسم الأول، فالبريد.	الاستدعاء المجرد لهاتف غير معروف يحصل على Last Name cannot be blank. في Locate. ونص Shukah الحالي: غير موثّق بعد.
sex (query)	0 أو 1 أو 2 أو 9.	1 ذكر، 2 أنثى. وأي قيمة أخرى تُخزَّن «غير معروف».
birth_date (query)	yyyy-mm-dd.	يُقرأ كتاريخ ويُخزَّن بالصيغة YYYY-MM-DD. والقيمة السيئة تُخزَّن فارغة بصمت.
receive_offers (query)	يُرسل 1 فقط.	لا يُقرأ. والعميل الجديد يبدأ وهو معطَّل.
language (query)	en-GB أو ar-SA.	تُخزَّن الجزء الذي قبل -، بأحرف صغيرة. والمفقودة تصبح ar.	لا تغيّر لغة SMS (العربية).
status (الاستجابة)	true.	true. وهي true أيضًا عندما يكون هناك رمز معلّق ولم تُرسل SMS جديدة.	لا تقرأ true على أنها «أُرسلت SMS».
خطأ الهاتف المفقود	رسالة بالعربية، وtype من Laravel.	{"name":"Bad Request","message":"Phone number cannot be blank.","code":0,"status":400,"type":"yii\\web\\BadRequestHttpException"} (التُقط على dev، 2026-10-01).	المفاتيح نفسها، لكن النص وtype يختلفان.

GET /maeda/api/verify-otp

البديل في Locate: GET /api/v1/clients/verify-otp

عنوان dev الكامل: https://dev-api.shukah.com/maeda/api/verify-otp

الطلب (من التطبيق). Query بالمفاتيح contact_phone وcode (4 أرقام) وfcm_token (يُحذف عندما يتعذّر على التطبيق الحصول على واحد) وplatform (Android أو iOS أو Huawei) وlanguage. دون key. ودون Authorization.

# Uses up the code and returns a new token. Use a test-mode number.
curl -s -G "$SHUKAH_BASE_URL/maeda/api/verify-otp" --data-urlencode "contact_phone=$PHONE" --data-urlencode "code=$CODE" --data-urlencode "platform=iOS"

استجابة Shukah الملتقطة. 200 على dev، 2026-10-02 (الرمز الصحيح 2022، وplatform=iOS، بلا token). قيمة access_token مُخفاة، فلم يُسجَّل هنا نوعها. أما ملف data الشخصي فهو الحقول الـ 13 نفسها بقيم متساوية كما في Locate.

{
  "access_token": "<redacted>",
  "data": {
    "client_id": 356259,
    "odoo_id": "1342170",
    "contact_phone": "+966500000000",
    "status": "active",
    "email_address": "user@example.com",
    "first_name": "Test",
    "last_name": "User",
    "sex": 1,
    "birth_date": "1990-01-01",
    "receive_offers": 0,
    "push_enabled": 0,
    "is_food_truck_user": 1,
    "is_cod_disabled": 0
  }
}

ظل الـ tokens اللذان صدرا سابقًا يعملان بعد هذا الاستدعاء (Shukah GET /maeda/client/points 200): فتسجيل الدخول الجديد لا ينهي الجلسات السابقة. وما تفعله Shukah بـ fcm_token وplatform ما زال غير ظاهر في الاستجابة.

الأخطاء المشاهَدة. رمز خاطئ، 400 (التُقط على dev، 2026-10-02): {"name":"Bad Request","message":"Sorry, but your verification code is incorrect","code":0,"status":400,"type":"Symfony\\Component\\HttpKernel\\Exception\\HttpException"}. وكان في التقاط يوليو 2026 المحفوظ في الوثيقة المسودة لخدمة المصادقة (api-auth-draft.md، 2026-07-07) الرسالة نفسها مع type بنمط Yii هو yii\\web\\BadRequestHttpException.

الحقل	Shukah	Locate	ملاحظة
contact_phone (query)	أرقام.	تُحذف المسافات، ويُطابَق بوجود + أو بدونها.
code (query)	4 أرقام.	يُقارَن كنص، لذا فالصفر في البداية مهم.
fcm_token (query)	يُرسل عندما يملكه التطبيق. وما تفعله Shukah به: غير موثّق بعد.	يُسقَط.	إذا كانت Shukah تستخدمه فإن ذلك يضيع. ويحفظ التطبيق أيضًا FCM token الخاص به على حدة، في order-v2 (client/fcm/save-token).
platform (query)	Android أو iOS أو Huawei. وما تفعله Shukah به: غير موثّق بعد.	يُسقَط.
language (query)	يُرسل.	يُتجاهل.
access_token (الاستجابة)	token معتم (opaque) من Shukah.	JWT من Locate، لا ينتهي أبدًا.	كل استدعاء لاحق إلى /api/v1/clients/* يحتاج هذا الـ JWT.
data (الاستجابة)	الملف الشخصي نفسه بالحقول الـ 13 كما في Locate، بقيم متساوية (التُقط على dev، 2026-10-02).	الملف الشخصي ذو الحقول الـ 13، كما في verify-token.	لا شيء: تطابق الشكل والقيم في زوج استدعاءات 2026-10-02.
خطأ الرمز الخاطئ	body بنمط Laravel أعلاه (type من Symfony).	{"status":400,"message":"Sorry, but your verification code is incorrect"} (التُقط على dev، 2026-10-01 و2026-10-02).	اختفت name وcode وtype. ورسالة واحدة تشمل الخاطئ والمنتهي والمستخدم والهاتف المجهول.

GET /maeda/api/verify-token

البديل في Locate: GET /api/v1/clients/verify-token

عنوان dev الكامل: https://dev-api.shukah.com/maeda/api/verify-token

الطلب. Authorization: Bearer <stored token> وlanguage. ويضبط التطبيق أيضًا Accept و Content-Type وx-from-application: LOCATE_CLIENT_V2 صراحةً في هذا الاستدعاء. ويعمل عند كل بدء للتطبيق ومرة أخرى عند فتح الشاشة الرئيسية (Home).

curl -s "$SHUKAH_BASE_URL/maeda/api/verify-token" -H "Authorization: Bearer $SHUKAH_TOKEN"

استجابة Shukah الملتقطة. 200، 731 ms.

{
  "client_id": 356259,
  "odoo_id": "1342170",
  "contact_phone": "+966500000000",
  "status": "active",
  "email_address": "user@example.com",
  "first_name": "Test",
  "last_name": "User",
  "sex": 1,
  "birth_date": "1990-01-01",
  "receive_offers": 0,
  "push_enabled": 0,
  "is_food_truck_user": 1,
  "is_cod_disabled": 0
}

التُقط على dev، 2026-10-01 (العميل 356259)؛ واستُبدلت الحقول الشخصية. وفي 2026-10-02 تطابق body Shukah وbody Locate (مع JWT من Locate) من جديد، مفتاحًا بمفتاح. ويتجاهل نوع الملف الشخصي في التطبيق odoo_id وis_food_truck_user وis_cod_disabled.

الأخطاء المشاهَدة. لا token، 401 (التُقط على dev، 2026-10-01): body بنمط Laravel المبيّن تحت أجسام الأخطاء. وعند أي 401 يحذف التطبيق الـ token المخزَّن.

الحقل	Shukah	Locate	ملاحظة
client_id وodoo_id وcontact_phone وstatus وemail_address وfirst_name وlast_name وsex وbirth_date وreceive_offers وpush_enabled وis_food_truck_user وis_cod_disabled (الاستجابة)	المفاتيح الـ 13 أعلاه.	المفاتيح الـ 13 نفسها والأنواع والقيم نفسها للعميل 356259 (التُقط على dev، 2026-10-01).	الـ body بديل مباشر (drop-in).
Authorization (header)	token معتم (opaque) من Shukah.	JWT من Locate فقط.	token من Shukah يحصل على 401. انظر الـ Tokens.
language وx-from-application وغيرها من الـ headers	تُرسل.	تُقبل وتُتجاهل.
body الخاص بـ 401	body بنمط Laravel أعلاه.	{"status":401,"message":"Unauthorization"} (التُقط على dev، 2026-10-01).	يجب تغيير أي شيء يطابق النص أو name أو type.
headers استجابة إصدار التطبيق	هل ترسلها Shukah: غير موثّق بعد.	لا تُرسل. وURL الخاص بـ Locate لا يحتوي api/verify-token.	انظر Headers الطلب.

GET /maeda/client

البديل في Locate: GET /api/v1/clients

عنوان dev الكامل: https://dev-api.shukah.com/maeda/client?contact_phone=<digits>&key=maeda&language=en-GB

يُستخدم لإيجاد مستلم هدية بالهاتف. الطلب. Bearer token. وquery بالمفاتيح contact_phone (أرقام، ويحذف التطبيق +) وkey=maeda وlanguage.

curl -s -G "$SHUKAH_BASE_URL/maeda/client" -H "Authorization: Bearer $SHUKAH_TOKEN" --data-urlencode "contact_phone=$PHONE" --data-urlencode "key=maeda"

استجابة Shukah الملتقطة. 200، 867 ms. مصفوفة بكائن واحد.

[
  {
    "client_id": 356259,
    "contact_phone": "+966500000000",
    "first_name": "Test",
    "last_name": "User"
  }
]

التُقط على dev، 2026-10-01 (العميل 356259)؛ واستُبدلت الحقول الشخصية. وقد استبدل الالتقاط last_name، لذا لا يظهر هل تقنّعه Shukah: غير موثّق بعد.

الأخطاء المشاهَدة. لا token، 401، body بنمط Laravel (التُقط على dev، 2026-10-01). ويأخذ التطبيق الصف الأول فقط ويعامل المصفوفة الفارغة على أنها "User not found".

الحقل	Shukah	Locate	ملاحظة
client_id (الاستجابة)	عدد صحيح.	عدد صحيح.
contact_phone (الاستجابة)	الهاتف.	الهاتف كما خُزِّن، غير مقنَّع.
first_name (الاستجابة)	الاسم الأول.	تُحذف المسافات الزائدة؛ والفارغ يصبح null. غير مقنَّع.
last_name (الاستجابة)	غير موثّق بعد (لا يمكن رؤية التقنيع في الالتقاط).	مقنَّع: يُحتفظ بالحرف الأول والأخير ويتحول ما بينهما إلى * (User تصبح U**r)؛ والحرف أو الحرفان يبقيان كما هما.	ينسخه التطبيق من الصف الأول. افحص تدفق الهدية.
هاتف غير معروف	غير موثّق بعد.	200 مع []، وكذلك لعميل غير نشط.	يعامل التطبيق [] بالفعل على أنها "User not found".
Authorization (header)	token من Shukah.	JWT من Locate فقط.	انظر الـ Tokens.
key وlanguage (query)	تُرسل.	تُتجاهل.
body الخاص بـ 401	body بنمط Laravel.	{"status":401,"message":"Unauthorization"}.

GET /maeda/address-book

البديل في Locate: GET /api/v1/clients/address-book

عنوان dev الكامل: https://dev-api.shukah.com/maeda/address-book (دون الجزء api/).

الطلب. Bearer token. ولا معاملات سوى language.

curl -s "$SHUKAH_BASE_URL/maeda/address-book" -H "Authorization: Bearer $SHUKAH_TOKEN"

استجابة Shukah الملتقطة. 200، 770 ms. مصفوفة مسطّحة من 13 عنوانًا للعميل 356259؛ وأولها:

{
  "id": 162115,
  "location_name": "Saihat",
  "is_default": 0,
  "formatted_address": "King Fahd Rd, Al Olaya, Riyadh 12211",
  "area_name": "A12345",
  "street": "King Fahd Rd",
  "city": "Saihat",
  "area": "Eastern Province",
  "state": "Al-Qatif",
  "zipcode": "32461",
  "country": "Saudi Arabia",
  "country_code": "SA",
  "lat": 24.7136,
  "lng": 46.6753,
  "image_urls": ["https://example.com/address-photo.jpg"],
  "position": 0
}

التُقط على dev، 2026-10-01 (العميل 356259)؛ واستُبدلت الحقول الشخصية والإحداثيات. لا واحد من أول 10 عناوين افتراضي. وفي 2026-10-02 كان في القائمة 15 عنوانًا، كلها بـ is_default يساوي 0، مرتبة حسب position من 0 إلى 14 بينما المعرّفات ليست مرتبة (162115 و161996 و162101 و…).

الأخطاء المشاهَدة. لا شيء لهذا الـ route. والمسار /maeda/api/address-book يجيب 404 {"name":"Not Found","message":"The route maeda/api/address-book could not be found.",…} (التُقط 2026-10-01): ولا يستدعيه التطبيق.

الحقل	Shukah	Locate	ملاحظة
id	عدد صحيح (162115).	سلسلة من 24 حرفًا.	يعرّفه التطبيق كرقم.
is_default	0 أو 1.	Boolean.	اختبار truthiness يعمل مع الاثنين. لكن المقارنة الصارمة مع 1 لن تعمل.
location_name وformatted_address وarea_name وstreet وcity وarea وstate وzipcode وcountry وcountry_code	سلاسل.	سلاسل، وnull عند الغياب (شكل القائمة).
lat وlng	أرقام JSON.	أرقام JSON في القائمة.
image_urls	مصفوفة أو null. لأربعة من العناوين الـ 15 رابط صورة (2026-10-02).	مصفوفة دائمًا. و[] في نسخ Locate من هذه العناوين الأربعة (2026-10-02).	تضيع الصور عند النسخ إلى Locate. السبب: غير موثّق بعد.
position	عدد صحيح.	لا يُرجَع.	لا يقرؤه التطبيق.
source وcreated_at وupdated_at	لا تُرجَع.	source (mt_client_inline أو mt_address_book أو locate) والتاريخان بصيغة ISO UTC.	لا يقرؤها التطبيق.
الترتيب	حسب position، من 0 إلى 14 (التُقط على dev، 2026-10-02).	الأحدث created_at أولًا.	قد تظهر القائمة بترتيب مختلف.
العدد للعميل 356259	15 عنوانًا (2026-10-02؛ و13 في 2026-10-01).	30 عنوانًا، للعميل نفسه واليوم نفسه (و28 في 2026-10-01).	عمليات الحذف التي تتم على Shukah لا تصل إلى Locate أبدًا، ويظهر عنوان واحد ثلاث مرات.
العناوين الافتراضية	is_default يساوي 0 في العناوين الـ 15 كلها (2026-10-02).	true في 28 من 30 (2026-10-02).	يأخذ التطبيق أول عنوان افتراضي يجده.
Authorization	token من Shukah.	JWT من Locate فقط.

GET /maeda/address-book/:id

البديل في Locate: GET /api/v1/clients/address-book/:id

عنوان dev الكامل: https://dev-api.shukah.com/maeda/address-book/<id>

الطلب. Bearer token. والمسار id، عدد صحيح من القائمة.

curl -s "$SHUKAH_BASE_URL/maeda/address-book/$ADDRESS_ID" -H "Authorization: Bearer $SHUKAH_TOKEN"

استجابة Shukah الملتقطة. 200، 286 ms: المفاتيح الـ 16 نفسها كما في عنصر القائمة أعلاه، مسطّحة.

{
  "id": 162115,
  "location_name": "Saihat",
  "is_default": 0,
  "formatted_address": "King Fahd Rd, Al Olaya, Riyadh 12211",
  "area_name": "A12345",
  "street": "King Fahd Rd",
  "city": "Saihat",
  "area": "Eastern Province",
  "state": "Al-Qatif",
  "zipcode": "32461",
  "country": "Saudi Arabia",
  "country_code": "SA",
  "lat": 24.7136,
  "lng": 46.6753,
  "image_urls": ["https://example.com/address-photo.jpg"],
  "position": 0
}

التُقط على dev، 2026-10-01 (العميل 356259)؛ واستُبدل نص العنوان والإحداثيات.

الأخطاء المشاهَدة. بعد الحذف، 404 (التُقط على dev، 2026-10-01): {"name":"Not Found","message":"Object not found: 162119","code":0,"status":404,"type":"Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException"}. عنوان عميل آخر (المعرّف 1)، 403 (التُقط على dev، 2026-10-02): {"name":"Forbidden","message":"You can only view address that belong to you.","code":0,"status":403,"type":"Symfony\\Component\\HttpKernel\\Exception\\AccessDeniedHttpException"}.

الحقل	Shukah	Locate	ملاحظة
id	عدد صحيح.	سلسلة من 24 حرفًا. ومعرّف Shukah العددي ما زال يعمل في المسار للعناوين التي جاءت من Shukah.	يقارن التطبيق معرّف آخر عنوان محدَّد مخزَّنًا لديه كسلسلة، لذا فالعدد الصحيح المحفوظ من Shukah لم يعد يطابق.
is_default	0 أو 1.	0 أو 1.	النوع نفسه، لكن ليس القيمة دائمًا: العنوان 162115 يساوي 0 على Shukah و1 على Locate (2026-10-02).
lat وlng	أرقام JSON.	سلاسل نصية ("24.7136").	يحوّل التطبيق بـ Number().
الحقول النصية	سلاسل.	سلاسل، و"" عند الغياب، وليست null أبدًا.
image_urls	مصفوفة أو null.	مصفوفة دائمًا.	للعنوان 162115 رابط صورة واحد على Shukah و[] على Locate (2026-10-02).
position	عدد صحيح.	لا يُرجَع.
عنوان شخص آخر	403 مع body بنمط Laravel أعلاه.	404 Address not found، مثل المعرّف المجهول (قراءة شيفرة؛ ولم يُجرَّب معرّف غريب مباشرة على Locate).	يتغير الـ status والنص الذي يعرضه التطبيق.
body الخاص بـ 404	body بنمط Laravel أعلاه.	{"status":404,"message":"Address not found"} (التُقط على dev، 2026-10-01). وعلى dev يحمل أيضًا حقل stack فيه stack trace للخادم.	يتغير النص الذي يعرضه التطبيق.

POST /maeda/address-book

البديل في Locate: POST /api/v1/clients/address-book

عنوان dev الكامل: https://dev-api.shukah.com/maeda/address-book

الطلب (من التطبيق). JSON فيه lat وlng كسلسلتين، وis_default (0 أو 1)، و area_name وlocation_name وimage_urls (مصفوفة أو null). وقبل الاستدعاء يحذف التطبيق أي عنوان موجود بـ location_name نفسه، لذا فالحفظ الواحد هو delete ثم create هذا.

# Creates an address on dev. Delete it afterwards.
curl -s -X POST "$SHUKAH_BASE_URL/maeda/address-book" -H "Authorization: Bearer $SHUKAH_TOKEN" -H "Content-Type: application/json" -d '{"lat":"24.7136","lng":"46.6753","is_default":0,"area_name":"Olaya","location_name":"Docs test","image_urls":[]}'

استجابة Shukah الملتقطة. 200، 678 ms. العنوان الجديد، مسطّحًا. فقد ملأت Shukah الشارع والمدينة والمنطقة والولاية والرمز البريدي والدولة والعنوان المنسَّق من الإحداثيات.

{
  "id": 162119,
  "location_name": "Docs capture (Shukah)",
  "is_default": 0,
  "formatted_address": "King Fahd Rd, Al Olaya, Riyadh 12211",
  "area_name": "Olaya",
  "street": "King Fahd Rd",
  "city": "Riyadh",
  "area": "Riyadh Province",
  "state": "Riyadh Principality",
  "zipcode": "12251",
  "country": "Saudi Arabia",
  "country_code": "SA",
  "lat": 24.7136,
  "lng": 46.6753,
  "image_urls": [],
  "position": 13
}

التُقط على dev، 2026-10-01 (العميل 356259، request body كما في curl لكن بالاسم Docs capture (Shukah))؛ وحُذف بعد ذلك.

الأخطاء المشاهَدة. لم يُلتقط شيء.

الحقل	Shukah	Locate	ملاحظة
lat وlng (body)	سلاسل من التطبيق.	أرقام أو سلاسل رقمية؛ وأي شيء آخر يُخزَّن null.
is_default (body)	0 أو 1.	1 و"1" وtrue تعني افتراضيًا؛ وأي شيء آخر لا.	في Locate يمسح العنوان الافتراضي أيضًا العلامة عن العناوين الأخرى.
area_name وlocation_name (body)	تُرسل.	تُخزَّن بعد حذف المسافات الزائدة.
image_urls (body)	مصفوفة أو null.	مصفوفة؛ تُحذف المسافات الزائدة من السلاسل وتُسقط الفارغة.
street وcity وarea وstate وzipcode وcountry وcountry_code وformatted_address	تملؤها Shukah من الإحداثيات (التُقطت مجددًا في 2026-10-02). وكيف: غير موثّق بعد.	تُخزَّن فقط إن أُرسلت، وإلا null: فقد عادت القيم الثماني كلها null لـ body التطبيق (التُقط على dev، 2026-10-02).	العنوان المنشأ بـ body التطبيق الحالي لا شارع ولا مدينة له في Locate.
شكل الاستجابة	العنوان نفسه، مسطّحًا، مع id عدد صحيح وposition.	{"status":200,"address":{…}} مع id من 24 حرفًا، وsource: "locate" والتاريخين بصيغة ISO.	يقرأ التطبيق id وlat وlng من المستوى الأعلى، لذا فمع الغلاف تكون مفقودة. اقرأ address.
مكان التخزين	Shukah.	Locate، ثم نسخة بذل أقصى جهد (best-effort) إلى Shukah.	على dev لم تصل النسخة إلى Shukah في 2026-10-01 ولا في 2026-10-02: فالنسخة تُرسل بـ POST إلى /maeda/api/address-book، وتجيب عليه Shukah على dev بـ 404.

PUT /maeda/address-book/:id

البديل في Locate: PUT /api/v1/clients/address-book/:id

عنوان dev الكامل: https://dev-api.shukah.com/maeda/address-book/<id>

الطلب (من التطبيق). المسار id. وJSON فيه أي من street وcity وlocation_name وstate و zipcode وcountry_code وcountry وarea وformatted_address وis_default (0 أو 1) و image_urls. وترسل شاشة تعديل العنوان في التطبيق location_name وarea وis_default و image_urls. ولا يوجد lat ولا lng ولا area_name في update.

# Edits an address on dev. Use one you created.
curl -s -X PUT "$SHUKAH_BASE_URL/maeda/address-book/$ADDRESS_ID" -H "Authorization: Bearer $SHUKAH_TOKEN" -H "Content-Type: application/json" -d '{"location_name":"Docs test (edited)"}'

استجابة Shukah الملتقطة. 200، 245 ms. العنوان كاملًا، مسطّحًا، مع الحقل المتغيّر.

{
  "id": 162119,
  "location_name": "Docs capture (Shukah, edited)",
  "is_default": 0,
  "formatted_address": "King Fahd Rd, Al Olaya, Riyadh 12211",
  "area_name": "Olaya",
  "street": "King Fahd Rd",
  "city": "Riyadh",
  "area": "Riyadh Province",
  "state": "Riyadh Principality",
  "zipcode": "12251",
  "country": "Saudi Arabia",
  "country_code": "SA",
  "lat": 24.7136,
  "lng": 46.6753,
  "image_urls": [],
  "position": 13
}

التُقط على dev، 2026-10-01 (العميل 356259، الـ body هو {"location_name":"Docs capture (Shukah, edited)"})؛ وحُذف بعد ذلك.

الأخطاء المشاهَدة. لم يُلتقط شيء. والمعرّف المفقود يجيب بـ 404 بنمط Laravel المبيّن تحت get.

الحقل	Shukah	Locate	ملاحظة
id (path)	عدد صحيح.	معرّف من 24 حرفًا، أو أرقام لمعرّف Shukah.
مفاتيح الـ body	المفاتيح أعلاه؛ تحديث جزئي.	المفاتيح نفسها، جزئيًا. والمفتاح المرسَل بـ null أو "" أو مسافات يمسح الحقل (وتصبح image_urls []).
is_default	0 أو 1.	فقط عندما يكون المفتاح في الـ body. وضبطها ينقل الافتراضي. وقواعد الافتراضي في Shukah: غير موثّق بعد.
الاستجابة	عنوان مسطّح، وid عدد صحيح، وlat وlng رقمان، وposition.	عنوان مسطّح، وid من 24 حرفًا، وlat وlng سلسلتان، دون position.	المفاتيح التي يقرؤها التطبيق كلها موجودة.
النسخ إلى Shukah	لا ينطبق.	نسخة بذل أقصى جهد. ومع غياب معرّف Shukah تنشئ عنوانًا جديدًا هناك، وقد يكرره.	على dev لم يصل تعديل عنوان أنشأته Locate إلى Shukah في 2026-10-02. وتعديل أُجري على Shukah لم يصل إلى Locate أيضًا.

DELETE /maeda/address-book/:id

البديل في Locate: DELETE /api/v1/clients/address-book/:id

عنوان dev الكامل: https://dev-api.shukah.com/maeda/address-book/<id>

الطلب. المسار id، دون body. ويحوّل التطبيق المعرّف إلى رقم أولًا بعلامة الجمع الأحادية.

# Deletes an address on dev, permanently. Use one you created.
curl -s -X DELETE "$SHUKAH_BASE_URL/maeda/address-book/$ADDRESS_ID" -H "Authorization: Bearer $SHUKAH_TOKEN"

استجابة Shukah الملتقطة. 204 مع body فارغ، 286 ms (التُقط على dev، 2026-10-01). ولا يقرأ التطبيق الـ body.

الأخطاء المشاهَدة. قراءة ثانية للمعرّف المحذوف تجيب بـ 404 بنمط Laravel Object not found: 162119 (التُقط على dev، 2026-10-01).

الحقل	Shukah	Locate	ملاحظة
id (path)	عدد صحيح.	معرّف من 24 حرفًا، أو أرقام لمعرّف Shukah.	تحوّل علامة الجمع الأحادية في التطبيق معرّف 24 حرف hex إلى NaN، فيصبح الاستدعاء .../address-book/NaN ويحصل على 404.
النجاح	204، body فارغ.	200 مع {"status":200}.	لا شيء: فالتطبيق لا يقرأ الـ body.
body الخاص بـ 404	body بنمط Laravel.	{"status":404,"message":"Address not found"}. وحذف ثانٍ يحصل عليه أيضًا.
النسخ إلى Shukah	لا ينطبق.	لا يُنسخ الحذف إلى Shukah أبدًا.	العنوان الذي عُدّل عبر Locate ثم حُذف قد يبقى على Shukah.

PUT /maeda/client/:client_id

البديل في Locate: PUT /api/v1/clients/:client_id

عنوان dev الكامل: https://dev-api.shukah.com/maeda/client/<client_id>

يخدم route Shukah الواحد هذا مدخلين في الـ registry. فتعديل الملف الشخصي ومفتاح إشعارات push كلاهما يستدعي PUT /maeda/client/<client_id>. ولا يُميَّزان إلا بالـ body: فتعديلات الملف الشخصي تحمل مفاتيح الملف الشخصي، ومفتاح push يحمل {client_id, push_enabled}. وتفصل Locate بينهما: فهذا المدخل يقابل PUT /api/v1/clients/:client_id، وتحديث الإعداد يقابل PUT /api/v1/clients/setting. وليس للتطبيق استدعاء منفصل للإعدادات في Shukah.

الطلب (من التطبيق). المسار client_id (الرقم، ويتكرر في الـ body). وJSON فيه client_id إضافةً إلى أي من contact_phone وemail_address وfirst_name وlast_name وsex (0 أو 1 أو 2 أو 9) و birth_date (YYYY-MM-DD، أو null) وreceive_offers (0 أو 1).

# Writes the profile on dev. Send the client's current value back.
curl -s -X PUT "$SHUKAH_BASE_URL/maeda/client/$CLIENT_ID" -H "Authorization: Bearer $SHUKAH_TOKEN" -H "Content-Type: application/json" -d "{\"client_id\":$CLIENT_ID,\"receive_offers\":$CURRENT_RECEIVE_OFFERS}"

استجابة Shukah الملتقطة. 200، 239 ms (التُقط على dev، 2026-10-02، مع الـ body {"client_id":356259,"receive_offers":0}، أي أُعيدت كتابة القيمة الحالية): الملف الشخصي ذو الحقول الـ 13، بالمفاتيح والأنواع والقيم نفسها كما في عينة verify-token. وأجابت Locate بالـ body نفسه. ويحلّله التطبيق بوصفه UserServer.

الأخطاء المشاهَدة. birth_date خاطئ ("not-a-date")، 422 (التُقط على dev، 2026-10-02): [{"field":"birth_date","message":"The birth date field must match the format Y-m-d."}]. وهو مصفوفة أخطاء حقول، لا كائن خطأ Laravel. وأجابت Locate بـ 400 {"status":400,"message":"birth_date is invalid","stack":"…"} على الـ body نفسه. وقواعد التحقق الأخرى في Shukah: غير موثّقة بعد.

الحقل	Shukah	Locate	ملاحظة
client_id (المسار والـ body)	المعرّف الرقمي، في الاثنين. وهل تفحصه Shukah مقابل الـ token: غير موثّق بعد.	يجب أن يساوي عميل الـ token في المسار، وفي الـ body إن أُرسل، وإلا 400 مع client_id does not match the authenticated client.
contact_phone	هل يُقبل هاتف تغيّر: غير موثّق بعد.	يجب أن يساوي الهاتف المخزَّن تمامًا، مع + في البداية، وإلا 400 مع contact_phone cannot be changed. ولا يُكتب أبدًا.	لا تعِد تنسيق الهاتف.
first_name وlast_name	سلاسل.	null أو 100 حرف على الأكثر بعد حذف المسافات الزائدة، وإلا 400.
email_address	سلسلة.	أي سلسلة أو null، دون فحص للصيغة.
birth_date	YYYY-MM-DD أو null.	أي شيء يستطيع new Date() قراءته، ويُخزَّن بتاريخ UTC. وnull تمسحه. و"" أو قيمة سيئة تعطي 400 مع birth_date is invalid.
sex	0 أو 1 أو 2 أو 9.	1 ذكر، 2 أنثى. وأي شيء آخر يُخزَّن «غير معروف» ويُقرأ لاحقًا 0.	القيمة 9 في Shukah تُقرأ «غير معروف» بعد التحوّل.
receive_offers	0 أو 1.	1 و"1" وtrue تعني التفعيل، وأي شيء آخر التعطيل.
push_enabled	يُقبل في هذا الـ route: ويستخدمه مفتاح push.	يُتجاهل. ويجيب الاستدعاء بـ 200 مع الملف الشخصي دون تغيير.	انقل المفتاح إلى تحديث الإعداد، وإلا فلن يفعل شيئًا بصمت.
الاستجابة	الملف الشخصي ذو الحقول الـ 13 (التُقط على dev، 2026-10-02).	الملف الشخصي نفسه ذو الحقول الـ 13 (التُقط على dev، 2026-10-01 و2026-10-02).
الأخطاء	422 مع مصفوفة {field, message} (التُقط لـ birth_date، 2026-10-02).	400 {"status":400,"message":"…"}، أول فحص فاشل فقط. وعلى dev يحمل الـ body أيضًا حقل stack.	يعرض التطبيق message، فيفقد اسم الحقل، ويتغير الـ status من 422 إلى 400.
Authorization	token من Shukah.	JWT من Locate فقط.
النسخ إلى Shukah	لا ينطبق.	لا يُنسخ.	أي شيء ما زال يقرأ الملف الشخصي من Shukah يحتفظ بالقيم القديمة.

PUT /maeda/client/:client_id

البديل في Locate: PUT /api/v1/clients/setting

عنوان dev الكامل: https://dev-api.shukah.com/maeda/client/<client_id>

route Shukah نفسه الخاص بـ تحديث الملف الشخصي. وهو مفتاح push عندما يكون الـ body فقط {client_id, push_enabled}.

الطلب (من التطبيق). JSON {"client_id": <id>, "push_enabled": 0 or 1}.

# Writes the push setting on dev. Send the current value back.
curl -s -X PUT "$SHUKAH_BASE_URL/maeda/client/$CLIENT_ID" -H "Authorization: Bearer $SHUKAH_TOKEN" -H "Content-Type: application/json" -d "{\"client_id\":$CLIENT_ID,\"push_enabled\":$CURRENT_PUSH_ENABLED}"

استجابة Shukah الملتقطة. 200، 252 ms (التُقط على dev، 2026-10-02، مع الـ body {"client_id":356259,"push_enabled":0}، أي أُعيدت كتابة القيمة الحالية): الملف الشخصي ذو الحقول الـ 13 مع push_enabled يساوي 0، كما في عينة verify-token. وأجاب route الإعداد في Locate بالـ body نفسه. ويقرأ التطبيق push_enabled منه. ولأن القيمة المكتوبة هي القيمة الحالية، فالالتقاط لا يثبت أن Shukah تطبّق push_enabled على هذا الـ route.

الأخطاء المشاهَدة. لم يُلتقط شيء: غير موثّق بعد.

الحقل	Shukah	Locate	ملاحظة
الـ Route	PUT /maeda/client/<client_id>، وهو route الملف الشخصي.	PUT /api/v1/clients/setting، دون معرّف في المسار.	وجّه مفتاح push إلى الـ route الجديد.
client_id (body)	يُرسل. وهل تفحصه Shukah: غير موثّق بعد.	مطلوب. يجب أن يساوي عميل الـ token، وإلا 400 مع client_id does not match the authenticated client.	يرسله التطبيق بالفعل.
push_enabled (body)	0 أو 1.	مطلوب. 1 و"1" وtrue تفعّله، وكل شيء آخر يعطّله. والمفتاح المفقود يعطي 400 مع push_enabled is required.
مفاتيح أخرى	تُقبل مفاتيح الملف الشخصي على الـ route نفسه.	لا تُقبل: فقط client_id وpush_enabled.
الاستجابة	الملف الشخصي ذو الحقول الـ 13 (التُقط على dev، 2026-10-02).	الملف الشخصي ذو الحقول الـ 13 مع push_enabled الجديدة (التُقط على dev، 2026-10-01 و2026-10-02).
Authorization	token من Shukah.	JWT من Locate فقط.
النسخ إلى Shukah	لا ينطبق.	لا يُنسخ. وتحتفظ Shukah بالقيمة القديمة.

POST /maeda/client/add-device-id

البديل في Locate: POST /api/v1/clients/add-device-id

عنوان dev الكامل: https://dev-api.shukah.com/maeda/client/add-device-id

الطلب (من التطبيق). JSON {"device_id": "<device unique id>"}. ويرسله التطبيق مرة واحدة لكل تثبيت، وفقط عند تسجيل الدخول، ويسجّل أنه أُرسل بعد 200.

curl -s -X POST "$SHUKAH_BASE_URL/maeda/client/add-device-id" -H "Authorization: Bearer $SHUKAH_TOKEN" -H "Content-Type: application/json" -d '{"device_id":"00000000-0000-4000-8000-000000000000"}'

استجابة Shukah الملتقطة. 200، 236 ms (التُقط على dev، 2026-10-02، مع معرّف الجهاز الوهمي في أمر curl أعلاه). ويتجاهل التطبيق الإجابة.

{
  "id": 1074,
  "client_id": 356259,
  "device_id": "00000000-0000-4000-8000-000000000000"
}

خزّنت Shukah سجل جهاز جديدًا (1074) للمستدعي. ولا يوجد API يزيله، فالسجل الوهمي ما زال على dev.

الأخطاء المشاهَدة. لم يُلتقط شيء.

الحقل	Shukah	Locate	ملاحظة
device_id (body)	معرّف الجهاز. وتخزّن Shukah سجل جهاز جديدًا للمستدعي في كل استدعاء (2026-10-02).	يُعاد كما هو. لا يُتحقق منه ولا يُخزَّن.
id (الاستجابة)	معرّف سجل الجهاز الجديد (1074).	دائمًا 920، لكل مستدعٍ.	قيمة بديلة (stand-in) ثابتة.
client_id (الاستجابة)	معرّف المستدعي (356259).	دائمًا 356315، وليس معرّف المستدعي.	قيمة بديلة (stand-in) ثابتة.
device_id (الاستجابة)	يُعاد كما هو.	يُعاد كما هو؛ ومعرّف نموذجي ثابت عندما لا يحمل الـ body واحدًا.
Authorization	يرسل التطبيق token الخاص به. وهل تشترطه Shukah: غير موثّق بعد.	غير مطلوب، ولا يُفحص.
الأثر	سجل جهاز يُخزَّن للمستدعي (2026-10-02).	لا شيء: لا يُخزَّن شيء.	يعلّم التطبيق الجهاز بأنه أُرسل ولا يعيد المحاولة أبدًا، مع أن شيئًا لم يُخزَّن.

GET /maeda/client/status

لا بديل في Locate بعد — أي شيء يستدعي هذا الـ route يواصل استدعاء Shukah.

عنوان dev الكامل: https://dev-api.shukah.com/maeda/client/status

شكل الطلب. غير موثّق بعد. تعرّف نسخة التطبيق اللحظية بتاريخ 2026-02-26 هذا الـ endpoint، لكن لا شيفرة فيها تستدعيه، فالطلب الذي سيرسله غير معروف.

curl -s "$SHUKAH_BASE_URL/maeda/client/status" -H "Authorization: Bearer $SHUKAH_TOKEN"

استجابة Shukah الملتقطة. 404، 320 ms (التُقط على dev، 2026-10-02): لا يوجد هذا الـ route على Shukah في dev.

{
  "name": "Not Found",
  "message": "The route maeda/client/status could not be found.",
  "code": 0,
  "status": 404,
  "type": "Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException"
}

الأخطاء المشاهَدة. الـ 404 أعلاه.

ما هو معروف:

• يُظهر جدول حركة الإنتاج بتاريخ 2026-10-02 768 استدعاءً لهذا الـ route في 3 أيام، فثمة ما يستدعيه في الإنتاج. وأي عميل يرسلها: غير موثّق بعد. والتطبيق 2.31.5 أحدث من النسخة اللحظية، فاسأل فريق الجوال أي شاشة تستدعيه.
• تجيب Shukah على dev بـ 404: فالـ route مفقود من نسخة Laravel على dev. وهل لا يزال الإنتاج يخدمه: غير موثّق بعد. وإن كان التطبيق 2.31.5 يستدعيه، فهذا الاستدعاء يفشل على dev اليوم.
• لم يُعثر على route في Locate له. ولا شيفرة قُرئت في التدقيق (نسخة التطبيق وخدمة المصادقة وorder-v2 وثلاثة backends أخرى في Locate) تستدعيه؛ وroute status الخاص بـ order-v2 فحص للتعافي من الكوارث (disaster-recovery) ولا علاقة له. وما يفعله هذا الـ route: غير موثّق بعد.

GET /maeda/client/delete

لا بديل في Locate بعد — يواصل التطبيق استدعاء Shukah.

عنوان dev الكامل: https://dev-api.shukah.com/maeda/client/delete

تحذير: هذا الـ route يحذف الحساب، وهو GET. لم يُستدعَ أبدًا أثناء كتابة هذه الصفحة، بأي token. ولا يوجد أمر قابل للتشغيل هنا عن قصد. لا تشغّله على حساب حقيقي، ولا تدع معاينة رابط أو crawler أو health check يصدره.

شكل الطلب. GET، دون query سوى language، ودون body. وAuthorization: Bearer <stored token> هو المُدخل الوحيد. أما السبب الذي يختاره المستخدم في شاشة الحذف فلا يُرسل.

استجابة Shukah الملتقطة. لا شيء: لم يُستدعَ أبدًا. ولا يتوقع التطبيق أي body. وعند النجاح يُسجّل التطبيق خروج المستخدم محليًا. و401 تجعل التطبيق يحذف الـ token المخزَّن.

الأخطاء المشاهَدة. لا شيء.

ما هو معروف:

• لا يوجد route في خدمة المصادقة أو خدمة النقاط أو order-v2 يحذف حسابًا. ويواصل التطبيق استدعاء route Shukah هذا، الذي يحتاج إلى token تقبله Shukah (انظر الـ Tokens).
• ما تفعله Shukah بالسجل (حذف ناعم، أو تغيير حالة) وكيف يصل ذلك إلى Locate: غير موثّق بعد. ولا شيفرة في Locate تضع علامة «محذوف» على عميل.

واجهات النقاط

GET /maeda/client/points

البديل في Locate: GET /api/v2/client/points

عنوان dev الكامل: https://dev-api.shukah.com/maeda/client/points

الطلب. Bearer token وlanguage. ولا معاملات أخرى. ويضيف مستدعٍ ثانٍ في التطبيق (حزمة food-court) x-auth-from: SHUKAH.

curl -s "$SHUKAH_BASE_URL/maeda/client/points" -H "Authorization: Bearer $SHUKAH_TOKEN"

استجابة Shukah الملتقطة. 200، 251 ms.

{
  "id": "356259",
  "user_id": "356259",
  "points": "514853.64",
  "pointsExpirationDate": "2026-11-30"
}

التُقط على dev، 2026-10-02 (العميل 356259). وفي 2026-10-01 أعاد الاستدعاء نفسه "128712.41"، أي أن بيانات Shukah على dev تغيرت بينهما.

الأخطاء المشاهَدة. لا token، 401، body بنمط Laravel (التُقط على dev، 2026-10-01).

الحقل	Shukah	Locate	ملاحظة
id	معرّف العميل كنص.	معرّف العميل كنص.
user_id	نفسه id.	نفسه id.
points	سلسلة بخانتين عشريتين: "514853.64" (2026-10-02).	سلسلة بحتى أربع خانات عشرية: "514405.6788" (العميل نفسه، اليوم نفسه، مع token من Shukah).	يستخدم التطبيق Number(points) || 0. وLocate أقل بـ 447.96 نقطة، أي نحو 0.09%. وأحدث صف في سجل Locate أقدم بيومين من أحدث صف في Shukah، وهذا يلائم الفجوة (استنتاج).
pointsExpirationDate	"2026-11-30".	"2026-11-28".	أبكر بيومين؛ وnull ما لم تنطبق قاعدة الانتهاء.
Authorization	token من Shukah.	token من Shukah فقط على dev اليوم: فـ JWT من Locate يحصل على 401 Invalid or expired token (التُقط على dev، 2026-10-02). وفي 2026-10-01 عمل الاثنان.	يجب أن يحتفظ التطبيق بـ token من Shukah لهذا الـ route. انظر الـ Tokens.
body الخطأ	body بنمط Laravel.	غلاف خدمة النقاط.
headers إصدار التطبيق	هل ترسلها Shukah على هذا URL: غير موثّق بعد.	لا تُرسل. وURL الخاص بـ Locate يحتوي أيضًا client/points، لذا سيبحث التطبيق عنها.	انظر Headers الطلب.

GET /maeda/point-rate

البديل في Locate: GET /api/v2/client/system_configs/point_rates

عنوان dev الكامل: https://dev-api.shukah.com/maeda/point-rate

عام (public) على Shukah: 200 دون token. ولا يستدعي التطبيق route Locate بدلًا منه إلا في وضع Merchant (enableMerchantService: true في إعدادات العميل).

الطلب. لا معاملات سوى language.

curl -s "$SHUKAH_BASE_URL/maeda/point-rate"

استجابة Shukah الملتقطة. 200، 235 ms.

[
  {"amount_from": 0, "amount_to": 139, "point_earn": 2},
  {"amount_from": 140, "amount_to": 153, "point_earn": 12},
  {"amount_from": 154, "amount_to": 250, "point_earn": 16},
  {"amount_from": 251, "amount_to": 450, "point_earn": 20},
  {"amount_from": 451, "amount_to": null, "point_earn": 30}
]

التُقط على dev، 2026-10-01.

الأخطاء المشاهَدة. لا شيء.

الحقل	Shukah	Locate	ملاحظة
amount_from	عدد صحيح، يبدأ عند 0.	يبدأ عند 70.	يضيف التطبيق صفًا قبل الأول، لذا فإجمالي أقل من 70 يعرض 0 نقطة على Locate.
amount_to	عدد صحيح، وnull في الصف الأخير. لا تتداخل النطاقات (139، ثم 140).	عدد صحيح، وnull في الصف الأخير. تشترك النطاقات في قيمة النهاية (فـ 140 تنهي صفًا وتبدأ التالي).	قد يطابق إجمالي 140 أو 251 بالضبط صفين.
point_earn	2 و12 و16 و20 و30.	2 و4 و10 و16.	شرائح مختلفة على dev.
الصفوف	خمسة.	أربعة: 70-140 و140-251 و251-451 و451 فأكثر (التُقط على dev، 2026-10-01).	أي الجدولين صحيح: غير موثّق بعد.
إجابة فارغة	غير موثّق بعد.	[] عندما لا يكون الخيار مضبوطًا.	يقرأ التطبيق الصف الأول دون فحص.
Authorization	لا حاجة إليه.	لا حاجة إليه.
قاعدة الإضافة (credit)	لا ينطبق.	ما زال order-v2 يحسب النقاط التي يكسبها الطلب من جدول Shukah.	قد تختلف البطاقة عن النقاط المضافة فعليًا.

GET /maeda/giftcard-code/use

البديل في Locate: POST /api/v2/client/gift-card-code

عنوان dev الكامل: https://dev-api.shukah.com/maeda/giftcard-code/use?code=<code>

الطلب. Bearer token. وQuery بالمفتاح code. ولا يستدعي التطبيق route Locate بدلًا منه إلا في وضع Merchant (enableMerchantService: true).

تحذير: GET يضيف نقاطًا عندما يكون الكود صالحًا. لم يُستدعَ أبدًا أثناء كتابة هذه الصفحة.

# Credits points if the code is valid. Use a code you may spend.
curl -s -G "$SHUKAH_BASE_URL/maeda/giftcard-code/use" -H "Authorization: Bearer $SHUKAH_TOKEN" --data-urlencode "code=$GIFT_CODE"

استجابة Shukah الملتقطة. لا شيء: فهو يضيف نقاطًا. ويتوقع التطبيق ستة مفاتيح: total_points و date_created وdescription وmessage وpoints_type وtrans_type. وقيم Shukah الحقيقية: غير موثّقة بعد.

الأخطاء المشاهَدة. لم يُلتقط شيء.

الحقل	Shukah	Locate	ملاحظة
الـ method وcode	GET مع ?code=.	POST مع {"code":"<code>"} في الـ body.	غيّر الـ method وURL ومكان الكود.
total_points وdate_created وdescription وmessage وpoints_type وtrans_type (الاستجابة)	المفاتيح الستة التي يحلّلها التطبيق. والقيم الحقيقية: غير موثّقة بعد.	المفاتيح الستة نفسها. وdate_created هي yyyy-mm-dd hh:mm:ss بالتوقيت العربي.	يحلّل التطبيق المفاتيح نفسها في الوضعين.
مخزون الأكواد	أكواد Shukah نفسها.	الأكواد الموجودة في قاعدة بيانات التاجر (merchant) في order-v2. وهل الأكواد الصادرة عن Shukah موجودة هناك: غير موثّق بعد.	قد يُرفض كود يعمل على Shukah.
Authorization	token من Shukah.	فحص الـ token نفسه الذي تستخدمه routes النقاط (عبر /api/v1/users)؛ ولم يُلتقط مع token.
أين تقع الإضافة (credit)	لا ينطبق.	Shukah أو خدمة النقاط، بحسب flag على الخادم (معطّل افتراضيًا: Shukah أولًا). وقيمته على dev: غير موثّق بعد.	مع تعطيل الـ flag، لا يتحرك رصيد Locate إلا بعد المزامنة.
body الخطأ	غير موثّق بعد.	Nest: {"message":"Unauthorized","statusCode":401} لـ token مفقود.

GET /maeda/client/point-history

البديل في Locate: GET /api/v2/client/point-history

عنوان dev الكامل: https://dev-api.shukah.com/maeda/client/point-history

الطلب. Bearer token. دون page أو limit.

curl -s "$SHUKAH_BASE_URL/maeda/client/point-history" -H "Authorization: Bearer $SHUKAH_TOKEN"

استجابة Shukah الملتقطة. 200، 2,254 ms: مصفوفة JSON واحدة من 8,134 صفًا (و8,136 في 2026-10-02). وأول صف كسب:

{
  "shukah_id": 1351762,
  "total_points": 0.5,
  "date_created": "2026-10-01 10:40:44",
  "description": "Points gained by buy item Order ID L07678739",
  "message": "",
  "points_type": "earn",
  "trans_type": "adjustment"
}

التُقط على dev، 2026-10-01 (العميل 356259)، أول 8,134 صفًا (يحتفظ الالتقاط بأول 10، وكلها صفوف كسب). ولم تكن صفوف المصروفات ضمن الصفوف المخزَّنة؛ ومفاتيحها الـ 14 (id وclient_id و merchant_id وorder_id وtotal_points كسلسلة مثل "684.00" وstatus وdate_created و ip_address وtotal_points_amt وtrans_type وpoints_type وremarks وexternal_id و description) مأخوذة من تقرير التطابق (parity report) لخدمة النقاط، locate-point-service: docs/reports/2026-07-17-client-api-parity.md (قيس في 2026-07-17).

الأخطاء المشاهَدة. لا token، 401، body بنمط Laravel (التُقط على dev، 2026-10-01).

الحقل	Shukah	Locate	ملاحظة
ترقيم الصفحات	لا شيء: السجل كله.	page وlimit، الافتراضي 20، والحد الأقصى 100.	لا يرسل التطبيق أيًّا منهما، لذا سيعرض أحدث 20 صفًا.
shukah_id (كسب)	عدد صحيح.	عدد صحيح، أو null للصفوف التي كتبتها Locate.
total_points (كسب)	رقم.	رقم.	لا فجوة في المقياس في 2026-10-02: 2 و2 و2 و2 و10 في أحدث صفوف Shukah (0.5 و0.5 و2.5 في 2026-10-01).
date_created	YYYY-MM-DD HH:mm:ss، بتوقيت الرياض.	نفسه.	أحدث صف 2026-10-01 17:00:01 في Shukah، و2026-09-29 12:45:07 في Locate (2026-10-02): Locate متأخرة.
description	نص، مثل Points gained by buy item Order ID L07678739.	"" في 8 من صفوف الكسب التسعة ضمن أول 10 صفوف، وmanual credit في واحد (2026-10-02).	سيعرض التطبيق سطرًا فارغًا.
message	"".	"".
points_type	earn أو expenses.	نفسه.
trans_type	adjustment في صفوف الكسب الملتقطة.	adjustment في الكسب، وorder في صف المصروفات الملتقط.
id للمصروفات	عدد صحيح.	سلسلة من 24 حرفًا.	نوع السجل في التطبيق لا يحتوي id.
total_points للمصروفات	سلسلة بخانتين عشريتين.	سلسلة بخانتين عشريتين بالضبط ("360.00").
client_id وmerchant_id وorder_id وstatus وip_address وtotal_points_amt وremarks وexternal_id للمصروفات	موجودة في صفوف مصروفات Shukah (تقرير parity لشهر يوليو 2026)؛ ولم تُلتقط القيم.	موجودة: status دائمًا "active"، وip_address دائمًا ""، وexternal_id دائمًا null.
صفوف الانتهاء	صف كسب سالب.	صف مصروفات بمبلغ موجب للانتهاءات منذ 2026-09-16؛ والأقدم صفوف كسب سالبة.
body الخطأ	body بنمط Laravel.	غلاف خدمة النقاط.

GET /maeda/point-offer

البديل في Locate: GET /api/v2/client/point-offers

عنوان dev الكامل: https://dev-api.shukah.com/maeda/point-offer

عام (public) على Shukah: 200 دون token.

الطلب. لا معاملات للقائمة. ويستدعيه التطبيق أيضًا بـ ?id=<id> ثم يلتقط العرض من القائمة المُرجَعة بنفسه.

curl -s "$SHUKAH_BASE_URL/maeda/point-offer"

استجابة Shukah الملتقطة. 200، 235 ms: خمسة عروض.

[
  {"id": 1, "point_amount": 100, "purchased_point_amount": 110, "amount": "40.00"},
  {"id": 2, "point_amount": 200, "purchased_point_amount": 240, "amount": "60.00"},
  {"id": 3, "point_amount": 300, "purchased_point_amount": 360, "amount": "90.00"},
  {"id": 4, "point_amount": 400, "purchased_point_amount": 480, "amount": "120.00"},
  {"id": 5, "point_amount": 500, "purchased_point_amount": 600, "amount": "150.00"}
]

التُقط على dev، 2026-10-01.

الأخطاء المشاهَدة. لا شيء.

الحقل	Shukah	Locate	ملاحظة
id	عدد صحيح، من 1 إلى 5.	سلسلة من 24 حرفًا، مثل 6a46104f3dd7b3dd6a261d90.	لا تخلط النوعين أبدًا: فLocate ترفض العدد الصحيح من Shukah.
point_amount	عدد صحيح.	قيم متساوية في 2026-10-01.
purchased_point_amount	عدد صحيح.	قيم متساوية، لكن قد تكون null عندما لا يكون للعرض سعر بالنقاط.	يعرّفه التطبيق كرقم.
amount	سلسلة بخانتين عشريتين.	قيم متساوية في 2026-10-01.
?id= (query)	يُرجع القائمة كلها.	يُقبل ويُتجاهل: القائمة كلها مجددًا.	الالتقاط من جانب العميل في التطبيق يعمل مع المعرّفات الجديدة.
Authorization	لا حاجة إليه.	مطلوب: 401 دون token (التُقط على dev، 2026-10-01).	أما شاشة تعرض العروض قبل تسجيل الدخول فستفشل.
الترتيب	غير موثّق بعد.	بتسلسل يضبطه المسؤول، ثم معرّف Shukah.
body الخطأ	غير موثّق بعد (عام).	غلاف خدمة النقاط.

GET /maeda/point-occasion

البديل في Locate: GET /api/v2/client/point-occasions

عنوان dev الكامل: https://dev-api.shukah.com/maeda/point-occasion

عام (public) على Shukah: 200 دون token.

الطلب. لا معاملات للقائمة؛ ويستدعيه التطبيق أيضًا بـ ?id=<id> ويرشّح القائمة بنفسه.

curl -s "$SHUKAH_BASE_URL/maeda/point-occasion"

استجابة Shukah الملتقطة. 200، 249 ms: سبع مناسبات.

[
  {"id": 1, "occasion": "Birthday", "occasion_en": "Birthday", "is_custom": 0},
  {"id": 2, "occasion": "Born", "occasion_en": "Born", "is_custom": 0},
  {"id": 3, "occasion": "Gift", "occasion_en": "Gift", "is_custom": 0},
  {"id": 4, "occasion": "Wedding", "occasion_en": "Wedding", "is_custom": 0},
  {"id": 5, "occasion": "Graduation", "occasion_en": "Graduation", "is_custom": 0},
  {"id": 6, "occasion": "Thank", "occasion_en": "Thank", "is_custom": 1},
  {"id": 7, "occasion": "Other", "occasion_en": "Other", "is_custom": 1}
]

التُقط على dev، 2026-10-01.

الأخطاء المشاهَدة. لا شيء.

الحقل	Shukah	Locate	ملاحظة
id	عدد صحيح، من 1 إلى 7.	سلسلة من 24 حرفًا.	لا تخلط النوعين أبدًا.
occasion	النص الإنجليزي.	إنجليزية، أو عربية عندما تكون language هي ar بالضبط.	يرسل التطبيق ar-SA، فلا يحصل على التسمية العربية أبدًا.
occasion_en	النص الإنجليزي.	قيم متساوية في 2026-10-01.	يقرأ نوع التطبيق occasionEn، لذا فاسمه الإنجليزي undefined اليوم على الجانبين.
is_custom	0 أو 1.	قيم متساوية في 2026-10-01.
?id= (query)	يُرجع القائمة كلها.	يُتجاهل: القائمة كلها مجددًا.
Authorization	لا حاجة إليه.	مطلوب: 401 دون token.
body الخطأ	غير موثّق بعد (عام).	غلاف خدمة النقاط.

POST /maeda/point-order

البديل في Locate: POST /api/v2/client/point-orders

عنوان dev الكامل: https://dev-api.shukah.com/maeda/point-order

الطلب (من التطبيق). JSON فيه point_offer_id (سلسلة) وto_client_id (سلسلة) وpayment_type (point، أو لدفع إلكتروني قيمة payment من الإعدادات العامة: payfort أو hyperpay أو checkout)، واختياريًا point_occasion_id وoccasion (نص حر). ولا يوجد مفتاح idempotency: فإعادة محاولة POST تنشئ طلبًا ثانيًا.

تحذير: ينشئ طلبًا. payment_type بالقيمة point يحرّك النقاط فورًا (فيدفع المرسِل هامشًا: 110 مقابل 100). جرّب checkout فقط، الذي يبقى غير مدفوع. واستُدعي كل نوع مرة واحدة على dev في 2026-10-02، بموافقة المستخدم (الطلبان 1256 و1257).

# Creates an unpaid order on dev.
curl -s -X POST "$SHUKAH_BASE_URL/maeda/point-order" -H "Authorization: Bearer $SHUKAH_TOKEN" -H "Content-Type: application/json" -d "{\"point_offer_id\":\"$OFFER_ID\",\"to_client_id\":\"$TO_CLIENT_ID\",\"payment_type\":\"checkout\"}"

استجابة Shukah الملتقطة. 201، 320 ms: طلب checkout إلى معرّف العميل نفسه.

{
  "point_order_id": 1256,
  "payment_point_order_id": "p-1256",
  "client_id": 356259,
  "to_client_id": 356259,
  "point_amount": 100,
  "purchased_point_amount": 110,
  "amount": "40.00",
  "status": "initial_order",
  "payment_type": "checkout",
  "point_occasion_id": null,
  "occasion": "",
  "description": ""
}

التُقط على dev، 2026-10-02 (العميل 356259). ولطلب point (1257، إلى عميل dev آخر) المفاتيح الاثنا عشر نفسها، مع status بالقيمة successful. وقد خفّض رصيد Shukah بمقدار 110 وترك رصيد Locate كما هو.

ويجيب create بمفاتيح صفوف الطلبات نفسها في قائمة الهدايا المرسَلة. ويتوقعها التطبيق أيضًا، عدا أنه يعرّف occasion_id: ترسل Shukah point_occasion_id (رقمًا أو null)، لذا فـ occasionId في التطبيق دائمًا undefined.

الأخطاء المشاهَدة. لم يُلتقط شيء.

الحقل	Shukah	Locate	ملاحظة
point_offer_id (body)	عدد صحيح كنص.	سلسلة من 24 حرفًا من قائمة Locate.	العدد الصحيح من Shukah يعطي 400.
to_client_id (body)	سلسلة المعرّف.	عدد صحيح موجب؛ وتُقبل السلسلة الرقمية.
payment_type (body)	point أو payfort أو hyperpay أو checkout.	point أو checkout فقط.	payfort وhyperpay تعطيان 400. وإذا قالت الإعدادات payfort أو hyperpay، يفشل create.
point_occasion_id (body)	عدد صحيح كنص.	سلسلة من 24 حرفًا، أو لا شيء.
occasion (body)	نص حر.	تُحذف المسافات الزائدة، من 1 إلى 255 حرفًا.
حالة HTTP	201.	200 (التُقط على dev، 2026-10-02).	لا شيء إذا قبل التطبيق أي 2xx.
point_order_id (الاستجابة)	عدد صحيح.	لا يُرجَع. ومعرّف الطلب هو UUID correlation_id.	تأخذه routes الدفع وget في المسار.
client_id وto_client_id وamount وoccasion وpoint_occasion_id وdescription وpayment_point_order_id (الاستجابة)	يقرؤها التطبيق، ويتوقع occasion_id بينما في صفوف طلبات Shukah point_occasion_id.	لا تُرجَع.	يجب إعادة بناء كائن الطلب من المفاتيح الجديدة.
correlation_id وorder_no وpayment_status وmoney_amount وorder_type (الاستجابة)	لا تُرجَع.	جديدة: UUID، ورقم من 100000، وحالة البوابة أو null، وسلسلة بخانتين عشريتين، وgift أو transfer.
status وpoint_amount وpurchased_point_amount وpayment_type (الاستجابة)	كلمات الحالة في التطبيق: initial_order وpayment_failed وsuccessful وpaid.	الكلمات نفسها (وطلب Locate لا يبلغ إلا الثلاث الأولى).
الـ Flag	لا شيء.	point يحتاج POINT_ORDER_POINT_ENABLED؛ والمعطّل يجيب 403. مفعّل على dev (فُحص 2026-10-01)؛ وproduction غير مؤكَّد.
هدية لنفسه	مسموحة.	مسموحة لـ checkout، و400 لـ point.
الرصيد بعد طلب point	لا ينخفض إلا رصيد Shukah (110 للطلب 1257).	لا ينخفض إلا رصيد Locate (110 للطلب 100012).	السجلان (ledgers) غير متزامنين عند الصرف (dev، 2026-10-02، خلال ثواني التشغيل؛ ولم يُفحص هل يصل لاحقًا). اقرأ الرصيد والسجل من الجانب الذي يُنشئ الطلبات.
body الخطأ	غير موثّق بعد.	غلاف خدمة النقاط.

POST /maeda/point-order/get-description

البديل في Locate: POST /api/v2/client/point-orders/description

عنوان dev الكامل: https://dev-api.shukah.com/maeda/point-order/get-description

الطلب (من التطبيق). JSON فيه point_offer_id (سلسلة)، واختياريًا point_occasion_id (سلسلة) وoccasion (نص حر). ويستدعيه التطبيق مرتين لكل طلب. ولا يكتب شيئًا.

curl -s -X POST "$SHUKAH_BASE_URL/maeda/point-order/get-description" -H "Authorization: Bearer $SHUKAH_TOKEN" -H "Content-Type: application/json" -d '{"occasion":"","point_offer_id":"1","point_occasion_id":"1"}'

استجابة Shukah الملتقطة. 200، 857 ms. وصف فارغ.

{
  "description": ""
}

التُقط على dev، 2026-10-01 (العميل 356259)، بالـ body الموجود في curl أعلاه، ومرة أخرى في 2026-10-02 بالإجابة نفسها. وأعاد كل body جُرّب في 2026-10-01 النتيجة نفسها: معرّفات كنص، ومعرّفات كأرقام، ومع نص حر. وتقول وثيقة خدمة النقاط إن Shukah أرجعت الجملة الكاملة في 2026-09-21 (locate-point-service: docs/integrations/2026-07-16-client-facing-point-apis.md، آخر تغيير 2026-09-22). ولماذا هو فارغ الآن: غير موثّق بعد.

الأخطاء المشاهَدة. لم يُلتقط شيء.

الحقل	Shukah	Locate	ملاحظة
point_offer_id (body)	عدد صحيح كنص.	سلسلة من 24 حرفًا.	العدد الصحيح من Shukah يعطي 400.
point_occasion_id (body)	عدد صحيح كنص.	سلسلة من 24 حرفًا، أو لا شيء.
occasion (body)	نص حر.	نص حر؛ وعندما لا يكون فارغًا يغلب معرّف المناسبة.
description (الاستجابة)	"" على dev اليوم. والجملة الكاملة بحسب وثيقة 2026-09-21.	You have received a gift Birthday of 100 points from Test User (*****0000) (التُقط على dev، 2026-10-01).	مع Shukah ستكون خانة الرسالة فارغة اليوم.
الجملة	الصياغة نفسها؛ ومسافة مزدوجة عند غياب المناسبة.	الصياغة نفسها والمسافة المزدوجة نفسها.	لا تحذفها.
Authorization	token من Shukah.	token من Shukah (200 على dev، 2026-10-02). ولم يُجرَّب JWT من Locate هنا؛ والفحص نفسه يعطيه 401 على routes النقاط الأخرى.	انظر الـ Tokens.
body الخطأ	غير موثّق بعد.	غلاف خدمة النقاط.

POST /maeda/order/checkout-payment-standalone

البديل في Locate: POST /api/v2/client/point-orders/:correlation_id/pay/card

عنوان dev الكامل: https://dev-api.shukah.com/maeda/order/checkout-payment-standalone

يدفع route Shukah نفسه أيضًا طلبات المطاعم. ويغطي هذا القسم استخدامه لطلبات النقاط.

تحذير: يخصم من بطاقة محفوظة في بوابة الدفع. لا يوجد أمر قابل للتشغيل هنا، ولم يُستدعَ أبدًا أثناء كتابة هذه الصفحة.

شكل الطلب. JSON {"id": "<saved card id>", "cvv": "<cvv>", "point_order_id": "<order id>"}. وid هو card.tokenName في التطبيق. وpoint_order_id سلسلة: فأجسام الدفع في التطبيق 2.31.5 الملتقطة على dev في 2026-10-02 ترسله بالشكل "1252" و"1253".

استجابة Shukah الملتقطة. لا شيء: فهو ينشئ دفعة. ويتوقع التطبيق id وstatus و reference و3ds (downgraded وenrolled) و_links (self وactions وredirect.href).

الأخطاء المشاهَدة. تجيب Shukah على dev على routes دفع طلبات النقاط بـ 422 (أُبلغ عنه في 2026-10-02، من التطبيق 2.31.5 على dev): {"name":"Unprocessable Content","message":"Checkout payment is not configured properly.","code":0,"status":422,"type":"Symfony\\Component\\HttpKernel\\Exception\\HttpException"}. ولا تستطيع Shukah على dev قبول دفعة نقاط اليوم. وتأتي أخطاء الدفع من خدمة الدفع كـ 4xx خاص بها.

الحقل	Shukah	Locate	ملاحظة
id (body)	معرّف البطاقة المحفوظة.	نفسه.
cvv (body)	رمز الأمان.	سلسلة أو رقم، من 1 إلى 8 محارف. يُمرَّر ولا يُخزَّن.
point_order_id (body)	سلسلة مثل "1252"، في الـ body (التطبيق 2.31.5، 2026-10-02).	يُقبل ويُتجاهل. والطلب هو UUID correlation_id في المسار.	يحتفظ التطبيق بـ pointOrderId فقط؛ وعليه أن يحتفظ بالمعرّف الجديد من create.
payment_type (body)	لا يُرسل في هذا الـ route.	يُقبل ويُتجاهل.
الاستجابة	يتوقع التطبيق 3ds.downgraded و_links.redirect.	body خدمة الدفع دون تغيير؛ وفي عينتها 3ds.is_redirect. وقد تأتي دفعة مرفوضة دون _links.redirect.	افحص بدء 3-D Secure مقابل استجابة حقيقية.
الـ Flag	لا شيء.	POINT_ORDER_CARD_ENABLED؛ والمعطّل يجيب 403 قبل أي قراءة. مفعّل على dev (فُحص 2026-10-01)؛ وproduction غير مؤكَّد.
body الخطأ	الخاص بخدمة الدفع نفسها.	يُمرَّر دون تغيير لأخطاء الدفع؛ وإلا غلاف خدمة النقاط.

POST /maeda/order/checkout-payment-flow

البديل في Locate: POST /api/v2/client/point-orders/:correlation_id/pay/session

عنوان dev الكامل: https://dev-api.shukah.com/maeda/order/checkout-payment-flow

يُستخدم أيضًا لطلبات المطاعم. ويغطي هذا القسم طلبات النقاط.

تحذير: يفتح جلسة دفع في بوابة الدفع. لا يوجد أمر قابل للتشغيل هنا. ولم تستدعِه الوثائق أبدًا؛ واستدعاه التطبيق 2.31.5 على dev في 2026-10-02، وأجابت Shukah على dev بـ 422 (غير مضبوط).

شكل الطلب. JSON {"point_order_id": "<order id>", "payment_type": "<wallet>", "rememberMe": true or false}. أرسل التطبيق 2.31.5 القيمة {"point_order_id":"1253","payment_type":"applePay","rememberMe":false} (التُقط على dev، 2026-10-02). وpoint_order_id سلسلة. وتسمح النسخة اللحظية للتطبيق أيضًا بـ stcpay وcard قيمةً لـ payment_type، لكن التطبيق 2.31.5 يرسل STC Pay إلى route خاص به، checkout-payment-stcpay.

استجابة Shukah الملتقطة. لا شيء. ويتوقع التطبيق id وpayment_session_secret و payment_session_token و_links.self.href.

الأخطاء المشاهَدة. استدعاء التطبيق 2.31.5 أعلاه، 422 (التُقط على dev، 2026-10-02): {"name":"Unprocessable Content","message":"Checkout payment is not configured properly.","code":0,"status":422,"type":"Symfony\\Component\\HttpKernel\\Exception\\HttpException"}.

الحقل	Shukah	Locate	ملاحظة
point_order_id (body)	سلسلة مثل "1253" (التطبيق 2.31.5، 2026-10-02).	يُقبل ويُتجاهل. والطلب هو UUID correlation_id في المسار.
payment_type (body)	applePay في التقاط 2.31.5. وتسمح النسخة اللحظية أيضًا بـ stcpay وcard.	يُقبل ويُتجاهل. وتعرض جلسة Checkout المحافظ (wallets).	لم تعد المحفظة تُختار على الخادم.
rememberMe (body)	Boolean.	true أو false أو "true" أو "false"؛ والافتراضي false. وأي شيء آخر 400.
الاستجابة	يتوقع التطبيق id وpayment_session_secret وpayment_session_token و_links.self.	جلسة خدمة الدفع، دون تغيير، بالمفاتيح نفسها.
الـ Flag	لا شيء.	POINT_ORDER_CARD_ENABLED، كما سبق.
body الخطأ	غير موثّق بعد.	غلاف خدمة النقاط.

GET /maeda/points-faq

البديل في Locate: GET /api/v2/client/points-faq

عنوان dev الكامل: https://dev-api.shukah.com/maeda/points-faq

عام (public) على Shukah: 200 دون token.

الطلب. لا معاملات.

curl -s "$SHUKAH_BASE_URL/maeda/points-faq"

استجابة Shukah الملتقطة. 200، 233 ms: خمسة عناصر. وأولها (النص العربي مختصَر هنا):

{
  "title_ar": "…",
  "text_ar": "…",
  "title_en": "How many points are worth in the Locate App?",
  "text_en": "each point equal to 0.25 SR\r\nthat means, each 4 points equal to one SR"
}

التُقط على dev، 2026-10-01. وكانت المصفوفة ذات العناصر الخمسة مطابقة لما في Locate، بما في ذلك ترتيب المفاتيح.

الأخطاء المشاهَدة. لا شيء.

الحقل	Shukah	Locate	ملاحظة
title_ar وtext_ar وtitle_en وtext_en	سلاسل.	متطابقة في 2026-10-01.	بديل مباشر (drop-in).
Authorization	لا حاجة إليه.	مطلوب: 401 دون token (التُقط على dev، 2026-10-01).	أما شاشة تعرض الأسئلة الشائعة قبل تسجيل الدخول فستفشل.
body الخطأ	غير موثّق بعد (عام).	غلاف خدمة النقاط.
Content-Type	application/json	application/json; charset=utf-8

GET /maeda/point-order

لا بديل في Locate بعد — يواصل التطبيق استدعاء Shukah.

عنوان dev الكامل: https://dev-api.shukah.com/maeda/point-order?page=<n>&per-page=<n>

هذا هو تبويب "Sent gifts": القائمة الوحيدة بالهدايا التي أرسلها المستخدم.

الطلب. Bearer token. وQuery بالمفتاحين page وper-page.

curl -s -G "$SHUKAH_BASE_URL/maeda/point-order" -H "Authorization: Bearer $SHUKAH_TOKEN" --data-urlencode "page=1" --data-urlencode "per-page=20"

استجابة Shukah الملتقطة. 200، 251 ms، مصفوفة مجردة من 20 طلبًا لـ page=1&per-page=20 (التُقط على dev، 2026-10-02). وأولها:

{
  "point_order_id": 1255,
  "payment_point_order_id": "p-1255",
  "client_id": 356259,
  "to_client_id": 356259,
  "point_amount": 200,
  "purchased_point_amount": 240,
  "amount": "60.00",
  "status": "initial_order",
  "payment_type": "checkout",
  "point_occasion_id": 3,
  "occasion": "Gift",
  "description": ""
}

ويتوقع التطبيق مصفوفة طلبات فيها point_order_id وclient_id وto_client_id و point_amount وpurchased_point_amount وamount وstatus وpayment_type وoccasion و occasion_id وdescription وpayment_point_order_id. وترسل Shukah point_occasion_id لا occasion_id، لذا فمعرّف المناسبة في التطبيق undefined. ويقرأ التطبيق أيضًا headers الاستجابة x-pagination-total-count وx-pagination-page-count؛ ولم يحفظ الالتقاط headers الاستجابة.

الأخطاء المشاهَدة. لا شيء.

ما هو معروف:

• لا يوجد route في Locate يسرد طلبات النقاط الخاصة بعميل. وليس لدى خدمة النقاط وorder-v2 سوى create وget بحسب correlation_id وdescription وrouteَي الدفع. ولا خطة تذكر route للسرد.
• تفتح شاشة دفع الهدية هذا التبويب بعد الدفع، لذا لا يظهر فيه طلب أُنشئ عبر Locate.
• لدى Locate route لـ get بحسب correlation_id، لكنه جديد وليس بديلًا لهذه القائمة. ولدى التطبيق أيضًا GET /maeda/point-order/<id> في الشيفرة، لكن لا شاشة تستدعيه.

POST /maeda/order/checkout-payment

لا بديل في Locate بعد — يواصل التطبيق استدعاء Shukah.

عنوان dev الكامل: https://dev-api.shukah.com/maeda/order/checkout-payment

تحذير: ينشئ دفعة في بوابة الدفع. لا يوجد أمر قابل للتشغيل هنا.

شكل الطلب. JSON {"payment_token": "<Checkout.com Frames token>", "point_order_id": <order id>}. ويستخدمه التطبيق لهدايا النقاط عندما يحصل على token للبطاقة من Checkout.com Frames.

استجابة Shukah الملتقطة. لا شيء. ويتوقع التطبيق المفاتيح نفسها كما في route standalone (id و status وreference و3ds و_links).

الأخطاء المشاهَدة. لا شيء.

ما هو معروف: توفّر Locate طريقتين لدفع طلب نقاط، بطاقة محفوظة وجلسة. وليس لـ Frames token نظير. وأي استدعاء من Locate ينبغي للتطبيق استخدامه بدلًا منه: غير موثّق بعد.

POST /maeda/order/checkout-payment-stcpay

لا بديل في Locate بعد — يواصل التطبيق استدعاء Shukah.

عنوان dev الكامل: https://dev-api.shukah.com/maeda/order/checkout-payment-stcpay

تحذير: يبدأ دفعة STC Pay. لا يوجد أمر قابل للتشغيل هنا.

شكل الطلب. JSON {"point_order_id": "<order id>", "environment": "sandbox" or "production"}. أرسل التطبيق 2.31.5 القيمة {"point_order_id":"1252","environment":"sandbox"} (التُقط على dev، 2026-10-02): وpoint_order_id سلسلة.

استجابة Shukah الملتقطة. لا شيء. ويتوقع التطبيق سلسلة (بداية STC Pay).

الأخطاء المشاهَدة. استدعاء التطبيق 2.31.5 أعلاه، 422 (التُقط على dev، 2026-10-02): {"name":"Unprocessable Content","message":"Checkout payment is not configured properly.","code":0,"status":422,"type":"Symfony\\Component\\HttpKernel\\Exception\\HttpException"}.

ما هو معروف: تتعامل Locate مع STC Pay كمحفظة داخل route الدفع بالجلسة (pay-session) ولا تستخدم endpoint منفصلًا لـ STC Pay لطلبات النقاط.

POST /maeda/order/payfort-token

لا بديل في Locate بعد — يواصل التطبيق استدعاء Shukah.

عنوان dev الكامل: https://dev-api.shukah.com/maeda/order/payfort-token

تحذير: يبدأ دفعة PayFort. لا يوجد أمر قابل للتشغيل هنا.

شكل الطلب. JSON فيه point_order_id وdevice_id وdigital_wallet وtype: "GiftOrder" واختياريًا promo_code. ويُستخدم لمسار بطاقة PayFort ومسار Apple Pay لهدية نقاط.

استجابة Shukah الملتقطة. لا شيء. ويتوقع التطبيق استجابة payment-token؛ ومفاتيحها: غير موثّقة بعد.

الأخطاء المشاهَدة. لا شيء.

ما هو معروف: PayFort خارج نطاق طلبات نقاط Locate ("deferred by design"). وما دامت قيمة payment في الإعدادات العامة ليست checkout، يرسل التطبيق مدفوعات بطاقة هدية النقاط وApple Pay وSTC Pay إلى PayFort، ولا تستطيع تلك استخدام Locate. ولدى order-v2 route POST /api/v2/client/payments/sdk-token يمرّر الاستدعاء، عندما يكون type: "GiftOrder"، إلى route Shukah هذا مع headers المستدعي فقط. وهو ليس بديلًا: فهو ما زال يحتاج إلى Shukah وإلى token تقبله Shukah.

POST /maeda/order/payfort-stc-pay-checkout

لا بديل في Locate بعد — يواصل التطبيق استدعاء Shukah.

عنوان dev الكامل: https://dev-api.shukah.com/maeda/order/payfort-stc-pay-checkout

تحذير: يبدأ دفعة STC Pay عبر PayFort. لا يوجد أمر قابل للتشغيل هنا.

شكل الطلب. JSON بالنوع GiftOrder. والمفاتيح الأخرى: غير موثّقة بعد.

استجابة Shukah الملتقطة. لا شيء. ويتوقع التطبيق عنوان URL لدفعة STC Pay؛ ومفاتيحه: غير موثّقة بعد.

الأخطاء المشاهَدة. لا شيء.

ما هو معروف: PayFort خارج نطاق طلبات نقاط Locate ("deferred by design")، لذا يواصل مسار STC Pay هذا استدعاء Shukah.