إعداد نطاق مخصّص (CNAME)

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

يتيح النطاق المخصّص (CNAME) تقديم كتيّب من اسم مضيف تملكه، مثل docs.example.com. وبعد أن يُضاف نطاق ويُتحقّق منه في لوحة التحكم على الويب، تتيح لك نقاط النهاية الثلاث هذه إدارة الربط بين ذلك النطاق وكتيّباتك من الـ API:

• أضِف ربط CNAME إلى كتيّب.
• اسرد كل سجلّ CNAME في حسابك، مع الكتيّبات المربوطة بكل واحد.
• احذف ربط CNAME من كتيّب واحد أو منها جميعًا دفعةً واحدة.

قبل أن تبدأ

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

أضِف CNAME إلى كتيّب

يربط نطاقًا مخصّصًا مُفعَّلًا فعلًا بكتيّب. مرّر اسم المضيف الكامل بوصفه CNAME. والحقل IsCloudflare اختياري وقيمته الافتراضية 0؛ مرّر 1 إذا كان الـ DNS لديك خلف وكيل Cloudflare.

curl -X POST 'https://go.fliplink.me/api/add-cname/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'CNAME=docs.example.com' \
  --data-urlencode 'IsCloudflare=0'

الاستجابة:

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

إذا لم يكن النطاق قد فُعِّل أولًا في حسابك، يُرفَض الطلب مع: Please add CNAME <domain> to your account using the web dashboard. Only activated CNAMEs are allowed to be created via API.

اسرد سجلّات CNAME لديك

يُعيد كل سجلّات CNAME المخصّصة للمستدعي. ويُبلِّغ كل عنصر عن اسم المضيف، وعدد الكتيّبات النشطة المربوطة به (Documents)، وقائمة مُعرّفات تلك الكتيّبات النشطة (FlipbookIDs).

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

الاستجابة:

{
  "Result": "OK",
  "Items": [
    {
      "CNAME": "ttr.antifragile.ae",
      "Documents": 1,
      "FlipbookIDs": [
        93270
      ]
    }
  ]
}

احذف ربط CNAME

يُزيل ربط نطاق مخصّص من كتيّب واحد أو منها جميعًا. وهناك وضعان:

• الجماعي (الافتراضي): مرّر CNAME=<host> واترك FlipbookID فارغًا — يُزيل ذلك الـ CNAME من كل كتيّب تملكه.
• لكل كتيّب: مرّر FlipbookID=<id> (أكبر من 0) — يُجلَب الـ CNAME من ذلك الكتيّب ويُزال من ذلك الواحد فقط.

مرّر الـ CNAME بوصفه معطى استعلام (لا مقطع مسار) لتجنّب مشكلات النقاط في اسم المضيف.

curl -X DELETE 'https://go.fliplink.me/api/delete-cname?CNAME=docs.example.com&FlipbookID=' \
  -H 'X-Api-Key: YOUR_API_KEY'

يعمل الأمر أعلاه في وضع الجماعي (FlipbookID متروك فارغًا)، لذا تكون استجابته:

{
  "Result": "OK",
  "Message": "CNAME removed successfully"
}

وفي وضع لكل كتيّب (FlipbookID أكبر من 0)، تكون الرسالة بدلًا من ذلك { "Result": "OK", "Message": "CNAME removed from flipbook successfully" }. وإذا لم تمرّر لا CNAME ولا FlipbookID، تكون الاستجابة { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

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

• مفتاح API مفقود أو غير صالح ← HTTP 401. تُعيد هذه الحالة صفحة HTML عادية لعدم التصريح — دون أي جسم JSON. تحقّق من وجود ترويسة X-Api-Key وصحّتها.
• flipbookId مجهول (أو غير مملوك لمفتاحك)، في إضافة CNAME ← HTTP 200 مع { "Result": "ERROR", "Message": "Item not found" }.
• حقل مجهول أو مكتوب خطأً في الجسم، في إضافة CNAME ← HTTP 200 مع { "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }.
• الحذف دون CNAME ولا FlipbookID ← { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

ملاحظات

• إضافة CNAME عبر الـ API تحفظ الربط فقط — فهي لا تتحقّق من الـ DNS ولا تُصدِر الشهادات. أضِف النطاق وتحقّق منه في لوحة التحكم على الويب أولًا.
• يجب أن يكون سجلّ CNAME ضمن حدّ سجلّات CNAME في باقتك.