أدر مفاتيح الواجهة البرمجية لـ متجرك. كل عمليات المفاتيح تتطلب مفتاح منصة أنشأته أنت. المفتاح العام يتلقى 403 forbidden ("Key management requires a platform key")، والمفتاح الذي يستعمله Copilot أو مساعد ذكاء اصطناعي متصل (Claude أو ChatGPT) يتلقى 403 ("This connection cannot manage API keys")، ورمز التطبيق المثبّت يتلقى 403 ("Apps cannot use this endpoint").
انتباه: المفتاح المُنشَأ عبر الواجهة البرمجية يصبح فعّالًا فورًا. لا يوجد تأكيد بالبريد ولا موافقة من مشرف. إن أنشأت مفتاحًا بصلاحيات واسعة وسرّبته، فإن المسرّب يمكنه التصرف بكامل صلاحيات هذا المفتاح حتى تستخدم DELETE. أبقِ الأسرار خارج المستودعات والشاشات المشتركة.
الحصول على مفتاحك الأول
الواجهة البرمجية حصرية لخطة Enterprise: لا تُصدَر المفاتيح إلا للمتاجر ذات خطة Enterprise سارية، وإنشاء مفتاح لأي خطة أخرى يفشل. أنشئ مفتاحك الأول من لوحة التحكم عبر الإعدادات ← واجهة API (/dashboard/api)، وهي متاحة لمالك المتجر، ويظهر السر مرة واحدة عند الإنشاء. ويمكنك أيضًا إنشاء المفاتيح وتدويرها عبر النقاط أدناه. يمكن للمتجر الاحتفاظ بـ 3 مفاتيح نشطة كحد أقصى من المفاتيح التي أنشأتها أنت، من لوحة التحكم أو عبر POST /v1/keys؛ ألغِ مفتاحًا لتحرير مكانه. المفاتيح التي يستعملها Copilot أو مساعد ذكاء اصطناعي متصل (Claude أو ChatGPT) أو تطبيق مثبّت لا تشغل هذه الأماكن. وإنشاء مفتاح بعد بلوغ الحد عبر POST /v1/keys يُرجع 400 bad_request ("Key limit reached for this store").
كما أن الواجهة البرمجية حاليًا مقيَّدة ببرنامج تجريبي (pilot). المفاتيح التي تُنشئها ترث تسجيل مفتاحك في البرنامج التجريبي فتعمل — أما أي مفتاح أُنشئ خارجه فيُرجع 403 forbidden ("API is in pilot mode; key not enrolled") على كل نداء.
GET /v1/keys
اسرد مفاتيح متجرك (يستثنى المُلغَى؛ المفاتيح المُلغَاة محفوظة في سجل التدقيق لكنها مخفية عن هذه القائمة). والمفاتيح التي يستعملها Copilot أو مساعد ذكاء اصطناعي متصل (Claude أو ChatGPT) أو تطبيق مثبّت لا تظهر في القائمة.
المصادقة: مفتاح منصة.
الاستجابة 200
{
"data": {
"items": [
{
"key_id": "dzpk_live_xxxxxxxxxxxxxx",
"type": "platform",
"name": "production-server-1",
"scopes": ["store:read", "products:read", "orders:read", "orders:write"],
"rate_limit_tier": "enterprise",
"pilot": true,
"status": "active",
"last_used_at": "2026-04-30 19:35:49",
"last_used_ip": "203.0.113.42",
"created_at": "2026-04-30 19:27:55",
"expires_at": null
}
]
}
}
ملاحظات: - last_used_at يُحدَّث مرة واحدة في الدقيقة على الأكثر لكل مفتاح، لذا قد يتأخر عن آخر نداء لك. - last_used_ip هو عنوان IP المصدر للمنادي كما تراه الواجهة البرمجية — أي IP العميل الأصلي، لا عنوان وسيط. - الأسرار لا تُعاد أبدًا عبر GET. - expires_at دائمًا null — لا شيء يضبطه والمفاتيح لا تنتهي تلقائيًا. ألغِها صراحةً. - المفاتيح بحالة status: "suspended" تظهر في هذه القائمة؛ المخفية هي المُلغَاة فقط. - key_id دائمًا 24 حرفًا بالضبط بما في ذلك البادئة dzpk_live_ / dzpub_live_.
POST /v1/keys — إنشاء
أنشئ مفتاحًا جديدًا. السر يُعاد مرة واحدة فقط — احفظه فورًا.
المصادقة: مفتاح منصة. يتطلب Idempotency-Key، لكن الإنشاء لا يُحفَظ أبدًا لإعادة التشغيل لأن الاستجابة تحمل أسرارًا: إعادة المحاولة بنفس Idempotency-Key تُنشئ مفتاحًا ثانيًا، فراجع GET /v1/keys قبل أن تعيد المحاولة.
الجسم
الحقل | النوع | إلزامي | ملاحظات |
|
| الافتراضي | |
| string ≤ 100 | تسمية حرة. الافتراضي |
الخطة (tier) والتسجيل في البرنامج التجريبي يُورَّثان من المفتاح المنادي، ومفتاح المنصة الجديد لا يحصل أبدًا على صلاحيات أكثر مما يملكه المفتاح المنادي. مفتاح المنصة المُنشأ عبر POST /v1/keys يحصل على صلاحيات المنصة الافتراضية التي يملكها المفتاح المنادي أصلًا؛ وإن لم يملك المفتاح المنادي أيًّا منها، يُرجع النداء 403 forbidden ("This key holds none of the scopes a new platform key can carry"). مجموعة المنصة الافتراضية، التي تحصل عليها كاملةً المفاتيح المُنشأة من لوحة التحكم، هي 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. والمفاتيح العامة تحصل دائمًا على signups:write وevents:write. تواصل مع الدعم إن أردت مفتاحًا بصلاحيات مخفَّضة.
الطلب
curl -X POST 'https://api.dzbuild.app/v1/keys' \
-H "Authorization: Bearer $DZ_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "type": "platform", "name": "ci-deploy-key" }'
الاستجابة 200
إنشاء المفتاح يُرجع HTTP 200 وليس 201 — تحقّق من data.key_id بدل رمز الحالة.
{
"data": {
"key_id": "dzpk_live_a3f9...",
"bearer_token": "dzpk_live_a3f9..........73ad…",
"signing_secret": "<64-character hex signing secret>",
"note": "Save these now — secrets are not retrievable."
}
}
لمفتاح منصة: bearer_token هو ما تضعه في Authorization: Bearer ... — وصيغته {key_id}.{سر hex من 48 حرفًا}. لمفتاح عام: bearer_token يكون null وتستخدم signing_secret لحساب تواقيع HMAC (انظر المصادقة).
DELETE /v1/keys/{key_id} — إلغاء
المصادقة: مفتاح منصة. يتطلب Idempotency-Key. المفتاح الذي ليس من متجرك، أو الذي يستعمله Copilot أو مساعد ذكاء اصطناعي متصل (Claude أو ChatGPT) أو تطبيق مثبّت، يُرجع 404 not_found. وإلغاء مفتاح مُلغًى من قبل يُرجع رغم ذلك revoked: true.
curl -X DELETE 'https://api.dzbuild.app/v1/keys/dzpk_live_a3f9...' \ -H "Authorization: Bearer $DZ_KEY" \ -H "Idempotency-Key: revoke-a3f9"
الاستجابة:
{ "data": { "revoked": true, "key_id": "dzpk_live_a3f9..." } }
ما يحدث:
تتحوّل حالة المفتاح إلى
revokedفورًا ويختفي منGET /v1/keys.يُسجَّل الإلغاء في سجل تدقيق المفاتيح الخاص بك.
قد يستغرق انتشار الإلغاء حتى ~60 ثانية؛ حتى ذلك الحين قد ينجح المفتاح في بعض النداءات. إن كان القطع الفوري حرجًا، تواصل مع الدعم.
أفضل الممارسات
مفتاح لكل بيئة — مفتاح
stagingومفتاحproduction. لا تُشاركها.مفتاح لكل تكامل — مفتاح لـ Zapier، آخر لمزامنة CRM، آخر لخط التحليلات. أسهل في إلغاء تكامل واحد دون كسر الباقي.
دوّر دوريًا — كل 90 يومًا لمفاتيح الإنتاج وتيرة معقولة.
راجع
last_used_at— المفاتيح غير المستخدمة منذ 30+ يومًا مرشّحة للإلغاء.لا ترسل سرًا بالبريد أبدًا — الصقه مرة في مدير الأسرار ولن تحتاجه ثانية.