يغطّي هذا الدليل كيفية حمل بيانات اعتماد DZBuild API بأمان إلى تطبيقك — تطوير محلي، staging، إنتاج. سواء تبني واجهة Node.js، back-office Laravel/Symfony، خط بيانات Python، خدمة Go صغيرة، أو دالة edge serverless، القواعد ذاتها.

قبل أن تبدأ

يجب أن يكون متجرك على خطة Enterprise سارية، وأن يكون مفتاحك مُسجَّلًا في البرنامج التجريبي. فـ API v1 حصري لخطة Enterprise ومُقيَّد بالبرنامج التجريبي في الإنتاج. على أي خطة أخرى، أو بعد انتهاء اشتراك Enterprise، يُرجع كل نداء 403 forbidden "API access requires an active Enterprise plan". والمفاتيح المُنشأة من الإعدادات ← واجهة API تُسجَّل تلقائيًا؛ أما المفتاح غير المُسجَّل فيُرجع 403 forbidden "API is in pilot mode; key not enrolled" في كل نداء، مهما كان إعدادك صحيحًا.
وجّه DZBUILD_API_BASE دائمًا إلى https://api.dzbuild.app/v1. فـ dzbuild.com/api/v1/... مجرد اسم بديل لنفس الـ API: قد تُحجب عليه بعض المسارات. أما تحديد المعدل لكل متجر (المشترك بين كل مفاتيح المتجر) وإعادة تشغيل idempotency فيسريان على المضيفين معًا.

ما تحتاج تخزينه

لتكامل واجهة / back-office نموذجي:

المتغير	مثال	ملاحظات
`DZBUILD_API_KEY`	`dzpk_live_0123456789abcd.<48 hex>`	رمز bearer الكامل. عامله ككلمة مرور.
`DZBUILD_API_BASE`	`https://api.dzbuild.app/v1`	عنوان القاعدة. استخدم هذا المضيف في الإنتاج، لا `dzbuild.com/api/v1` (هو alias فقط).
`DZBUILD_WEBHOOK_SECRET`	64 محرفًا ست عشريًا صغيرًا	سر لكل webhook يعود من التسجيل. بلا بادئة. كل تسليم إلى ذلك الـ webhook يُوقَّع به؛ انظر أسرار Webhooks.

تشريح رمز الـ bearer

التجار يبترون هذا الرمز باستمرار، فيستحق التوضيح. رمز bearer لمفتاح المنصة هو:

dzpk_live_<14 hex>.<48 hex>

73 محرفًا، كلها صغيرة بعد البادئة، وبينها نقطة واحدة. والجزء dzpk_live_… قبل النقطة هو معرّف المفتاح — هوية لا بيان اعتماد. وAuthorization: Bearer يحتاج السلسلة كاملة بمحارفها الـ 73.

وإن أخطأت في ذلك تختلف الطبقتان، وهذا تشخيص مفيد:

رمز بلا نقطة إطلاقًا ← 401 unauthorized "Invalid bearer format".
رمز جيّد الشكل لكنه مجهول / ملغى ← 401 unauthorized "Invalid or revoked API key".

لـ تدفق المفتاح العام (signups / events من عميل عام):

المتغير	مثال	ملاحظات
`DZBUILD_PUBLIC_KEY_ID`	`dzpub_live_...`	آمن للشحن في كود العميل (المعرّف عام، السر لا)
`DZBUILD_SIGNING_SECRET`	64 محرفًا ست عشريًا صغيرًا، بلا بادئة	خادمي فقط — لتوقيع HMAC لكل جسم طلب

ملفات .env

النمط الأبسط:

# .env (في جذر مشروعك، gitignored)
DZBUILD_API_KEY=dzpk_live_0123456789abcd.0123456789abcdef0123456789abcdef0123456789abcdef
DZBUILD_API_BASE=https://api.dzbuild.app/v1
DZBUILD_WEBHOOK_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

# .gitignore
.env
.env.local
.env.*.local

ضع ملف .env.example بقيم placeholder ليعرف المطورون الآخرون ما يضبطون:

# .env.example (ملتزَم بـ git)
DZBUILD_API_KEY=dzpk_live_REPLACE_ME
DZBUILD_API_BASE=https://api.dzbuild.app/v1
DZBUILD_WEBHOOK_SECRET=REPLACE_ME_64_HEX

تحميل .env لكل لغة

Node.js / Next.js / Express

// next.config.js — Next.js يُحمّل .env و .env.local و .env.production تلقائيًا
// لـ Node عادي:
import 'dotenv/config';
const key = process.env.DZBUILD_API_KEY;

Python

# pip install python-dotenv
from dotenv import load_dotenv
import os
load_dotenv()
key = os.environ['DZBUILD_API_KEY']

