إنشاء كتيّب (من ملف PDF أو من رابط)

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

هناك طريقتان لإنشاء كتيّب من ملف PDF، بحسب مكان وجود الملف:

• ارفع الملف مباشرةً — أرسل الـ PDF بصيغة multipart/form-data.
• أشِر إلى رابط — أعطِ رابط PDF ودع الخادم ينزّله نيابةً عنك.

في كلتا الحالتين يُخزَّن الملف، وتُولَّد صورة مصغّرة، ويُسجَّل السجلّ، ثم تستلم مُعرّف العنصر الجديد ID، ورابط عرضه URL، وحصة باقتك بعد التحديث. استخدم الـ ID المُعاد في الطلبات اللاحقة (set-meta، وset-cta-primary، وsave-as-template، وما إلى ذلك).

قبل أن تبدأ

• مفتاح API — يُرسَل في ترويسة X-Api-Key، أو ضمن Authorization: Bearer YOUR_API_KEY، مع كل طلب.
• تذهب جميع الطلبات إلى الرابط الأساسي https://go.fliplink.me.
• يُحدَّد ما إذا كنت تنشئ كتيّبًا (Flipbook) أم مستندًا (Document) عبر الحقل الاختياري DocType: أغفله أو أرسل DocType=Flipbook لإنشاء كتيّب (وهو الافتراضي)، أو DocType=Document لإنشاء مستند — فـ FlipLink يدعم الاثنين.
• تعكس حقول الحصة المُعادة (Flipbooks_Count / Flipbooks_Max / Flipbooks_Left) حصة باقتك بعد الإنشاء.

لا تستخدم أيٌّ من نقطتَي النهاية معطى مسار — فأنت تنشئ عبر إرسال POST إلى نقطة النهاية نفسها وتستلم الـ ID الجديد. يستخدم الإنشاء من ملف صيغة multipart/form-data. أما الإنشاء من رابط فيستخدم form-urlencoded (لا JSON).

الإنشاء من ملف PDF مرفوع

ينشئ POST /api/create-by-file كتيّبًا من ملف PDF مرفوع يُرسَل بصيغة multipart/form-data. يُخزَّن الملف، وتُولَّد صورة مصغّرة، ويُسجَّل السجلّ. الحقل الوحيد المطلوب هو File؛ أما Name وTitle وDocType فاختيارية. الحد الأقصى لحجم الملف يتبع الباقة (انظر MaxFileSizeMB من who-am-i).

curl -X POST 'https://go.fliplink.me/api/create-by-file' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -F 'File=@/path/to/file' \
  -F 'Name=My Document' \
  -F 'Title=My Title' \
  -F 'DocType=Flipbook'

الحقل DocType قيمته Flipbook (الافتراضي) أو Document — أرسل DocType=Document لإنشاء مستند بدلًا من كتيّب.

الاستجابة:

{
  "Result": "OK",
  "ID": "90001",
  "URL": "https://go.fliplink.me/view/<slug>",
  "Flipbooks_Count": 12,
  "Flipbooks_Max": 200,
  "Flipbooks_Left": 188
}

الإنشاء من رابط PDF

ينشئ POST /api/create-by-url كتيّبًا من رابط PDF. يتولّى الخادم تنزيل FileURL، ورفعه إلى S3، وتوليد صورة مصغّرة، وتسجيل السجلّ. يكون جسم الطلب بصيغة form-urlencoded. الحقل الوحيد المطلوب هو FileURL؛ أما Name وTitle وDocType فاختيارية.

curl -X POST 'https://go.fliplink.me/api/create-by-url' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'FileURL=https://example.com/document.pdf' \
  --data-urlencode 'Name=My Document' \
  --data-urlencode 'Title=My Title' \
  --data-urlencode 'DocType=Flipbook'

يجب أن يستجيب الرابط المصدر خلال 60 ثانية — فالمصادر البطيئة أو غير المتاحة تفشل مع الرسالة Source URL timed out after 60s. وللمصادر غير الموثوقة، يُفضَّل استخدام /api/create-by-file.

الاستجابة:

{
  "Result": "OK",
  "ID": "90001",
  "URL": "https://go.fliplink.me/view/<slug>",
  "Flipbooks_Count": 12,
  "Flipbooks_Max": 200,
  "Flipbooks_Left": 188
}

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

الإنشاء من ملف:

• مفتاح API مفقود أو غير صالح ← HTTP 401. تُعيد هذه الحالة صفحة HTML عادية لعدم التصريح — دون أي جسم JSON.
• الملف المرفوع ليس PDF قابلًا للقراءة ← HTTP 200، والرسالة File is not a valid PDF.
• تجاوز الرفع الحد الأقصى لحجم الملف في الباقة ← HTTP 413، والرسالة File exceeds the maximum allowed upload size.

الإنشاء من رابط:

• مفتاح API مفقود أو غير صالح ← HTTP 401. تُعيد هذه الحالة صفحة HTML عادية لعدم التصريح — دون أي جسم JSON.
• مضيف FileURL خاص أو غير مسموح به ← HTTP 200، والرسالة FileURL host is not allowed.
• حقل مجهول أو مكتوب خطأً في الجسم ← HTTP 200، والرسالة Unknown field(s) '…'. Expected: …

ملاحظات

• تعكس قيم Flipbooks_Count / Flipbooks_Max / Flipbooks_Left حصة باقتك بعد هذا الإنشاء.
• احتفظ بالـ ID المُعاد — فهو ما تمرّره إلى الطلبات اللاحقة (set-meta، وset-cta-primary، وsave-as-template، وغيرها).