واجهة فانيو البرمجية

واجهة برمجية (API) عامة للقراءة تعطي برنامجك حزم فانيو ومشاهدها وتراخيصها بصيغة JSON، وتتيح التحقق من مفتاح الترخيص وتنزيل المشاهد المدفوعة. وصفها الكامل بمعيار OpenAPI 3.1 على العنوان https://fanio.net/v1/openapi.json

قبل أن تبدأ

• القراءة لا تحتاج إلى مفتاح.
• لكل عنوان شبكة حد لعدد الطلبات. إذا تجاوزته جاء الرد برمز الحالة 429 والرمز rate_limited.
• لكل مشهد معرف ثابت بالشكل fanio:<pack>/<scene>، حيث pack اسم الحزمة في الرابط وscene اسم المشهد.
• الردود بصيغة JSON، والخطأ يأتي بالشكل {"error": {"code": "...", "detail": "..."}}.
• روابط الصفحات في الردود تشير إلى الصفحات الإنجليزية تحت /en/، والصفحة العربية هي المسار نفسه تحت /ar/.

القراءة

• GET /v1/packs: كل الحزم مع مشاهدها وأسعارها
• GET /v1/packs/{pack}: حزمة واحدة
• GET /v1/scenes/{pack}/{scene}: مشهد واحد، مع عنوانه ونصه البديل ووسومه بالعربية والإنجليزية، وعبارة ذكر المصدر، وترخيصه، وروابطه
• GET /v1/scenes/{pack}/{scene}.svg: ملف SVG للمشهد المجاني. المشهد المدفوع يرد بالرمز 402 وlicence_required مع رابط الشراء
• GET /v1/scenes/{pack}/{scene}.png: معاينة PNG بقياس 480 بكسل لأي مشهد، مجانيا كان أو مدفوعا
• GET /v1/scenes/{pack}/{scene}/provenance: سجل المنشأ، أي كيف صنع المشهد
• GET /v1/search?q=قراءة: البحث بكلمات عربية أو إنجليزية. يدعم limit من 1 إلى 50 وoffset للصفحات. يمكن تكرار pack أو character أو style أو activity أو setting أو season لاختيار عدة قيم من التصنيف نفسه. وتدعم التصفية free=true أو free=false، والترتيب sort=title مع lang=ar. يتضمن الرد العدد الكلي total وأعداد التصنيفات facets. يطلب smart=true ترتيب Jev الاختياري للصفحة الأولى عند تفعيله على الخادم، مع الرجوع إلى الترتيب المحلي عند التعذر
• GET /v1/licences: كل مستويات الترخيص
• GET /v1/licences/{tier}: مستوى ترخيص واحد، والقيمة tier إحدى ثلاث: free أو standard أو extended
• GET /v1/health: حالة الخدمة
• GET /v1/openapi.json: وصف OpenAPI الكامل

المسار غير الموجود يرد بالرمز 404 وnot_found، والمدخل غير الصالح يرد بالرمز 400 وinvalid_input.

المشاهد المدفوعة

تنزيل مشهد مدفوع يحتاج إلى مفتاح الترخيص الذي حصل عليه المشتري. الطلبان الآتيان يرسلان جسما بصيغة JSON مع الترويسة content-type: application/json، وحجم الجسم حتى 4096 بايت.

1. POST /v1/licences/verify بالجسم {"key": "fanio_lk_..."} يرد بالحزمة المرخصة ومستوى الترخيص: {"valid": true, "pack": "...", "tier": "..."}. المفتاح غير الصحيح يرد بالرمز 404.
2. POST /v1/licences/download بالجسم {"key": "...", "scene": "fanio:<pack>/<scene>"} يرد برابط تنزيل url صالح خمس دقائق، وتظهر المدة في الحقل expiresIn بالثواني. المشهد من حزمة لا يشملها المفتاح يرد بالرمز 403 وnot_entitled.

حفظ مفتاح الترخيص

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