صفحة الهبوط صفحة تحويل مركّزة لمنتج واحد. مستقلة عن كتالوج الواجهة — يمكنك امتلاك صفحة هبوط بدون منتج حي (لإطلاقات قادمة)، أو واحدة مرتبطة بمنتج لإعلانات مدفوعة.

تُدار الأقسام (السلايدرات، الزوار الوهميون، العدّاد التنازلي…) من لوحة التحكم في v1؛ الواجهة البرمجية تُجري CRUD على السجل الأم فقط. تحديث v1.1 سيكشف CRUD الأقسام أيضًا.

حدود الخطة

الخطة	صفحات الهبوط (كل الحالات — المسودات محسوبة)
Free	0 (شراء لمرة واحدة: 1000 دج/مدى الحياة لكل منها)
Pro	3
Unlimited / Enterprise	غير محدود

الحد يُفرض من تدفّقي الإنشاء والنسخ في لوحة التحكم فقط، مع احتساب كل صفحة هبوط بما فيها المسودات. أما الواجهة البرمجية فلا تفرض شيئًا: POST /v1/landing-pages متبوعًا بـ /publish يتجاوز الحد بالكامل، وعلى خطة مدفوعة تُعرض الصفحات الزائدة حيّة على واجهة المتجر. أما صفحات الخطة المجانية فتبقى غير مرئية ما لم تكن الصفحة مشتراة (is_purchased).

GET /v1/landing-pages

اسرد صفحات الهبوط. ترقيم بالمؤشّر. مخزَّنة مؤقتًا لمدة 30 ثانية — تحقّق من ترويسة الاستجابة X-Cache: HIT|MISS. أما GET /v1/landing-pages/{id} فغير مُخزَّنة.

المصادقة: أي مفتاح منصة نشِط للمتجر (landing_pages:read غير مطبَّقة في v1؛ المفحوصة هي landing_pages:write فقط على نقاط الكتابة).

معاملات الاستعلام

المعامل	النوع	ملاحظات
`limit`	int 1–200	الافتراضي 50
`cursor`	string	غير شفاف
`status`	`active` \| `draft`	تصفية

القيمة غير المعروفة في status تُتجاهَل فتُرجَع كل الصفحات بدل 400.

الاستجابة 200

