نوعان من المفاتيح.

استخدم Bearer token من خادمك الخلفي:

الشكل هو key_id.key_secret، وكلا الجزأين مطلوب. وkey_id هو المعرّف المكوّن من 24 حرفًا والذي يبدأ أصلًا بـdzpk_live_ (مثال: dzpk_live_xxxxxxxxxxxxxx.<48-hex secret>)، لذا لا تُضِف البادئة مرة أخرى. أما سر المفتاح فطوله 48 حرفًا ست عشريًا ويُعرض مرة واحدة فقط عند الإنشاء ولن يظهر مجددًا.

لعدّ اشتراكات المستخدمين النهائيين وأحداثهم المخصصة من موقع أو تطبيق تديره خارج DZBuild. يستدعي خادمك الخلفي POST /v1/signups أو POST /v1/events ويوقّع كل طلب — لا تكشف سر التوقيع للمتصفح أبدًا.

الرؤوس:

هنا أيضًا يبدأ key_id أصلًا بـdzpub_live_ — مرّره كما أُرجع لك تمامًا. وسر التوقيع طوله 64 حرفًا ست عشريًا.

الـ nonce يُستخدم مرة واحدة فقط لكل مفتاح ولمدة ساعة، ويمنع إعادة التشغيل. الطابع الزمني يجب أن يكون ضمن ±5 دقائق.

⚠️ تنبيه — المفتاح العام الجديد يبقى معطّلًا حتى يُفعَّل

المفتاح من نوع type: public الذي تُنشئه عبر POST /v1/keys سيُرجع 401 إلى أن يُفعَّل لاستقبال حركة الواجهة البرمجية. راسل الدعم مباشرة بعد إنشائه لتفعيله. أما مفاتيح المنصة (Bearer) فلا يشملها ذلك — تعمل فورًا.

كل مفتاح له قائمة من الصلاحيات. صلاحيات منصة افتراضية: 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. المفتاح الذي يُنشأ من لوحة التحكم يحصل على هذه القائمة بالضبط. وهي لا تضم delivery:send ولا ai:generate، لذا فالمفتاح المُنشأ من لوحة التحكم أو عبر POST /v1/keys يتلقى 403 على POST /v1/orders/{id}/send-to-delivery وPOST /v1/landing-pages/generate.

صلاحيات عامة افتراضية: signups:write, events:write.

تُفحَص الصلاحيات في القراءة كما في الكتابة: المفتاح الذي لا يملك orders:read يتلقى 403 مع الرسالة Missing scope: orders:read على GET /v1/orders. والصلاحية store:write تشمل كتابات إعدادات المتجر وتصميمه وقالبه وأقسام صفحته الرئيسية. أما signups:write وevents:write فتخصّان POST /v1/signups وPOST /v1/events.

إدارة المفاتيح (/v1/keys) محكومة بـنوع المفتاح لا بصلاحياته: المفتاح العام الذي يستدعيها يتلقى 403 — "Key management requires a platform key".

مفتاح المنصة الذي يُنشأ عبر POST /v1/keys لا يحصل إلا على الصلاحيات التي يملكها المفتاح المستدعي أصلًا (403 إن لم تجمعهما أي صلاحية مشتركة). أما المفتاح من نوع type: public فيحصل دائمًا على signups:write وevents:write.

ينشئ مالك متجر على خطة Enterprise سارية مفاتيحه الشخصية من لوحة التحكم عبر الإعدادات ← واجهة API (/dashboard/api). يُسجَّل المفتاح الجديد في البرنامج التجريبي تلقائيًا ويعمل فورًا، فلا شيء تطلبه من الدعم. تعرض الصفحة قيمتين، مرة واحدة فقط، عند إنشاء المفتاح:

يحتفظ المتجر بـ 3 مفاتيح شخصية نشطة كحد أقصى. والمفاتيح التي تحملها التطبيقات المثبّتة أو Copilot أو أحد الموصلات لا تشغل أيًّا من هذه الأماكن.

الاتصال الذي يُنشأ لـ Copilot أو لمساعد ذكاء اصطناعي متصل (Claude أو ChatGPT) يمكن أن يغطي عدة متاجر للتاجر، بمفتاح لكل متجر. وتسمح نقطتا نهاية للمفتاح الذي يحمله اتصال كهذا بقراءة المتاجر التي يغطيها وبتغيير المتجر النشط منها. أما أي مفتاح آخر، بما في ذلك المفتاح المُنشأ من لوحة التحكم، فيتلقى 404 not_found مع This key does not belong to an assistant connection.

يحتاج إلى store:read.

client_name هو اسم تطبيق المساعد. والاتصال الذي تمّت الموافقة عليه قبل أن تصبح الاتصالات قادرة على تغطية عدة متاجر يسرد متجره الوحيد.

يحتاج إلى store:write وإلى Idempotency-Key. ويحدّد store_id في الجسم المتجر الذي يصبح نشطًا.

الاستجابة هي الاتصال بعد النقل، بالشكل نفسه الذي يُرجعه GET /v1/connection. المتجر النشط مؤشّر وليس صلاحية: كل طلب يبقى يعمل على المتجر الوحيد الذي ينتمي إليه مفتاحه. والمتجر الذي لا يدخل في الاتصال يُرجع 403 store_not_in_connection، والجسم الذي لا يحمل store_id يُرجع 400 bad_request.