تشغيل وسيط

GET /contents/{id}/stream

معامل اختياري usage: stream (الافتراضي) أو download.

الرد 200:

{
  "content_id": 3, "product_id": 1, "type": "audio", "duration_s": 420,
  "url": "https://…/media/private/audio/programme-motivation-de-soi/3.m4a?expires=…&signature=…",
  "expires_at": "2026-09-14T12:00:00+01:00",
  "usage": "stream"
}

الرمز	الحالة
200	مقتطف مجاني (بحساب أو بدونه)؛ أو مقطع مقفل مع حق نشط
401	مقطع مقفل، أو تنزيل، بدون رمز وصول
403	حساب معطّل، أو لا حق نشط على المنتج
404	مقطع أو منتج غير منشور
409	المقطع ليس له ملف مرتبط بعد

قواعد يجب احترامها من جهة التطبيق

• لا تخزّن url أبدًا بشكل دائم. الرابط تنتهي صلاحيته؛ احتفظ بمعرّف المقطع وأعد الطلب.
• جدّد عند 403 أو انتهاء الصلاحية واستأنف من الموضع المحفوظ. هذه هي شبكة الأمان المقررة: التقدم في المسار الصوتي، أو الاستئناف بعد توقف، أو تغيير الشبكة، كلها تعيد إطلاق طلب إلى التخزين، والصلاحية محسوبة بحيث لا يحدث ذلك أثناء الاستماع.
• الحق ينزل في الشجرة. الحساب الذي يملك المسار يحصل على رابط لكل مقطع من مقاطع برامجه.
• التنزيل: usage=download يعطي رابطًا أطول (ست ساعات افتراضيًا) ويتطلب دائمًا حسابًا وحقًا.

PUT /me/progress/{id} — حفظ موضعي

{ "position_s": 210, "completed": false }

تُرسل دوريًا أثناء الاستماع وعند الإيقاف المؤقت والخروج. يعيد الرد position_s وpercent وcompleted وupdated_at. الكتابة الأخيرة هي التي تُعتمد أيًّا كان الجهاز: هذا ما يتيح الاستئناف على جهاز آخر. يُستنتج completed إن غاب، ابتداءً من 95 % من المدة؛ والموضع الذي يتجاوز المدة يُعاد إليها. المقطع المقفل يتطلب حق وصول (وإلا 403)؛ أما المقتطف المجاني فيكفيه حساب.

يسرد GET /me/progress كل مواضعي؛ ويحمل كل مقطع في بطاقة المنتج progress (أو null) عند إرسال رمز الوصول — وهو ما يقرأه التطبيق لعرض «استئناف».

ما سيأتي

تحديد عدد الأجهزة والحماية من المشاركة يأتيان مع الدفعة L8.