{
  "data": {
    "items": [
      {
        "id":            42,
        "title":         "Black T-Shirt — 30% off",
        "slug":          "black-tshirt-30-off",
        "status":        "active",
        "language":      "ar",
        "product_id":    26,
        "views":         1543,
        "is_purchased":  false,
        "created_at":    "2026-03-01 10:00:00",
        "updated_at":    "2026-03-15 14:22:11"
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}

GET /v1/landing-pages/{id}

تفاصيل مع section_count.

{
  "data": {
    "id":               42,
    "title":            "Black T-Shirt — 30% off",
    "slug":             "black-tshirt-30-off",
    "status":           "active",
    "language":         "ar",
    "product_id":       26,
    "views":            1543,
    "is_purchased":     false,
    "meta_title":       "Black T-Shirt — Cotton 200gsm — 30% off | DZBuild",
    "meta_description": "Limited-time offer on our cotton black t-shirt.",
    "section_count":    7,
    "created_at":       "2026-03-01 10:00:00",
    "updated_at":       "2026-03-15 14:22:11"
  }
}

مرجع الحقول

الحقل	ملاحظات
`status`	`active` أو `draft` فقط بصرامة — لا توجد حالة `archived` لصفحات الهبوط.
`language`	`ar` أو `fr` أو `en`.
`product_id`	المنتج المرتبط، أو `null`. الصفحة بلا معرّف منتج لا تستطيع تسعير نموذج طلبها بشكل صحيح.
`views`	للقراءة فقط. تُحتسب في كل مرة تُشاهَد فيها الصفحة العامة؛ ولا تستطيع الواجهة البرمجية كتابتها ولا توجد طريقة لتصفيرها.
`is_purchased`	`true` بمجرد شراء الصفحة نهائيًا (1000 دج/مدى الحياة). على الخطة المجانية هذا ما يجعل الصفحة مرئية على واجهة المتجر.
`section_count`	في نقطة التفاصيل فقط — عدّ حيّ لأقسام الصفحة يُحسب مع كل طلب.
`meta_title` / `meta_description`	وسوم SEO. انظر الملاحظة تحت الإنشاء.

POST /v1/landing-pages — إنشاء

المصادقة: مفتاح منصة بصلاحية landing_pages:write. يتطلب Idempotency-Key.

الجسم

الحقل	النوع	إلزامي	ملاحظات
`title`	string 1–255	✅
`slug`	string		يُشتق تلقائيًا من `title` إن أُغفل. أما الـ slug الذي ترسله هنا فيُخزَّن بدون تطبيع — أرسل قيمة نظيفة
`status`	`active` \| `draft`		الافتراضي `draft`. أي قيمة أخرى تُحوَّل بصمت إلى `draft`
`language`	`ar` \| `fr` \| `en`		الافتراضي `ar`. أي قيمة أخرى تُحوَّل بصمت إلى `ar`
`product_id`	int		يجب أن ينتمي إلى متجرك؛ الصفحة تربط بهذا المنتج
`meta_title`	string ≤ 255		عنوان SEO. إن أغفلته عبر الواجهة البرمجية يُخزَّن ويُرجَع كـ `null` (بخلاف نموذج لوحة التحكم الذي ينسخ `title` إليه). ومع ذلك تعرض الصفحة العامة `title` كبديل، فعنوان الصفحة الظاهر صحيح في الحالتين
`meta_description`	string		وصف SEO

تُجعل الـ slugs فريدة داخل متجرك بإلحاق -2 و-3 وهكذا. وإن كان أساس الـ slug فارغًا فيُستعمل landing- متبوعًا بـ 6 أحرف hex.

الأخطاء

الكود	السبب
`bad_request` "Body must be valid JSON"	Content-Type خاطئ أو JSON تالف
`bad_request` "title is required (1-255 chars)"	العنوان مفقود أو طويل جدًا
`bad_request` "product_id N does not belong to this store"	معرّف من متجر آخر

الطلب

curl -X POST 'https://api.dzbuild.app/v1/landing-pages' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "title":      "Black T-Shirt — 30% off",
    "language":   "ar",
    "product_id": 26,
    "status":     "draft"
  }'

تُرجع 200 (وليس 201) وبنفس شكل GET /v1/landing-pages/{id}. صفحة الهبوط الجديدة بدون أقسام — أضفها من لوحة التحكم.

PATCH /v1/landing-pages/{id}

تحديث جزئي.

يتحقّق PATCH بصرامة أكبر من الإنشاء: status غير صالح يُرجع 400 bad_request ("status must be active or draft")، وlanguage غير صالح يُرجع 400 ("language must be ar, fr, or en") بدل التحويل الصامت. ويجب أن يبقى title بين 1 و255 حرفًا. أما الـ slug المُرسَل في PATCH فيُطبَّع، بخلاف الإنشاء.

curl -X PATCH 'https://api.dzbuild.app/v1/landing-pages/42' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "title": "Black T-Shirt — Spring promo" }'

تغيير العنوان يُعيد توليد slug تلقائيًا فقط إن لم تُرسل slug صراحةً.

POST /v1/landing-pages/{id}/publish

اختصار: تحويل الحالة إلى active. يكافئ PATCH ... { status: "active" }.

curl -X POST 'https://api.dzbuild.app/v1/landing-pages/42/publish' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Idempotency-Key: publish-42-$(date +%s)"

DELETE /v1/landing-pages/{id}

حذف نهائي. وتُحذف أقسام الصفحة معها.

curl -X DELETE 'https://api.dzbuild.app/v1/landing-pages/42' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Idempotency-Key: del-42"

الاستجابة: { "data": { "deleted": true, "id": 42 } }.

المقالات ذات الصلة