واجهة DZBuild البرمجية

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

عنوان القاعدة: https://api.dzbuild.app/v1 — وهو عنوان القاعدة العام الوحيد المدعوم. الإصدار: مستقر على v1. أي تغييرات جذرية تتطلب بادئة مسار جديدة. التنسيق: JSON دخولًا وخروجًا، بترميز UTF-8. المصادقة: انظر المصادقة. الحالة: تجريبي (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 لمفتاح عام.
• الحد لكل دقيقة يُطبَّق لكل مفتاح API، ضمن نافذة ثابتة مدتها 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 فورًا — نداؤك لا ينتظر انتهاء المعالجة.