مصادقة العميل
المسار الأساسي: /v1/auth على الواجهة العامة.
يتصادق المتسوقون بـ رمز OTP عبر الهاتف. يصدر الخادم JWT عميل (typ: "customer").
- احفظ
accessTokenوrefreshTokenفي SecureStore. - أرسل
Authorization: Bearer <accessToken>مع الطلبات المصادقة. - عند 401 استدعِ
POST /v1/auth/refreshمع{ "refreshToken" }، خزّن الزوج الجديد، وأعد المحاولة مرة واحدة.
صلاحية JWT الوصول 15 دقيقة (expiresIn). تحديث العميل 30 يوماً.
النقاط
| الطريقة | المسار | المصادقة | الغرض |
|---|---|---|---|
POST | /v1/auth/send-otp | عامة | إرسال (أو تسجيل) رمز لمرة واحدة |
POST | /v1/auth/verify-otp | عامة | التحقق من الرمز؛ إصدار زوج JWT |
POST | /v1/auth/refresh | عامة | تدوير الوصول والتحديث |
POST | /v1/auth/logout | عامة | إلغاء رمز التحديث |
إرسال OTP
الجسم
| الحقل | النوع | ملاحظات |
|---|---|---|
phone | نص | 4–24 حرفاً |
مثال
http
POST /v1/auth/send-otp
Content-Type: application/json
Accept-Language: ar
{ "phone": "50000000" }النتائج (داخل الغلاف)
| الحقل | ملاحظات |
|---|---|
message | إقرار مترجم |
code | يظهر في غير الإنتاج ليتحقق التطبيق بلا SMS |
إرسال SMS تجريبي: يسجّل الخادم الرمز. لا تعتمد على مزوّد رسائل حقيقي بعد.
التحقق من OTP
الجسم
| الحقل | النوع |
|---|---|
phone | نص |
code | نص، 4–8 أحرف |
http
POST /v1/auth/verify-otp
Content-Type: application/json
{ "phone": "50000000", "code": "1234" }عند النجاح:
| الحقل | ملاحظات |
|---|---|
customer | كائن العميل العام |
accessToken | JWT — أرسله Bearer |
refreshToken | معتم — احفظه بأمان |
tokenType | "Bearer" |
expiresIn | مدة الوصول بالثواني (900) |
تُدمج سلة الضيف (X-Cart-Token) ومحادثات المساعد (X-Assistant-Guest) في الحساب. بعد الدخول يمكن حذف ترويسات الضيف.
التحديث
http
POST /v1/auth/refresh
Content-Type: application/json
{ "refreshToken": "<opaque>" }يُلغى رمز التحديث السابق. احفظ accessToken وrefreshToken الجديدين.
الخروج
http
POST /v1/auth/logout
Authorization: Bearer <accessToken>يلغي رموز تحديث هذا العميل. احذف الزوج من SecureStore. إن انتهت صلاحية رمز الوصول حدّث أولاً أو أسقط الرموز المحلية وتابع كضيف.
بعد الدخول
استدعِ GET /v1/account/me بـ Bearer. راجع الحساب.