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

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

⚠️ تنبيه — وجّه تكاملك إلى 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": ..., "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`. أرسل رأس `X-Request-Id` خاصًا بك وسنعيده كما هو، لتتطابق سجلاتك مع سجلاتنا.
`X-Api-Version`	في معظم الاستجابات	دائمًا `v1`. لا يظهر في عمليات الكتابة المُعادة (idempotent replays) ولا في استجابات ذاكرة القراءة المؤقتة (cache hits).
`X-Cache`	في طلبات `GET` القابلة للتخزين المؤقت	`HIT` تعني أن الاستجابة أتت من ذاكرة القراءة المؤقتة، و`MISS` تعني أنها جُلبت حديثًا.
`Idempotency-Replay`	في عمليات الكتابة المُعادة	القيمة `1` تعني أن هذه هي الاستجابة المخزَّنة لنداء سابق بنفس `Idempotency-Key` — ولم يحدث أي أثر جانبي جديد. انظر Idempotency.

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

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

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

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

بداية سريعة

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

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

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