بيع كتيّب وقراءة المبيعات

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

تغطّي نقاط النهاية الخمس هذه دورة حياة بيع كتيّب كاملةً وتتبّع ما يجنيه:

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

قبل أن تبدأ

• مفتاح API — يُرسَل في ترويسة X-Api-Key، أو ضمن Authorization: Bearer YOUR_API_KEY، مع كل طلب.
• تذهب جميع الطلبات إلى الرابط الأساسي https://go.fliplink.me.
• تأخذ كل نقطة نهاية عدا سرد المبيعات المُعرّف الرقمي للكتيّب بوصفه معطى المسار {flipbookId} — مثل .../set-sale-settings/96216.
• ترسل نقاط الكتابة (Set Sale Settings، وSet Sale Page Text، وSet Sale Gateway، وSet Flipbook Purchase) جسمها بوصفه حقول form-urlencoded (لا JSON).

اضبط البيع

يضبط PUT /api/set-sale-settings/{flipbookId} بيع الكتيّب (السعر، والعملة، والخيارات). وتفعيل وضع البيع يُفعّل تلقائيًا التحقّق من البريد الإلكتروني ويجعل بريد العميل المحتمل إلزاميًا.

الحقول الأساسية:

• SaleAmount — السعر بـوحدات العملة الكاملة (مثل الدولارات)، مع السماح بالكسور العشرية. 9.99 تعني $9.99 و1000 تعني $1,000 — وهذه ليست قيمة بالسنتات/الوحدات الصغرى.
• SaleCurr — رمز العملة (الافتراضي usd). انتقِ رمزًا صالحًا من /api/list-currencies.

curl -X PUT 'https://go.fliplink.me/api/set-sale-settings/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'IsForSale=true' \
  --data-urlencode 'SaleCurr=usd' \
  --data-urlencode 'SaleAmount=9.99'

الاستجابة:

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

خصّص صفحة الدفع

يحدّد PUT /api/set-sale-page-text/{flipbookId} النص التسويقي المعروض على صفحة بيع / دفع الكتيّب.

curl -X PUT 'https://go.fliplink.me/api/set-sale-page-text/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'SalePageTitle=' \
  --data-urlencode 'SaleAccessPageTitle=' \
  --data-urlencode 'SalePurchaseButtonText=' \
  --data-urlencode 'SaleButtonText=' \
  --data-urlencode 'SaleAccessButtonText=' \
  --data-urlencode 'SaleButtonColor='

الاستجابة:

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

اختر بوّابة دفع

ينتقي PUT /api/set-sale-gateway/{flipbookId} بوّابة الدفع المُستخدَمة عند بيع هذا الكتيّب ويضبطها.

curl -X PUT 'https://go.fliplink.me/api/set-sale-gateway/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'SaleGatewayName=' \
  --data-urlencode 'SaleGatewayKey=' \
  --data-urlencode 'SaleGatewaySecret='

الاستجابة:

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

سجّل عملية شراء

يسجّل POST /api/set-flipbook-purchase/{flipbookId} عملية بيع (شراء) مكتملة لكتيّب — استخدمه لتدوين عمليات الشراء التي تمّت عبر مسار الدفع الخاص بك، دون المرور عبر دفع Stripe في FlipLink. أرسِل Email المشتري ومرجع بوّابة الدفع PaymentRef (في Stripe، مُعرّف PaymentIntent، pi_...)؛ وكلاهما مطلوب. لا ترسل Amount/Currency — فتلك تُشتقّ على جانب الخادم من مرجع الدفع الخاص بك.

curl -X POST 'https://go.fliplink.me/api/set-flipbook-purchase/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'Email=customer@example.com' \
  --data-urlencode 'PaymentRef=pi_3O1234567890abcdef'

الاستجابة:

{
  "Result": "OK",
  "Message": "Purchase recorded successfully"
}

اقرأ مبيعاتك

يسرد GET /api/list-sales سجلّات البيع/الشراء لكتيّباتك (بريد المشتري، والكتيّب، والمبلغ، والتاريخ) إضافةً إلى تعريفات أعمدة جدول المبيعات. ويدعم التصفّح والتصدير إلى CSV عبر IsDownload. واضبط IsAbandoned=true لإعادة مبيعات السلة المتروكة بدلًا من المبيعات المكتملة.

curl -X GET 'https://go.fliplink.me/api/list-sales?ItemIDs=&SearchText=&PageNo=1&Offset=0&IsDownload=true&IsAbandoned=false' \
  -H 'X-Api-Key: YOUR_API_KEY'

الاستجابة:

{
  "Result": "OK",
  "Items": [],
  "Columns": [
    {
      "ID": 1,
      "data": "ID",
      "title": "ID",
      "type": "numeric",
      "hidden": true,
      "readOnly": true,
      "defaultValue": "",
      "source": "",
      "width": 0,
      "backgroundColor": "",
      "align": "left"
    }
  ],
  "TotalRecordCount": 0
}

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

• مفتاح API مفقود أو غير صالح ← HTTP 401. تُعيد هذه الحالة صفحة HTML عادية لعدم التصريح — دون أي جسم JSON. تحقّق من وجود ترويسة X-Api-Key وصحّتها.
• flipbookId مجهول (أو غير مملوك لمفتاحك) ← HTTP 200 مع { "Result": "ERROR", "Message": "Item not found" }. وينطبق ذلك على Set Sale Settings، وSet Sale Page Text، وSet Sale Gateway، وSet Flipbook Purchase.
• حقل مجهول أو مكتوب خطأً في الجسم ← HTTP 200 مع { "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }.
• حقل شراء مطلوب مفقود (Set Flipbook Purchase) ← { "Result": "ERROR", "Message": "Email is required." } أو { "Result": "ERROR", "Message": "PaymentRef is required." }.

ملاحظات

• تفعيل وضع البيع (IsForSale) عبر Set Sale Settings يُفعّل تلقائيًا التحقّق من البريد الإلكتروني ويجعل بريد العميل المحتمل إلزاميًا.
• Set Flipbook Purchase مخصّص لعمليات الشراء التي تمّت عبر مسار الدفع الخاص بك — فهو يتيح لك تدوين بيع دون المرور عبر دفع Stripe في FlipLink.