PHP / Laravel

// Laravel يُحمّل .env تلقائيًا
$key = env('DZBUILD_API_KEY');// PHP عادي:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$key = $_ENV['DZBUILD_API_KEY'];

Go

// go get github.com/joho/godotenv
godotenv.Load()
key := os.Getenv("DZBUILD_API_KEY")

Flutter / موبايل

لا تشحن مفتاح المنصة في تطبيقك المحمول. بدلًا من ذلك:

ينادي تطبيقك المحمول خادمك الخلفي.
خادمك الخلفي يحمل المفتاح ويُمرّر الطلبات إلى DZBuild.

إن احتاج تطبيقك المحمول إلى تسجيل signups، فأرسلها هي أيضًا إلى خادمك الخلفي. فكل طلب بالمفتاح العام يحمل توقيع HMAC مصنوعًا بسر التوقيع، وهذا السر لا يُشحن أبدًا داخل تطبيق: خادمك الخلفي يوقّع النداء ويُمرّره، كما في قسم المفتاح العام أدناه. ومعرّف المفتاح العام وحده آمن للكشف. انظر نقاط المفتاح العام.

بيئات الإنتاج

في الإنتاج لا تستعمل ملف .env. استعمل مدير الأسرار الأصلي للمنصة:

Vercel / Netlify / Cloudflare Pages

المشروع → الإعدادات → Environment Variables
   DZBUILD_API_KEY = dzpk_live_...
   DZBUILD_API_BASE = https://api.dzbuild.app/v1
   DZBUILD_WEBHOOK_SECRET = <64-char lowercase hex>

علّم متغيرات الإنتاج في scope "Production". متغيرات staging في "Preview" أو بيئة منفصلة.

Cloudflare Workers

wrangler secret put DZBUILD_API_KEY
# (الصق القيمة عند الطلب)

متاح في الـ worker كـ env.DZBUILD_API_KEY (مع [vars] في wrangler.toml).

AWS Lambda / API Gateway

استعمل AWS Secrets Manager أو Parameter Store:

import boto3, json
secret = json.loads(
    boto3.client('secretsmanager').get_secret_value(SecretId='dzbuild/prod')['SecretString']
)
key = secret['DZBUILD_API_KEY']

لا تخزّن المفتاح في Lambda env vars بنص واضح (يظهر في سجلات CloudTrail). أحل من Secrets Manager.

Docker / Docker Compose

# docker-compose.yml
services:
  app:
    image: yourapp:latest
    env_file:
      - .env.production    # غير ملتزَم
    environment:
      - NODE_ENV=production

لـ Kubernetes استعمل Secret:

apiVersion: v1
kind: Secret
metadata:
  name: dzbuild-creds
type: Opaque
stringData:
  DZBUILD_API_KEY: dzpk_live_...
  DZBUILD_WEBHOOK_SECRET: <64-char lowercase hex>

ثم أحل في النشر:

envFrom:
  - secretRef:
      name: dzbuild-creds

GitHub Actions

# .github/workflows/deploy.yml
env:
  DZBUILD_API_KEY: ${{ secrets.DZBUILD_API_KEY }}

اضبط السر في Repo → Settings → Secrets and variables → Actions.

مفاتيح dev مقابل production

أنشئ دائمًا مفتاحين منفصلين:

واحد بالاسم dev أو staging — للاستخدام في .env.local / بيئات dev
واحد بالاسم production — يُستعمل فقط في نشر الإنتاج الفعلي

إن تسرّب مفتاح dev، تحرق dev فقط. بيانات الإنتاج تبقى سليمة.

كيف تحصل على المفتاح

يُنشئ مالك المتجر المفاتيح من لوحة تحكم التاجر عبر الإعدادات ← واجهة API (/dashboard/api). ويجب أن يكون المتجر على خطة Enterprise سارية، ويحتفظ بـ 3 مفاتيح نشطة كحد أقصى.

مفتاحك الأول يأتي من تلك الصفحة: اضغط إنشاء مفتاح API، وسمِّه باسم البيئة التي سيعيش فيها (myapp-dev، myapp-prod)، ثم انسخ رمز الـ bearer الذي يظهر مرة واحدة فقط. والمفاتيح المُنشأة هناك مُسجَّلة مسبقًا في البرنامج التجريبي.
المفاتيح التالية يمكنك إنشاؤها بنفسك انطلاقًا من مفتاح قائم:

bash curl -X POST 'https://api.dzbuild.app/v1/keys' \ -H "Authorization: Bearer $DZBUILD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"type":"platform","name":"myapp-dev"}' # HTTP 200 → { "data": { "key_id", "bearer_token", "signing_secret", "note" } }

