تنظيم الكتيّبات بالمجلّدات والقوالب

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

تتيح لك نقاط النهاية الثلاث هذه إبقاء كتيّباتك منظَّمة دون الحاجة إلى لوحة التحكم:

• اسرد مجلّداتك، ويُعاد كل واحد منها باسم ومُعرّف GUID للمجلّد.
• أسنِد كتيّبًا إلى مجلّد — تُنشأ المجلّدات عند الطلب، وإرسال مجلّد فارغ يُخرِج الكتيّب من مجلّده.
• احفظ كتيّبًا كقالب قابل لإعادة الاستخدام، أو أزِله من قوالبك.

قبل أن تبدأ

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

اسرد مجلّداتك

يسرد GET /api/list-folders مجلّداتك، كلٌّ منها بالشكل { Folder (name), URL (a folder GUID) }. تُشتقّ المجلّدات من إسنادات الكتيّبات، لذا لا يُسرَد المجلّد الفارغ.

curl -X GET 'https://go.fliplink.me/api/list-folders' \
  -H 'X-Api-Key: YOUR_API_KEY'

الاستجابة:

{
  "Result": "OK",
  "Items": [
    {
      "Folder": "Marketing",
      "URL": "00000000-0000-0000-0000-000000000001"
    },
    {
      "Folder": "Marketing/Q2",
      "URL": "00000000-0000-0000-0000-000000000002"
    }
  ]
}

أسنِد كتيّبًا إلى مجلّد

ينقل PUT /api/assign-to-folder/{flipbookId} الكتيّب إلى مجلّد. تُنشأ المجلّدات عند الطلب — أسنِد إلى اسم مجلّد غير موجود بعد فيُنشأ تلقائيًا (لا يوجد استدعاء منفصل لـ«إنشاء مجلّد»). وقد تحتوي أسماء المجلّدات على / (مثل Marketing/Q2). ويبقى المجلّد موجودًا ما دام فيه كتيّب واحد على الأقل، لذا فإن إخراج آخر كتيّب منه يجعله يختفي من list-folders.

curl -X PUT 'https://go.fliplink.me/api/assign-to-folder/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'Folder=Marketing/Q2'

الاستجابة:

{
  "Result": "OK",
  "Message": "Folder updated successfully"
}

لإخراج الكتيّب من مجلّده، أرسِل Folder فارغًا:

curl -X PUT 'https://go.fliplink.me/api/assign-to-folder/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'Folder='

احفظ كتيّبًا كقالب

يميّز PUT /api/save-as-template/{flipbookId} الكتيّب كقالب قابل لإعادة الاستخدام (Status=true) أو يُزيله من القوالب (Status=false). تظهر القوالب في list-templates ويمكن أن تكون بذرةً لكتيّبات جديدة. قيمة Status الافتراضية true إذا أُغفِلت.

curl -X PUT 'https://go.fliplink.me/api/save-as-template/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'Status=true'

الاستجابة:

{
  "Result": "OK",
  "Message": "Saved as template"
}

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

• مفتاح API مفقود أو غير صالح ← HTTP 401. تُعيد هذه الحالة صفحة HTML عادية لعدم التصريح — دون أي جسم JSON.
• مُعرّف العنصر غير موجود أو غير مملوك لمفتاحك (assign-to-folder، save-as-template) ← HTTP 200 مع Message: "Item not found".
• حقل مجهول أو مكتوب خطأً في الجسم (assign-to-folder، save-as-template) ← HTTP 200 مع Message: "Unknown field(s) '…'. Expected: …".

ملاحظات

• اسم Folder الذي تُسنِده هو القيمة نفسها التي تظهر تحت Folder في list-folders، لذا يمكنك إعادة استخدام اسم مجلّد موجود لإضافة مزيد من الكتيّبات إليه.