صفحات المتجر

صفحات المتجر هي صفحات النص التي يكتبها التاجر، مثل من نحن أو التوصيل أو الإرجاع. كل صفحة مكتوبة بلغة Markdown. الصفحة المنشورة تظهر على الرابط /pages/{slug} في المتجر، وتُدرج في sitemap.xml وllms.txt الخاصين بالمتجر. والمسودة تُرجع 404 في المتجر. هذه النقاط الخمس تعرض الصفحات وتقرأها وتنشئها وتعدّلها وتحذفها.

يعدّل التاجر الصفحات نفسها من لوحة التحكم، في صفحة التخصيص، سطر الصفحات. انظر صفحات المتجر في دليل التاجر.

قبل أن تبدأ

• تحتاج القراءة إلى store:read وتحتاج الكتابات إلى store:write. مفاتيح التاجر تحمل الاثنتين.
• تحتاج POST وPATCH وDELETE إلى Idempotency-Key. انظر Idempotency.
• الواجهة البرمجية لا تستطيع رفع الصور. الصورة في body_md رابط إلى صورة موجودة على الإنترنت، تُكتب هكذا: ![text](https://...).

كائن الصفحة

الحقل	النوع	ملاحظات
id	int	رقم الصفحة.
slug	string	آخر جزء من عنوان الصفحة، بعد /pages/. من 2 إلى 80 حرفاً من الحروف اللاتينية الصغيرة والأرقام والشرطات، يبدأ وينتهي بحرف أو رقم. فريد في المتجر.
title	string	من 1 إلى 120 حرفاً.
body_md	string	النص بلغة Markdown، حتى 65,536 بايت. انظر كيف يُعرض النص.
seo_title	string أو null	العنوان الذي تعرضه محركات البحث، حتى 70 حرفاً. null يستعمل title.
seo_description	string أو null	الوصف الذي تعرضه محركات البحث، حتى 160 حرفاً. null يستعمل أول سطور النص.
status	string	draft أو published.
translations	object أو null	نصوص اللغة الثانية للمتجر، مفتاحها رمز اللغة، مثل {"fr": {"title": "...", "body_md": "...", "seo_title": null, "seo_description": null}}، أو null. انظر اللغة الثانية.
url	string	العنوان الكامل للصفحة في المتجر.
created_at	string	YYYY-MM-DD HH:MM:SS، بتوقيت الخادم.
updated_at	string	YYYY-MM-DD HH:MM:SS، بتوقيت الخادم.

تُحذف وسوم HTML من title وseo_title وseo_description، ويُقصّ النص الذي يتجاوز الحد.

كيف يُعرض النص

• يُعرض Markdown في الوضع الآمن: تُهرَّب شيفرة HTML الخام وتظهر نصاً.
• السطر الجديد الواحد في النص يبقى سطراً جديداً.
• الرابط إلى المتجر نفسه، مثل /products أو /category/12 أو /pages/delivery، يُفتح في النافذة نفسها. والرابط إلى موقع آخر يُفتح في نافذة جديدة، وكذلك الرابط الذي يبدأ بـ//.
• رابط يوتيوب وحده في سطره يعرض الفيديو.

اللغة الثانية

لا يُكتب translations إلا ما دامت إضافة المتجر متعدد اللغات مفعّلة في المتجر. بدونها يُتجاهل الحقل وتبقى القيمة المحفوظة كما هي. المفتاح هو اللغة الثانية للمتجر: fr لمتجر عربي، وar لمتجر فرنسي. الزبون الذي يتصفح المتجر بتلك اللغة يرى تلك النصوص، والحقل الفارغ يُعوَّض بالحقل الأساسي.

GET /v1/store/pages

كل صفحات المتجر، والمسودات معها، مرتبة حسب العنوان. العناصر ملخصات بدون النص: اقرأ صفحة واحدة لتحصل على body_md. القائمة ليست مقسمة إلى صفحات: للمتجر 25 صفحة على الأكثر.

المصادقة: مفتاح منصة بصلاحية store:read.

الطلب

curl 'https://api.dzbuild.app/v1/store/pages' \
  -H "Authorization: Bearer $DZ_KEY"

الاستجابة 200

يحمل كل عنصر id وslug وtitle وstatus وurl وupdated_at. cap هو عدد الصفحات الذي تسمح به خطة المتجر. وmax_pages هو الحد الأقصى لكل الخطط.

{
  "data": {
    "items": [
      {
        "id": 7,
        "slug": "retours",
        "title": "Retours",
        "status": "published",
        "url": "https://my-store.dzbuild.app/pages/retours",
        "updated_at": "2026-11-06 10:12:40"
      }
    ],
    "cap": 25,
    "max_pages": 25
  },
  "meta": {"request_id": "3f1c9a7b20d4e865", "api_version": "v1"}
}

GET /v1/store/pages/{id}

صفحة واحدة.

المصادقة: مفتاح منصة بصلاحية store:read.

الطلب

curl 'https://api.dzbuild.app/v1/store/pages/7' \
  -H "Authorization: Bearer $DZ_KEY"

الاستجابة 200

الاستجابة هي كائن الصفحة. الصفحة التي ليست في المتجر تُرجع 404 page_not_found.

POST /v1/store/pages

ينشئ صفحة.

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

الجسم

الحقل	النوع	مطلوب	ملاحظات
title	string	نعم	من 1 إلى 120 حرفاً.
slug	string	لا	يُصنع من العنوان إذا لم ترسله. وإذا لم يعطِ ذلك slug صالحاً (عنوان ليس فيه حروف لاتينية ولا أرقام كالعنوان العربي، أو كلمة محجوزة، أو slug تستعمله صفحة أخرى)، تأخذ الصفحة page-N. الـslug الذي ترسله يُحوَّل إلى حروف صغيرة، ثم يجب أن يكون صالحاً وغير مستعمل.
body_md	string	لا	Markdown، حتى 65,536 بايت.
seo_title	string أو null	لا	حتى 70 حرفاً.
seo_description	string أو null	لا	حتى 160 حرفاً.
status	draft أو published	لا	القيمة الافتراضية draft. لا تنشر إلا إذا طلب التاجر ذلك.
translations	object أو null	لا	انظر اللغة الثانية.

لا يجوز أن يكون slug كلمة يستعملها المتجر في عناوينه، مثل products أو product أو cart أو checkout أو category أو track-order أو landing أو pages أو sitemap أو ar أو fr. هذا الـslug يُرجع 422 invalid_page.

الطلب

curl -X POST 'https://api.dzbuild.app/v1/store/pages' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: page-create-retours-1" \
  -d '{"title": "Retours", "slug": "retours", "body_md": "## Comment retourner un article\n\nÉcrivez-nous sur WhatsApp avec votre numéro de commande.", "status": "published"}'

الاستجابة 201

{
  "data": {
    "page": {
      "id": 7,
      "slug": "retours",
      "title": "Retours",
      "body_md": "## Comment retourner un article\n\nÉcrivez-nous sur WhatsApp avec votre numéro de commande.",
      "seo_title": null,
      "seo_description": null,
      "status": "published",
      "translations": null,
      "url": "https://my-store.dzbuild.app/pages/retours",
      "created_at": "2026-11-06 10:12:40",
      "updated_at": "2026-11-06 10:12:40"
    },
    "change_id": 90310
  },
  "meta": {"request_id": "8b2e04d1c9a7f356", "api_version": "v1"}
}

PATCH /v1/store/pages/{id}

يغيّر الحقول التي ترسلها فقط. يأخذ الجسم حقول POST، كلها اختيارية. الجسم الذي لا يحمل أياً منها يُرجع 422 no_changes، والنداء الذي لا يغيّر شيئاً يُرجع change_id: null.

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

• slug جديد يغيّر عنوان الصفحة. ويبقى العنوان القديم يجيب بتحويل 301 إلى الجديد، فتبقى الروابط المنشورة تعمل. ويمكن إرجاع الـslug القديم. وإذا لم ترسل slug يبقى العنوان كما هو، حتى لو تغيّر العنوان.
• "status": "draft" يُخرج الصفحة من المتجر دون حذفها.

الطلب

curl -X PATCH 'https://api.dzbuild.app/v1/store/pages/7' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: page-7-seo-1" \
  -d '{"seo_title": "Retours et échanges", "seo_description": "Comment retourner un article commandé sur notre boutique."}'

الاستجابة 200

للاستجابة حقول استجابة POST نفسها: page، أي الصفحة بعد التغيير، وchange_id.

DELETE /v1/store/pages/{id}

يحذف صفحة. يتوقف عنوانها في المتجر عن العمل فوراً.

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

الطلب

curl -X DELETE 'https://api.dzbuild.app/v1/store/pages/7' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Idempotency-Key: page-7-delete-1"

الاستجابة 200

{
  "data": {
    "deleted": true,
    "id": 7,
    "change_id": 90312
  },
  "meta": {"request_id": "c40a91e7b25d3f68", "api_version": "v1"}
}

التراجع

كل كتابة تُرجع change_id. يُلغي POST /v1/changes/{change_id}/undo ذلك التغيير. يحتاج التراجع إلى store:write وإلى Idempotency-Key.

• التراجع عن PATCH يُرجع الصفحة كما كانت قبل ذلك النداء. وإذا حُذفت الصفحة بعد ذلك، يُرجع التراجع 422 restore_target_missing.
• التراجع عن DELETE يُنشئ الصفحة من جديد برقمها وslug القديمين.
• لا يمكن التراجع عن الإنشاء: يُرجع التراجع 422 nothing_to_restore. احذف الصفحة بدلاً من ذلك.
• إذا أخذت صفحة أخرى رقم الصفحة المحذوفة أو slug الخاص بها بعد ذلك، أو صار في المتجر 25 صفحة، يُرجع التراجع عن الحذف 409 page_restore_conflict. غيّر اسم تلك الصفحة أو احذفها، ثم أعد التراجع.
• التغيير الذي يُتراجع عنه مرة ثانية يُرجع 409 already_undone.
• التغييرات التي يحفظها التاجر من صفحة التخصيص لا تُسجَّل، فلا يمكن التراجع عنها عبر الواجهة البرمجية.
• يعرض GET /v1/changes?entity=store.page تغييرات الصفحات، الأحدث أولاً، بصلاحية store:read. وentity_id هو رقم الصفحة.
• لا يستطيع رمز التطبيق المثبّت قراءة التغييرات ولا التراجع عنها: يُرجع GET /v1/changes والتراجع 403 forbidden (Apps cannot use this endpoint). وتبقى استجابات الكتابة تحمل change_id.

curl -X POST 'https://api.dzbuild.app/v1/changes/90312/undo' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Idempotency-Key: undo-90312"

{
  "data": {
    "undone": true,
    "change_id": 90312,
    "entity": "store.page",
    "undo_change_id": 90315
  },
  "meta": {"request_id": "71d5e0a2c8b94f36", "api_version": "v1"}
}

الأخطاء

HTTP	الرمز	السبب
400	bad_request	الجسم ليس كائن JSON، أو رقم الصفحة في المسار ليس رقماً موجباً، أو Idempotency-Key غائب أو غير صالح.
401	unauthorized	مفتاح خاطئ أو غائب.
402	quota_exceeded	انتهت حصة الطلبات الشهرية للمتجر. انظر حدود المعدل.
403	forbidden	Missing scope: store:read أو Missing scope: store:write، أو API access requires an active Enterprise plan لمفتاح تاجر متجره ليس على خطة Enterprise سارية.
403	plan_required	الإنشاء يتجاوز عدد الصفحات الذي تسمح به الخطة. يحمل الخطأ plan وcap.
404	page_not_found	لا توجد صفحة بهذا الرقم في المتجر.
409	slug_taken	صفحة أخرى في المتجر تستعمل هذا الـslug. قيمة fields هي [{"path": "slug", "code": "taken"}].
409	write_conflict	وصلت كتابة أخرى في اللحظة نفسها. اقرأ الصفحة، ثم أعد المحاولة بـIdempotency-Key جديد.
409	already_undone	للتراجع فقط: سبق التراجع عن هذا التغيير.
409	page_restore_conflict	للتراجع عن الحذف فقط: صفحة أخرى تستعمل الآن رقم الصفحة أو slug الخاص بها، أو في المتجر 25 صفحة بالفعل.
413	payload_too_large	الجسم أكبر من 1 MB.
422	invalid_page	قيمة مرفوضة: عنوان غائب أو فارغ، أو حقل ليس نصاً، أو slug غير صالح أو محجوز، أو status غير draft وpublished، أو translations ليس كائناً، أو body_md أكبر من 65,536 بايت. يذكر fields قيمتي {path, code} للحقل المرفوض، مثل slug.
422	limit_reached	في المتجر 25 صفحة بالفعل. يحمل الخطأ limit.
422	no_changes	PATCH لا يحمل أياً من حقول الصفحة.
422	nothing_to_restore	للتراجع فقط: التغيير أنشأ الصفحة.
422	restore_target_missing	للتراجع عن PATCH فقط: حُذفت الصفحة بعد ذلك.
422	idempotency_key_reuse	استُعمل Idempotency-Key نفسه مع جسم آخر.
429	rate_limited	طلبات كثيرة، ومنها أكثر من 30 كتابة صفحات في الدقيقة للمتجر. انتظر Retry-After.
429	too_many_concurrent	أكثر من 5 كتابات صفحات تعمل في الوقت نفسه للمتجر. أعد المحاولة بعد بضع ثوانٍ.
500	server_error	فشل الطلب. أعد المحاولة بـIdempotency-Key نفسه.

هكذا تبدو استجابة invalid_page.

{
  "error": {
    "code": "invalid_page",
    "message": "slug: 2 to 80 lowercase latin letters, digits or dashes, not a store route",
    "fields": [{"path": "slug", "code": "invalid"}]
  },
  "meta": {"request_id": "e9a3c17f04b26d58", "api_version": "v1"}
}

الحدود

• 25 صفحة لكل متجر (max_pages)، والمسودات محسوبة.
• حد الخطة (cap): 3 صفحات في الخطة المجانية أو الخطة المنتهية، و25 ابتداءً من Pro. المتجر الذي يتجاوز حده بعد تخفيض خطته يحتفظ بصفحاته ويستطيع قراءتها وتعديلها وحذفها. ويُرجع الإنشاء 403 plan_required حتى يصبح المتجر تحت حده.
• النص: body_md حتى 65,536 بايت، والطلب حتى 1 MB.
• الكتابات: 30 في الدقيقة و5 في الوقت نفسه لكل متجر، فوق الحد الدقيقي للمتجر. انظر حدود المعدل.

أدوات MCP

يعطي خادم MCP، في نسخته 1.8.0، المساعد الذكي خمس أدوات للصفحات بالقواعد نفسها: pages_list وpage_get وpage_create وpage_update وpage_delete. وأداة page_delete تطلب من المساعد أن يتأكد من التاجر أولاً.