يرث المفتاح الجديد فئة تحديد المعدل وعَلَم البرنامج التجريبي من المفتاح المنادي حرفيًا.

الصلاحيات غير قابلة للاختيار. فـ POST /v1/keys لا يقبل إلا type و name. ومفتاح المنصة المُنشأ من الإعدادات ← واجهة API يحصل على المجموعة الافتراضية الكاملة: 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. ومفتاح المنصة المُنشأ بـ POST /v1/keys يحصل على هذه المجموعة ناقصًا كل صلاحية لا يملكها المفتاح المنادي، ولا يحصل أبدًا على أكثر منها. أما المفتاح العام فيحصل دائمًا على signups:write و events:write. والفصل بين dev و prod يأتي من استعمال مفتاحين مختلفين، لا من تضييق الصلاحيات.

أسرار Webhooks

عند تسجيل webhook تتضمن الاستجابة secret:

curl -X POST 'https://api.dzbuild.app/v1/webhooks' \
  -H "Authorization: Bearer $DZBUILD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url":    "https://yourapp.com/webhook",
    "events": ["order.created", "order.confirmed"]
  }'

الاستجابة — HTTP 200، وثلاثة حقول فقط:

{
  "data": {
    "id":     42,
    "secret": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "note":   "Save the secret now — it is not retrievable after this response."
  },
  "meta": { "request_id": "...", "api_version": "v1" }
}

الـ secret سلسلة مجرّدة من 64 محرفًا ست عشريًا صغيرًا — لا توجد بادئة dzwh_sec_. وهو يظهر مرة واحدة؛ احفظه فورًا في مدير أسرارك. إن فقدته، احذف الـ webhook وسجّل واحدًا جديدًا.

ℹ️ معلومة — تحقّق من كل تسليم API v1 بهذا السر

يحمل كل تسليم إلى الـ webhook الترويسة X-DZ-Signature: t=<unix seconds>,v1=<hex>، وهي HMAC-SHA256 للقيمة t + "." + raw_body بالمفتاح DZBUILD_WEBHOOK_SECRET. أعد حسابها، وقارن بزمن ثابت، وارفض أي t تبتعد عن ساعتك بأكثر من 300 ثانية. أما الـ webhook المسجّل قبل اعتماد التوقيع بسر كل webhook فيبقى على توقيع قديم لا يستطيع هذا السر فحصه: سجّل ذلك الـ webhook من جديد.

الوصفة والشيفرة بأربع لغات موجودة في التحقق من التواقيع.

تدفق المفتاح العام (signups / events)

يوجد تدفق المفتاح العام للنقاط محدودة النطاق (تتبع signups، تتبع events) حيث لا تريد إدخال مفتاح منصة في الحلقة. ومعرّف المفتاح العام وحده غير سرّي — أما سر التوقيع فيبقى على خادمك الخلفي.

⚠️ تنبيه — لا تنادِ /v1/signups مباشرة من متصفح

ثلاثة أمور تُفشل النداء المباشر من المتصفح اليوم:

لا يوجد CORS. لا تجيب الـ API على أي طلب تمهيدي (preflight): طلب OPTIONS بلا مفتاح يتلقى الرد المعتاد 401 دون أي ترويسة Access-Control-*، فيحجب المتصفح النداء. الـ API مخصّصة للنداءات من خادم إلى خادم فقط.
Idempotency-Key إلزامية في كل POST، ومن السهل نسيانها في كود العميل.
crypto.randomUUID() ليس nonce صالحًا. فالـ nonce يجب أن يكون 32 محرفًا ست عشريًا صغيرًا بالضبط؛ أما UUID بـ 36 محرفًا وشرطات فيُرجع 401 unauthorized "Invalid nonce format".

مرّر عبر خادمك الخلفي بدلًا من ذلك — بالنمط أدناه.

// المتصفح: تحدّث مع نقطتك أنت، لا مع api.dzbuild.app
await fetch('/api/track-signup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, external_user_id: externalId })
});

// خادمك الخلفي (Node): يحمل سر التوقيع، يوقّع ويُمرّر.
import crypto from 'node:crypto';const KEY_ID = process.env.DZBUILD_PUBLIC_KEY_ID;
const SECRET = process.env.DZBUILD_SIGNING_SECRET;export async function trackSignup({ email, external_user_id }) {
  const nonce = crypto.randomBytes(16).toString('hex');   // 32 محرفًا ست عشريًا صغيرًا
  const ts    = Math.floor(Date.now() / 1000).toString();
  const body  = JSON.stringify({ email, external_user_id, source: 'web', nonce });
  const hash  = crypto.createHash('sha256').update(body).digest('hex');
  const sig   = crypto.createHmac('sha256', SECRET)
    .update(`${KEY_ID}\n${nonce}\n${ts}\n${hash}`).digest('hex');  await fetch('https://api.dzbuild.app/v1/signups', {
    method: 'POST',
    headers: {
      'Authorization':   `DZ-Public ${KEY_ID}`,
      'X-DZ-Timestamp':  ts,
      'X-DZ-Nonce':      nonce,
      'X-DZ-Signature':  sig,
      'Idempotency-Key': nonce,
      'Content-Type':    'application/json'
    },
    body
  });
}

