إدارة قائمة السماح بالبريد الإلكتروني للكتيّب

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

عندما يكون الكتيّب مُقيَّدًا بالبريد الإلكتروني، لا يستطيع فتحه إلا العناوين المدرجة في قائمة السماح الخاصة به. ويمنحك الـ API أربع طرق لإدارة تلك القائمة دون الحاجة إطلاقًا إلى لوحة التحكم:

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

يشرح هذا الدليل كلًّا منها، والشكل الدقيق للطلب، والاستجابات التي تستلمها، والمزلق الوحيد الذي يوقِع الناس فيه (الفرق بين الإضافة والاستبدال).

قبل أن تبدأ

ستحتاج إلى:

• مفتاح API — يُرسَل في ترويسة X-Api-Key مع كل طلب. (مفتاحك موجود في صفحة الـ API لحسابك.)
• الـ flipbookId لكتيّب مُقيَّد بالبريد الإلكتروني. تحكم قائمة السماح وصول المشاهدين في الكتيّبات المُقيَّدة بالبريد الإلكتروني.
• تذهب جميع الطلبات إلى الرابط الأساسي https://go.fliplink.me.

الحقل EmailsAllowed في طلبات الكتابة يكون بصيغة form-urlencoded (لا JSON) ومفصولًا بفواصل منقوطة (alice@corp.com;bob@corp.com). وتُقبل الفواصل وتُحوَّل تلقائيًا إلى فواصل منقوطة.

نقاط النهاية الأربع في لمحة

اقرأ القائمة الحالية

ابدأ من هنا دائمًا — اقرأ القائمة لتعرف حالتها الدقيقة قبل تغيير أي شيء.

curl -X GET 'https://go.fliplink.me/api/get-email-allow-list/96464' \
  -H 'X-Api-Key: YOUR_API_KEY'

الاستجابة:

{ "Result": "OK", "EmailsAllowed": ["alice@corp.com", "bob@corp.com"], "Count": 2 }

يُعاد EmailsAllowed بوصفه مصفوفة JSON نظيفة (لا سلسلة بفواصل منقوطة)، وCount هو طولها.

أضِف عناوين (دون مسح البقية)

لمنح الوصول لأشخاص جدد مع إبقاء كل من هو مدرَج فعلًا في القائمة، استخدم الإضافة. هذه العملية إضافية — ولن تحذف أحدًا.

curl -X POST 'https://go.fliplink.me/api/add-email-allow-list/96464' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'EmailsAllowed=carol@corp.com;dan@corp.com'

الاستجابة (القائمة الكاملة بعد التحديث):

{ "Result": "OK", "EmailsAllowed": ["alice@corp.com", "bob@corp.com", "carol@corp.com", "dan@corp.com"], "Count": 4 }

احذف عناوين محدّدة

لسحب الوصول من أشخاص مسمّين، استخدم الحذف. تُزال فقط العناوين التي تدرجها؛ ويبقى الجميع الآخرون.

curl -X DELETE 'https://go.fliplink.me/api/delete-email-allow-list/96464' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'EmailsAllowed=carol@corp.com'

الاستجابة:

{ "Result": "OK", "EmailsAllowed": ["alice@corp.com", "bob@corp.com", "dan@corp.com"], "Count": 3 }

استبدل القائمة بأكملها ⚠️

يستبدل Set قائمة السماح بأكملها بالضبط بالعناوين التي ترسلها. وهنا المزلق: إرسال عنوان واحد يمسح كل من سواه.

# This does NOT add one person — it makes the list ONLY this one person.
curl -X PUT 'https://go.fliplink.me/api/set-email-allow-list/96464' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'EmailsAllowed=alice@corp.com'

بعد هذا الاستدعاء، يصبح alice@corp.com العنوان الوحيد الذي يستطيع عرض الكتيّب. استخدم Set فقط عندما تريد فعلًا تعريف القائمة الكاملة من الصفر (مثل تهيئة كتيّب جديد تمامًا). أما لتغييرات «امنح هذا الشخص / اسحب من ذلك» اليومية، فاستخدم الإضافة والحذف بدلًا من ذلك.

لمسح القائمة بالكامل، أرسِل قيمة فارغة:

curl -X PUT 'https://go.fliplink.me/api/set-email-allow-list/96464' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'EmailsAllowed='

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

• مفتاح API مفقود أو غير صالح ← HTTP 401. تُعيد هذه الحالة صفحة HTML عادية لعدم التصريح — دون أي جسم JSON. تحقّق من وجود ترويسة X-Api-Key وصحّتها.
• flipbookId مجهول (أو غير مملوك لمفتاحك) ← HTTP 200 مع { "Result": "ERROR", "Message": "Item not found" }.

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

النمط المُوصى به

لتغييرات آمنة يمكن التنبّؤ بها:

1. GET القائمة الحالية.
2. قرّر من تضيف أو تحذف.
3. استخدم الإضافة / الحذف للتغييرات الدقيقة (فهما لا يمسّان أبدًا بقيّة القائمة).
4. احتفظ بـ Set لحين رغبتك الفعلية في استبدال القائمة كاملةً دفعةً واحدة.
5. GET مجدّدًا لتأكيد الحالة النهائية.

تعني حلقة «اقرأ ← غيّر ← أعِد القراءة» هذه أنك لن تضطر أبدًا إلى تتبّع القائمة في نظامك الخاص، ولن تمسح الوصول عرضًا باستخدام Set حين كنت تقصد الإضافة.