خطافات الويب للعملاء المحتملين ومزامنة Google Sheets

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

عندما يلتقط كتيّب العملاء المحتملين، يمكنك توجيه كل عميل محتمل جديد خارج FlipLink وإلى أنظمتك الخاصة. وتتيح لك نقاط النهاية الثلاث هذه:

• تحديد Webhook للعميل المحتمل الجديد — رابط يستقبل حمولة JSON لكل عميل محتمل جديد.
• اختبار الـ Webhook — إطلاق حمولة وهمية كي تتحقّق من التسليم والصيغة دون عميل محتمل حقيقي.
• مزامنة العملاء المحتملين إلى Google Sheets — إضافة كل عميل محتمل جديد إلى جدول تحدّده.

قبل أن تبدأ

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

حدّد Webhook للعميل المحتمل الجديد

يحدّد رابط Webhook يستقبل كل عميل محتمل جديد (يُحفَظ بوصفه Webhook العميل المحتمل الجديد). استخدم نقطة الاختبار أدناه للتحقّق من أنه يُطلَق.

curl -X PUT 'https://go.fliplink.me/api/set-lead-webhook/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'WebhookURL_NewLead=https://example.com/hooks/new-lead'

الاستجابة:

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

اختبر الـ Webhook

يُطلِق حمولة اختبار (TEST) إلى Webhook العملاء المحتملين المضبوط للكتيّب كي تتحقّق من صيغة التسليم دون عميل محتمل حقيقي. ويُعيد ERROR "No lead webhook is configured for this flipbook." إن لم يُضبَط أي منها. وتطابق بنية الحمولة عميلًا محتملًا حقيقيًا (المفاتيح: pdf_id وpdf_name وlead_name وlead_email وlead_phone وlead_company وlead_date وlead_custom_1 وlead_custom_2) لكنها تحمل قيمًا وهمية (pdf_id:"-1"، وpdf_name:"Test PDF"، …). ولا يُخزَّن أي عميل محتمل حقيقي ولا يُرسَل أي بريد إشعار.

curl -X POST 'https://go.fliplink.me/api/test-webhook/96216' \
  -H 'X-Api-Key: YOUR_API_KEY'

الاستجابة:

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

زامِن العملاء المحتملين إلى Google Sheets

يربط التقاط العملاء المحتملين بجدول Google Sheets — إذ تُضاف العملاء المحتملون الجدد إلى الجدول الذي تحدّده. يرسل الطلب ثلاثة حقول نموذج:

• GoogleSheetURL — رابط مشاركة جدول البيانات (الرابط الذي تحصل عليه من مربّع «مشاركة» في Google Sheets).
• GoogleSheetIDKey — مُعرّف جدول البيانات (المُعرّف الطويل في رابط الجدول، بين /d/ و/edit).
• GoogleSheetName — اسم ورقة العمل (التبويب) المراد إضافة الصفوف إليها، مثل Sheet1.

curl -X PUT 'https://go.fliplink.me/api/set-lead-google-sheets/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'GoogleSheetURL=https://docs.google.com/spreadsheets/d/1A2B3C4D5E6F7G8H9I0J/edit?usp=sharing' \
  --data-urlencode 'GoogleSheetIDKey=1A2B3C4D5E6F7G8H9I0J' \
  --data-urlencode 'GoogleSheetName=Sheet1'

الاستجابة:

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

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

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

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

ملاحظات

• تُعيد نقطة الاختبار ERROR "No lead webhook is configured for this flipbook." عندما لا يكون للكتيّب أي Webhook مضبوط — فاضبطه بـ set-lead-webhook أولًا.
• حمولة الاختبار لا تُخزِّن أبدًا عميلًا محتملًا حقيقيًا ولا تُرسِل أبدًا بريد إشعار.