الحسابات

POST /auth/otp/request — طلب رمز

{ "identifier": "salma@example.com" }

الرد 202:

{ "message": "Un code vient d’être envoyé à votre adresse e-mail.", "identifier": "salma@example.com",
  "channel": "mail", "expires_at": "2026-09-14T10:05:00+01:00" }

رفض 422 — معرّف غير صالح؛ حساب غير مدعو خلال المرحلة الخاصة؛ حساب معطّل؛ هاتف ما دامت قناة الرسائل القصيرة/واتساب غير مهيأة. رفض 429 — طلبات كثيرة جدًا.

POST /auth/otp/verify — استبدال الرمز برمز وصول

{
  "identifier": "salma@example.com",
  "code": "482913",
  "device": { "key": "a3f1…", "platform": "android", "name": "Pixel de Salma", "app_version": "0.3.0" }
}

device.key معرّف ثابت يولّده التطبيق ويحتفظ به على الجهاز؛ وplatform تأخذ القيمة ios أو android أو web.

الرد 201:

{
  "token": "12|kD9…", "token_type": "Bearer", "expires_at": null,
  "user": { "id": 3, "name": "سلمى التازي", "email": "salma@example.com", "phone": null,
            "role": "learner", "status": "active", "locale": "ar", "verified_at": "…" },
  "device": { "id": 5, "device_key": "a3f1…", "platform": "android", "name": "Pixel de Salma", "app_version": "0.3.0", "last_seen_at": "…" }
}

رفض 422 — رمز خاطئ (تبيّن الرسالة عدد المحاولات المتبقية)، أو منتهي الصلاحية، أو مستعمل من قبل، أو ملغى بطلب جديد. إعادة الدخول من device.key نفسه تستبدل رمز الوصول السابق.

GET /me — الحساب المتصل

مع Authorization: Bearer <jeton>. يعيد user وقائمة devices الخاصة بالحساب. بدون رمز وصول صالح: 401.

GET /me/library — مكتبتي

المنتجات التي يملك الحساب حق وصول نشطًا إليها، مباشرة أو عبر عرض يحتويها: المسار يمنح برامجه الخمسة. كل مدخل هو منتج من القائمة مع via (المنتج الذي ينبع منه الحق) وgranted_at وexpires_at. المقتطفات المجانية لا تظهر هنا: تُسمع دون حق.

مع رمز الوصول، يحمل كل منتج في الكتالوج أيضًا owned: صحيح إن كان في المكتبة. دون رمز، تكون قيمته null.

POST /auth/logout — تسجيل الخروج

يلغي رمز الوصول الخاص بهذا الجهاز. وتبقى الأجهزة الأخرى متصلة.

التسلسل الموصى به من جهة التطبيق

1. شاشة المعرّف ← otp/request. اعرض expires_at وأتح إعادة الطلب بعد انقضاء المهلة.
2. شاشة الرمز ← otp/verify مع وصف الجهاز. خزّن رمز الوصول في المخزن الآمن للمنصة.
3. أرسل Accept-Language: ar ورمز الوصول مع كل استدعاء. عند 401، ارجع إلى شاشة المعرّف.