💡 نصيحة — أنشئ تطبيقاتك لمتاجر DZBuild

أنشئ تطبيقات يستطيع التجار تثبيتها على متاجرهم في DZBuild. زر بوابة المطورين dzbuild.dev للاطلاع على القوالب الرسمية والأدلة، أو ابدأ إنشاء تطبيق.

اشتراط خطة المؤسسات أدناه يخص مفاتيح API الشخصية للتاجر. لتثبيت التطبيقات شروط وصول مستقلة، منها الحد الأدنى للخطة والصلاحيات التي يطلبها التطبيق.

تتيح لك واجهة DZBuild البرمجية إدارة متجرك برمجيًا: المنتجات، الطلبات، العملاء، صفحات الهبوط، بالإضافة إلى متتبع اشتراكات عالي الحجم للتجار الذين يدمجون DZBuild في منصاتهم الخاصة.

عنوان القاعدة: https://api.dzbuild.app/v1 — وهو عنوان القاعدة العام الوحيد المدعوم. الإصدار: مستقر على v1. أي تغييرات جذرية تتطلب بادئة مسار جديدة. التنسيق: JSON دخولًا وخروجًا، بترميز UTF-8. المصادقة: انظر المصادقة. مفاتيح API الشخصية: تحتاج إلى متجر باشتراك سارٍ في خطة المؤسسات. لا ينطبق هذا الشرط على رموز تثبيت التطبيقات، التي تخضع لشروط الوصول المرتبطة أعلاه. الحالة: تجريبي (Pilot). ينشئ مالك متجر على خطة Enterprise سارية مفاتيحه الشخصية من لوحة التحكم عبر الإعدادات ← واجهة API (/dashboard/api). يُسجَّل المفتاح الجديد في البرنامج التجريبي تلقائيًا ويعمل فورًا، فلا حاجة إلى طلب أي شيء من الدعم.

⚠️ تنبيه — وجّه تكاملك إلى api.dzbuild.app ولا شيء غيره

العنوان https://dzbuild.com/api/v1 هو مجرد اسم بديل داخلي، وليس هدفًا للتكامل. على هذا المضيف: المساران /v1/signups و/v1/events غير موجودين (404)، ونداءات المفتاح العام (DZ-Public) تُرفض بـ401. أما إعادة التشغيل idempotent وحد المعدل لكل متجر فيسريان على المضيفين معًا.

بداية سريعة

curl https://api.dzbuild.app/v1/ping

الاستجابة:

{ "data": { "pong": true, "time": "2026-04-30T20:15:59.836Z", "edge": true },
  "meta": { "request_id": "...", "api_version": "v1", "edge": true } }

طلب موثَّق:

curl https://api.dzbuild.app/v1/whoami \
  -H "Authorization: Bearer <your_key_id>.<your_key_secret>"

الاستجابة:

{ "data": { "key_id": "dzpk_live_xxxxxxxxxxxxxx", "store_id": 10, "type": "platform",
            "rate_limit_tier": "enterprise", "pilot": true,
            "scopes": ["store:read", "store:write", "products:read", "products:write",
                       "orders:read", "orders:write", "customers:read", "landing_pages:read",
                       "landing_pages:write", "promos:read", "promos:write", "pixels:read",
                       "pixels:write", "shipping:read", "shipping:write", "webhooks:read",
                       "webhooks:write", "usage:read", "analytics:read", "whatsapp:read",
                       "whatsapp:send"] },
  "meta": { "request_id": "...", "api_version": "v1" } }

يسرد scopes ما يحق لهذا المفتاح استدعاؤه: نقطة النهاية التي تحتاج إلى صلاحية غائبة عن القائمة تُرجع 403 مع Missing scope: متبوعة باسم الصلاحية. ومع رمز تطبيق مثبّت تحمل استجابة whoami أيضًا app، مع app_id وclient_id وinstall_id الخاصة به.

بنية الاستجابة

كل الاستجابات تتبع الشكل ذاته:

نجاح

{ "data": ..., "meta": { "request_id": "...", "api_version": "v1" } }

خطأ

{ "error": { "code": "rate_limited", "message": "...", "retry_after": 12 },
  "meta": { "request_id": "...", "api_version": "v1" } }

رؤوس الاستجابة

الرأس	متى	المعنى
`X-Request-Id`	في كل استجابة	القيمة نفسها الموجودة في `meta.request_id`، إلا في استجابة كتابة مُعادة (`Idempotency-Replay: 1`): محتواها هو المحتوى المخزَّن، فيبقى فيه `meta.request_id` الخاص بالنداء الأول. أرسل رأس `X-Request-Id` خاصًا بك وسنعيده كما هو، لتتطابق سجلاتك مع سجلاتنا.
`X-Api-Version`	في معظم الاستجابات	دائمًا `v1`.
`X-Cache`	في `GET /v1/products` و`GET /v1/landing-pages` و`GET /v1/store` ومساراته الفرعية	دائمًا `MISS`: هذه القراءات تُخدَم حديثًا.
`Idempotency-Replay`	في عمليات الكتابة المُعادة	القيمة `1` تعني أن هذه هي الاستجابة المخزَّنة لنداء سابق بنفس `Idempotency-Key` — ولم يحدث أي أثر جانبي جديد. انظر Idempotency.

معلومات مفيدة

يُتحقَّق من مفتاحك في كل طلب — سواء كان Bearer token أو توقيع HMAC لمفتاح عام.
الحد لكل دقيقة يُطبَّق لكل متجر — جميع مفاتيح المتجر تتشارك ميزانية واحدة — ضمن نافذة ثابتة مدتها 60 ثانية (يُصفَّر العدّاد مع كل دقيقة من ساعة الحائط). والتطبيق تقريبي عند الدفعات الكبيرة، لذا تعامل مع 429 بحذر بدل ضبط وتيرتك تمامًا على الحد. وهو يخصّ نداءات الواجهة البرمجية وحدها — فواجهة متجر التاجر وصفحة إتمام الطلب ولوحة التحكم لا تستهلكه أبدًا. انظر حدود المعدل.
كل طلب GET يُخدَم حديثًا من المنصة: لا توجد ذاكرة قراءة مؤقتة على حافة api.dzbuild.app، فتُرجع GET /v1/products وGET /v1/landing-pages وGET /v1/store وكل طلب GET تحته القيمَ الحالية في كل نداء. خزّن من جهتك عندما تقرأ بحجم كبير.
الكتابات عالية الحجم (/v1/signups, /v1/events) تُقبل بشكل غير متزامن وتُرجع 202 Accepted فورًا — نداؤك لا ينتظر انتهاء المعالجة.

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

واجهة DZBuild البرمجية — مقدمة

بداية سريعة

بنية الاستجابة

رؤوس الاستجابة

معلومات مفيدة