دفع الكتيّبات إلى Google Sheets

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

تتيح لك نقطتا نهاية نقل بيانات الكتيّبات إلى جدول Google Sheets عبر جسر Sheets الخاص بك:

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

وبينهما يمكنك إضافة صفوف العملاء المحتملين (أو أي بيانات جدولية) وتأكيد مشاركة الجدول بشكل صحيح أولًا، كي تلتقط مشكلة مشاركة قبل الدفع، بدلًا من أن يُرفَض الدفع بـ 403.

قبل أن تبدأ

• مفتاح API — يُرسِله مثال المواصفات في ترويسة X-Api-Key. كما يحمل جسم الطلب حقل apiKey (مفتاح ثابت يطابق إعداد الخادم)، وهو مطلوب في نقطتَي النهاية كلتيهما.
• الرابط الأساسي هو جسر Sheets الخاص بك، {sheetsBaseUrl} — الرابط الأساسي الخارجي لجسر Google Sheets لديك (مثل رابط تطبيق ويب Apps Script). وهو رابط كامل وليس نسبيًا إلى go.fliplink.me.
• جسم الطلب هو JSON (خام)، لا form-urlencoded.
• لا تستخدم أيٌّ من نقطتَي النهاية معطى المسار {flipbookId} — إذ يُحدَّد الجدول الهدف بحقل sheetId في الجسم.

ادفع صفوفًا إلى جدول

يضيف POST {sheetsBaseUrl}/api/push-to-sheets صفوفًا إلى جدول Google Sheets ويُنشئ تبويب الجدول المسمّى تلقائيًا إن كان مفقودًا. قد يكون data مصفوفة من الكائنات (تصبح مفاتيح الكائن الأول ترتيب الأعمدة، ويُكتَب صفّ ترويسة عند عدم إعطاء range صريح) أو مصفوفة من المصفوفات (تُمرَّر كما هي). يأخذ الحقل الاختياري range تدوين A1، مثل "Leads!A1"؛ وإن أُغفِل، تُضاف الصفوف بعد آخر صفّ مملوء في الجدول المسمّى.

curl -X POST '{sheetsBaseUrl}/api/push-to-sheets' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "sheetId": "YOUR_SHEET_ID",
    "sheetName": "Leads",
    "data": [
      { "Name": "Alice", "Email": "alice@corp.com" },
      { "Name": "Bob", "Email": "bob@corp.com" }
    ],
    "range": "Leads!A1"
  }'

الاستجابة:

{ "Result": "OK", "Message": "Data pushed to Google Sheet.", "RowsAppended": 2 }

الحقل sheetId هو مُعرّف جدول البيانات — القيمة المكوَّنة من 44 حرفًا الواقعة بين /spreadsheets/d/ و/edit في رابط الجدول. أما sheetName فهو التبويب الهدف، ويُنشأ إن كان غائبًا.

تحقّق ممّا إذا كان جدول قابلًا للكتابة

يختبر POST {sheetsBaseUrl}/api/check-sheet-writable ما إذا كان حساب الخدمة قادرًا على الكتابة في جدول. فهو يُنشئ تبويبًا مؤقتًا، ويكتب فيه خليةً واحدة، ثم يحذف التبويب — ويُعيد IsWritable: true فقط إذا نجحت الخطوات الثلاث جميعها، فيلتقط بذلك كلًّا من «غير مُشارك معنا» و«مُشارك لكن الخلايا محمية».

curl -X POST '{sheetsBaseUrl}/api/check-sheet-writable' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "sheetId": "YOUR_SHEET_ID"
  }'

الاستجابة عندما يكون الجدول مُشاركًا بشكل صحيح:

{ "Result": "OK", "IsWritable": true }

الاستجابة عندما لا يكون الجدول مُشاركًا، أو تكون الكتابة محجوبة، أو يقع خطأ نقل:

{ "Result": "OK", "IsWritable": false }

الاستجابة عند فشل التحقّق من صحّة الطلب:

{ "Result": "ERROR", "Message": "...", "IsWritable": false }

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

في الدفع إلى Sheets:

• الجدول غير مُشارك مع حساب الخدمة ← { "Result": "ERROR", "Message": "Sheet is not editable. Confirm the sheet is shared with the service account as Editor.", "GoogleErrorCode": 403 }
• مفتاح خاطئ ← { "Result": "ERROR", "Message": "Invalid API key." }
• جسم فارغ / لا شيء لإرساله ← { "Result": "ERROR", "Message": "There is no data to send to google sheet." }

في التحقّق من قابلية الجدول للكتابة:

• فشل التحقّق من صحّة الطلب ← { "Result": "ERROR", "Message": "...", "IsWritable": false }. أما الكتابة المحجوبة أو الفاشلة فيُبلَّغ عنها بـ { "Result": "OK", "IsWritable": false } بدلًا من خطأ.

ملاحظات

• استخدم التحقّق من قابلية الجدول للكتابة بوصفه فحصًا مسبقًا قبل الدفع إلى Sheets — فهو أصرم من مجرّد اختبار مشاركة لأنه يجري دورة كتابة-ثم-حذف فعلية، فيلتقط الجداول المُشاركة لكنها ذات خلايا محمية.
• في الدفع إلى Sheets، حين يكون data مصفوفة من الكائنات ولم يُعطَ range، يُكتَب صفّ ترويسة من مفاتيح الكائن الأول؛ وحين يكون data مصفوفة من المصفوفات، يُمرَّر كما هو.