خطوة بخطوة: تحديث صفحة عبر الـ API

في هذا المثال تحدّث صفحة موجودة بالكامل عبر الـ API: تضيف رابطًا، وتنقله إلى الأعلى، وتغيّر نمط الأزرار، وتتحقق من المسودة، ثم تنشرها. وتعمل الأوامر في أي صدفة (shell) فيها curl وjq.

#1. إنشاء مفتاح API

1. افتح «Callback وواجهة API» في لوحة التحكم
2. انقر «+ إنشاء مفتاح جديد»
3. اختر «كتابة» لكل من «الصفحات» و«الروابط» (وهذا يشمل صلاحية القراءة)
4. انقر «إنشاء المفتاح» وانسخ سر المفتاح
5. انسخ معرّف المفتاح من القائمة

احفظ القيمتين كمتغيرات بيئة، لا في السكربت:

export LH_KEY_ID="6F668EA6598B0692"
export LH_KEY_SECRET="lt_…"
export API="https://dock.at-harbor.com"

#2. الحصول على رمز وصول

LH_TOKEN=$(curl -sS -X POST "$API/v1/token" \
  -H "Content-Type: application/json" \
  -d "{\"key_id\":\"$LH_KEY_ID\",\"key_secret\":\"$LH_KEY_SECRET\"}" \
  | jq -r .token)

الرمز صالح لمدة 15 دقيقة. وإذا استغرق السكربت وقتًا أطول، فاحصل على رمز جديد في أثناء التشغيل.

#3. العثور على الصفحة

curl -sS "$API/v1/pages" -H "Authorization: Bearer $LH_TOKEN" \
  | jq '.items[] | {id, handle, title, status, current_version}'

دوّن id الصفحة. وفي هذا المثال قيمته 42:

PAGE_ID=42

#4. إضافة رابط

LINK_ID=$(curl -sS -X POST "$API/v1/pages/$PAGE_ID/links" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Autumn sale","target_url_template":"https://shop.example.com/autumn","enabled":true}' \
  | jq -r .id)
echo "New link: $LINK_ID"

تستجيب الـ API بـ HTTP 201 والمعرّف الجديد. وتُضاف الروابط الجديدة إلى نهاية القائمة. وإذا بلغت حد الروابط في خطتك، تحصل على 409 link_limit_reached.

#5. نقل الرابط إلى الأعلى

curl -sS -X POST "$API/v1/pages/$PAGE_ID/links/reorder" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"order\":[$LINK_ID]}"

يكفي إرسال المعرّفات التي يجب أن تنتقل إلى الأمام. وتحتفظ كل الروابط الأخرى بترتيبها خلفها.

#6. تغيير التصميم في المسودة

يُستبدل theme_config بالكامل عند PATCH. لذا تقرأ المسودة أولًا، وتغيّر القيمة التي تريدها فقط، ثم ترسل الكائن كاملًا:

THEME=$(curl -sS "$API/v1/pages/$PAGE_ID/draft" -H "Authorization: Bearer $LH_TOKEN" \
  | jq -c '(.theme_config // {}) | .button_style = "pill"')

curl -sS -X PATCH "$API/v1/pages/$PAGE_ID/draft" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"theme_config\":$THEME}"

يقبل button_style القيم rounded وpill وsquare. ومن حقول theme_config الأخرى bg_color وtext_color وbutton_color وbutton_text_color وbackground.

#7. التحقق من المسودة

curl -sS "$API/v1/pages/$PAGE_ID/draft/validate" -H "Authorization: Bearer $LH_TOKEN"
# → {"ok":true,"valid":true,"issues":[]}

إذا كانت قيمة valid هي false، تسرد issues المشكلات. أصلحها قبل النشر. وما إذا كانت المسودة تختلف أصلًا عن الإصدار المنشور يبيّنه GET /v1/pages/$PAGE_ID في الحقل has_unpublished_changes؛ فإذا كانت قيمته false، يمكنك تخطي النشر.

#8. النشر

curl -sS -X POST "$API/v1/pages/$PAGE_ID/publish" -H "Authorization: Bearer $LH_TOKEN"
# → {"ok":true,"version":8,"checksum":"…"}

يرى الزوّار الآن الإصدار الجديد، بما في ذلك الرابط الجديد والترتيب والتصميم. وإذا كان لديك Webhook للحدث page.published، فإنه يتلقى الآن عملية تسليم. وإذا تعذّر نشر المسودة، تستجيب الـ API بـ 409 draft_not_publishable مع القائمة في details.issues.

#9. التراجع

إذا لم تعجبك النتيجة، فأعد الإصدار السابق إلى المسودة وانشر مجددًا:

curl -sS -X POST "$API/v1/pages/$PAGE_ID/versions/7/restore" -H "Authorization: Bearer $LH_TOKEN"
curl -sS -X POST "$API/v1/pages/$PAGE_ID/publish" -H "Authorization: Bearer $LH_TOKEN"

بدلًا من رقم إصدار يمكنك تمرير current: فهذا يتجاهل كل تغييرات المسودة منذ آخر نشر. وتعيد الاستعادة التصميم والقالب وCSS المخصص وSEO والكتل والروابط؛ أما العنوان والمعرّف والظهور فلا تخضع للإصدارات.

#الأخطاء الشائعة

400 bad_request

الترويسة Content-Type: application/json مفقودة. ودونها يرسل curl -d نوعًا مختلفًا.

401 invalid_token

انتهت صلاحية الرمز بعد 15 دقيقة. احصل على رمز جديد.

403 insufficient_scope

ينقص المفتاح نطاق، مثل «كتابة» للروابط.

أُعيد ضبط التصميم فجأة

أُرسل theme_config بحقل واحد فقط فاستبدل المظهر كله. أرسل المظهر الكامل مجددًا، أو استخدم restore بالقيمة current لتجاهل كل تغييرات المسودة منذ آخر نشر.

كل الرموز مشروحة في تنسيق أخطاء الـ API ورموز الأخطاء، وكل نقاط النهاية مذكورة في نقاط نهاية الـ API حسب المجال.