البيانات الوصفية، والرابط المخصّص، والنشر

ما الذي يمكنك فعله

تتحكّم نقاط النهاية الأربع هذه في كيفية تقديم الكتيّب لنفسه — عنوانه وبياناته الوصفية لمحركات البحث، وحالة نشره، ورابط مشاركته، وشكل تجربة القراءة. تستهدف كلٌّ منها كتيّبًا واحدًا عبر {flipbookId} الخاص به:

• حدّد العنوان والبيانات الوصفية لمحركات البحث — Title وDescription وTitleColor وراية IsPublished.
• انشر أو ألغِ النشر دون المساس بالعنوان أو الوصف.
• امنحه لاحقة مخصّصة (أنيقة) لرابط المشاركة.
• اضبط مظهر صفحة العارض — عمق الصفحة ونوع الغلاف.

قبل أن تبدأ

• مفتاح API — يُرسَل مع كل طلب إمّا في ترويسة X-Api-Key أو ضمن Authorization: Bearer YOUR_API_KEY.
• الـ {flipbookId} — المُعرّف الرقمي للكتيّب، الذي يُعيده create-by-file / create-by-url (بوصفه ID) أو تُعيده list. وتستخدمه نقاط النهاية الأربع أدناه بوصفه معطى مسار.
• تذهب جميع الطلبات إلى الرابط الأساسي https://go.fliplink.me.
• كل جسم طلب هنا يكون بصيغة form-urlencoded (لا JSON) — أرسِل كل حقل بـ --data-urlencode.

حدّد العنوان والبيانات الوصفية لمحركات البحث

يحدّد PUT /api/set-meta/{flipbookId} عنوان الكتيّب وبياناته الوصفية لمحركات البحث — Title وDescription وTitleColor وراية IsPublished. وهذا يستبدل Title/Description/TitleColor. ولتغيير حالة النشر فقط، استخدم set-published (أدناه) بدلًا من ذلك. يأخذ TitleColor لون hex مع # البادئة (مثل #1a1a1a؛ والافتراضي #000000) ويُخزَّن كما هو.

curl -X PUT 'https://go.fliplink.me/api/set-meta/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'Title=Spring 2026 Catalog' \
  --data-urlencode 'Description=Our latest product lineup and pricing' \
  --data-urlencode 'IsPublished=true'

الاستجابة:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

انشر أو ألغِ النشر

يقلب PUT /api/set-published/{flipbookId} راية النشر فقط، تاركًا Title/Description/TitleColor سليمةً (بخلاف set-meta). استخدمه لنشر كتيّب (أو إعادة نشره) — مثل كتيّب عاد غير منشور من create-by-file. والحقل IsPublished مطلوب: true/1 = انشر، وfalse/0 = ألغِ النشر.

curl -X PUT 'https://go.fliplink.me/api/set-published/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'IsPublished=true'

الاستجابة:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

حدّد رابطًا مخصّصًا

يحدّد PUT /api/set-custom-url/{flipbookId} اللاحقة المخصّصة (الأنيقة) لرابط مشاركة الكتيّب عبر الحقل CustomURL. ويجب أن تكون اللاحقة فريدة — فاللاحقة قيد الاستخدام تُعيد Result: "ERROR" (انظر الأخطاء أدناه).

curl -X PUT 'https://go.fliplink.me/api/set-custom-url/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'CustomURL=spring-catalog'

الاستجابة:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

حدّد مظهر الصفحة

يضبط PUT /api/set-page-appearance/{flipbookId} مظهر صفحة العارض. تكشف نقطة النهاية هذه حاليًا حقلين قابلين للتحديد فقط: PageDepth (يقبل flat أو thin أو thick) وCoverType (يقبل soft أو hard). تُخزَّن القيم حرفيًا؛ وقد تُبلِّغ العناصر الأقدم عن قيم أخرى (مثل regular، أو الرقم 1) عند قراءتها مجدّدًا عبر جلب واحد.

curl -X PUT 'https://go.fliplink.me/api/set-page-appearance/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'PageDepth=thin' \
  --data-urlencode 'CoverType=soft'

الاستجابة:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

الأخطاء المحتملة

تنطبق هذه الأخطاء عبر نقاط النهاية الأربع (ويضيف الرابط المخصّص خطأً من عنده):

• مفتاح API مفقود أو غير صالح ← HTTP 401. تُعيد هذه الحالة صفحة HTML عادية لعدم التصريح — دون أي جسم JSON. تحقّق من وجود ترويسة X-Api-Key (أو Authorization: Bearer) وصحّتها.
• مُعرّف العنصر غير موجود أو غير مملوك لمفتاحك ← HTTP 200 مع { "Result": "ERROR", "Message": "Item not found" }.
• الرابط المخصّص مأخوذ فعلًا (set-custom-url فقط) ← HTTP 200 مع { "Result": "ERROR", "Message": "This custom URL is already in use. Please choose another." }.
• حقل مجهول أو مكتوب خطأً في الجسم ← HTTP 200 مع Message: "Unknown field(s) '…'. Expected: …".

قاعدة سريعة: Result: "OK" تعني أن التغيير طُبِّق؛ وResult: "ERROR" تعني أنه لم يُطبَّق — فاقرأ Message لمعرفة السبب.

ملاحظات

• set-meta مقابل set-published: يستبدل set-meta قيم Title/Description/TitleColor، لذا إن كنت تريد تغيير حالة النشر فقط، فاستخدم set-published — فهو يترك تلك الحقول سليمة.