سر التوقيع لا يغادر خادمك أبدًا. معرّف المفتاح العام يمكن لأي أحد فحصه — وهذا بقصد. انظر الاشتراكات للعقد الكامل.

نفق dev محلي للـ webhooks

تحتاج webhooks DZBuild URL HTTPS عام. للاختبار محليًا استعمل tunnel:

# ngrok
ngrok http 3000# Cloudflare Tunnel
cloudflared tunnel --url http://localhost:3000

سجّل URL الـ tunnel كهدف webhook. ولا يمكن تعديل URL الـ webhook بعد تسجيله، فإن تغيّر URL الـ tunnel احذف الـ webhook وسجّل الـ URL الجديد واحفظ السر الجديد الذي يُرجعه التسجيل (ngrok مجاني يغير URL في كل مرة؛ ادفع 8$ شهريًا لـ subdomain ثابت).

سياسة التدوير

دوّر المفاتيح:

ربع سنوي لمفاتيح الإنتاج (ضع تذكير في التقويم)
فورًا إن احتمل أن مفتاحًا تسرّب (التزم بـ git، صورة شاشة، أُرسل في chat)
عند مغادرة عضو فريق إن كان لديه وصول لمدير الأسرار

إجراء التدوير:

أنشئ مفتاحًا جديدًا بـ POST /v1/keys (انظر كيف تحصل على المفتاح). سيرث فئة المفتاح القديم وعَلَم البرنامج التجريبي. ويحتفظ المتجر بـ 3 مفاتيح نشطة كحد أقصى: عند بلوغ الحد يُجيب النداء بـ 400 bad_request "Key limit reached for this store (3 active keys). Revoke unused keys first."، فألغِ مفتاحًا غير مستعمل قبل التدوير.
حدّث مدير الأسرار / متغيرات البيئة إلى المفتاح الجديد.
انشر. وتحقّق من أن المفتاح الجديد قيد الاستعمال: GET /v1/keys يسرد كل مفتاح مع last_used_at الخاص به (أما GET /v1/usage فيعدّ المتجر كله، لا مفتاحًا واحدًا).
بعد تأكيد 24 ساعة من حركة نظيفة على الجديد، ألغِ القديم: DELETE /v1/keys/{old_key_id}.

أخطاء شائعة

الخطأ	ما يحدث	الإصلاح
التزام `.env` في git	المفتاح صار في تاريخ git إلى الأبد؛ دوّره فورًا	`git filter-repo` لا يُصلح forks/clones؛ اعتبره متسربًا
استخدام مفتاح المنصة في كود متصفح	العملاء يقرؤون network tab → يرونه ويسرقونه	انقله إلى back-end / serverless؛ دوّره
Hardcode `dzpk_live_...` في source	نفس الأمر	استعمل env vars؛ دوّر
نفس المفتاح لـ dev وprod	خطأ dev يضرب بيانات prod	أنشئ مفتاحين؛ لا تشارك أبدًا
فقدان سر webhook	لا يمكن التحقق من التسليمات	احذف الـ webhook، سجّل غيره
تسجيل مفتاح API في سجلات التطبيق	مدققون / شاحنو سجلات / كل من له وصول للسجل يراه	redact secrets في إعدادات logger؛ دوّر

قائمة سريعة قبل الإطلاق

[ ] .env في .gitignore (ولم يُلتزَم سهوًا)
[ ] مفتاح الإنتاج اسمه prod ويُستعمل فقط في prod
[ ] مفتاح الـ dev اسمه dev ويُستعمل فقط في dev/staging
[ ] أسرار webhooks في مدير أسرار، ليس في الكود
[ ] رأس Authorization على كل نداء API من خادمك الخلفي
[ ] كود المتصفح لا يرى dzpk_live_* (فقط dzpub_live_* إن استعملت تدفق المفتاح العام)
[ ] نقطة webhook لديك تتحقق من X-DZ-Signature بسر الـ webhook، وتزيل التكرار بـ delivery_id الموجود في الجسم
[ ] لديك تذكير تدوير مفاتيح في تقويمك
[ ] لديك logging لا يلتقط أجسام الطلبات الكاملة (قد تتضمن مفاتيح API في رؤوس العميل)

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

إعداد البيئة و .env