نوعان من المفاتيح.
مفتاح المنصة (خادم إلى خادم، CRUD كامل)
استخدم Bearer token من خادمك الخلفي:
Authorization: Bearer <key_id>.<key_secret>
الشكل هو key_id.key_secret — كلا الجزأين مطلوب. وkey_id هو المعرّف المكوّن من 24 حرفًا والذي يبدأ أصلًا بـdzpk_live_ (مثال: dzpk_live_c741d949613f8f.<48-hex secret>)، لذا لا تُضِف البادئة مرة أخرى. أما سر المفتاح فطوله 48 حرفًا ست عشريًا ويُعرض مرة واحدة فقط عند الإنشاء ولن يظهر مجددًا.
المفتاح العام (المواقع والتطبيقات الخارجية؛ موقّع بـ HMAC)
لعدّ اشتراكات المستخدمين النهائيين وأحداثهم المخصصة من موقع أو تطبيق تديره خارج DZBuild. يستدعي خادمك الخلفي POST /v1/signups أو POST /v1/events ويوقّع كل طلب — لا تكشف سر التوقيع للمتصفح أبدًا.
الرؤوس:
Authorization: DZ-Public <key_id> X-DZ-Timestamp: <unix_seconds> X-DZ-Nonce: <32-hex> X-DZ-Signature: hex(hmac_sha256(signing_secret, key_id + "\n" + nonce + "\n" + ts + "\n" + sha256(body)))
هنا أيضًا يبدأ key_id أصلًا بـdzpub_live_ — مرّره كما أُرجع لك تمامًا. وسر التوقيع طوله 64 حرفًا ست عشريًا.
الـ nonce يُستخدم مرة واحدة فقط لكل مفتاح ولمدة ساعة، ويمنع إعادة التشغيل. الطابع الزمني يجب أن يكون ضمن ±5 دقائق.
⚠️ تنبيه — المفتاح العام الجديد يبقى معطّلًا حتى يُفعَّل
المفتاح من نوع type: public الذي تُنشئه عبر POST /v1/keys سيُرجع 401 إلى أن يُفعَّل لاستقبال حركة الواجهة البرمجية. راسل الدعم مباشرة بعد إنشائه لتفعيله. أما مفاتيح المنصة (Bearer) فلا يشملها ذلك — تعمل فورًا.
الصلاحيات (Scopes)
كل مفتاح له قائمة من الصلاحيات. صلاحيات منصة افتراضية: store:read, store:write, products:read, products:write, orders:read, orders:write, customers:read, landing_pages:read, landing_pages:write, webhooks:read, webhooks:write, usage:read.
صلاحيات عامة افتراضية: signups:write, events:write.
تُطبَّق الصلاحيات اليوم على نقاط الكتابة والنقاط المحسوبة: products:write، orders:write، landing_pages:write، webhooks:write، إضافة إلى webhooks:read وusage:read. أما نقاط القراءة (المتجر، المنتجات، الطلبات، العملاء، صفحات الهبوط) فتقبل حاليًا أي مفتاح نشط ومُسجَّل في البرنامج التجريبي بغضّ النظر عن قائمة صلاحياته. والصلاحيات store:write وsignups:write وevents:write تُمنح افتراضيًا لكن لا توجد نقطة تستهلكها بعد. لا تعتمد على حذف صلاحية ما لتقييد ما يستطيع المفتاح قراءته.
إدارة المفاتيح (/v1/keys) محكومة بـنوع المفتاح لا بصلاحياته: المفتاح العام الذي يستدعيها يتلقى 403 — "Key management requires a platform key".
التسجيل في البرنامج التجريبي
ما دامت الواجهة في المرحلة التجريبية، فإن المفتاح الصالح والموقّع بشكل صحيح يُرجع مع ذلك 403 forbidden ما لم يكن مُسجَّلًا في البرنامج التجريبي. راسل الدعم مع رقم متجرك لتسجيله.