إنتقل إلى المحتوى الرئيسي

للموزّعين

إن كنت تبني متاجر للعملاء — وكالات، فريلانسرز، شركات تنفيذ، مشغّلو منصات سوق — فإن DZBuild API مصمّم ليكون عمودك العملياتي.

هذا الدليل لك إن كان أيٌّ مما يلي ينطبق:

  • تدير 5+ متاجر DZBuild لعملاء مختلفين.
  • تُفوتر العملاء لكل طلب أو شهريًا وتحتاج إشارة استخدام موثوقة.
  • تبني ثيمات مخصصة أو واجهات مخصصة نيابة عن العملاء.
  • تبيع DZBuild كطبقة علامة بيضاء ("MyAgency Commerce, مدعومة من DZBuild").
  • تريد سكربتة عمليات بالجملة: استيراد منتجات، تحديث أسعار، تأكيد طلبات.

كيف يستخدم الموزّعون الـ API فعلًا​

إعداد موزّع نموذجي:

                                ┌─────────────────────────┐
                                │ back-office /           │
                                │ لوحة وكالتك              │
                                │ (كودك، واجهتك)           │
                                └──────────┬──────────────┘
                                           │  Bearer dzpk_live_…
                                           ▼
                            ┌─────────────────────────────┐
                            │  api.dzbuild.app/v1/*       │
                            └──────────┬──────────────────┘
                                       ▼
                           ┌──────────┬─────────┬──────────┐
                           │ متجر A  │ متجر B │ متجر C  │   ← العملاء الذين تديرهم
                           └──────────┴─────────┴──────────┘

كل عميل له متجر DZBuild خاص (حساب التاجر، خطته، طلباته). تحمل مفتاح API لكل متجر وتنسّق كل شيء — إعداد، تخصيص، تقارير — من لوحة وكالتك.

نموذج المفاتيح للموزّعين​

لا يوجد نوع مفتاح "موزّع" خاص. كل موزّع يعمل بـ مفتاح منصة واحد لكل متجر عميل. إما:

أ) كل عميل ينشئ المفتاح ويشاركه معك (مستحسن للعلاقات على مسافة)​

العميل يدخل لوحته في DZBuild، يُنشئ مفتاحًا، ويعطيك السر. تُخزّن أسرار العملاء في back-office لديك مشفّرة. كل عملية ضد العميل X تستخدم مفتاح العميل X.

الإيجابيات: موافقة واضحة، العميل يملك المفتاح ويستطيع إلغاءه. السلبيات: احتكاك في الإعداد (يجب أن يقوم العميل بخطوة).

ب) لديك اتفاق تجاري جزائري شامل مع DZBuild ونحن نُنشئ المفاتيح لك​

للوكالات التي تدير 20+ متجرًا، تواصل معنا. يمكننا إصدار "مظلة وكالة" تُتيح لك إنشاء مفاتيح برمجيًا مع كل عميل جديد. (ميزة Pro+ / Enterprise.)

الإيجابيات: تأهيل بدون احتكاك. السلبيات: تتطلب عقدًا مكتوبًا؛ أنت مسؤول تشغيليًا عن أي إساءة على هذه المفاتيح.

استيراد منتجات بالجملة​

تبني كتالوجًا لعميل؟ استخدم حلقة CSV → API:

import requests, csv, uuid, os

KEY = os.environ['DZ_KEY_CLIENT_X']
HEADERS = {
    'Authorization': f'Bearer {KEY}',
    'Content-Type':  'application/json',
}

with open('products.csv') as f:
    for row in csv.DictReader(f):
        body = {
            'name':           row['name'],
            'price':          float(row['price']),
            'compare_price':  float(row['compare_price']) if row['compare_price'] else None,
            'sku':            row['sku'],
            'description':    row['description'],
            'stock_quantity': int(row['stock']),
            'track_stock':    True,
            'status':         'active',
        }
        r = requests.post(
            'https://api.dzbuild.app/v1/products',
            headers={**HEADERS, 'Idempotency-Key': str(uuid.uuid4())},
            json=body,
        )
        if r.status_code == 201:
            print(f"OK {row['sku']} → id {r.json()['data']['id']}")
        else:
            print(f"FAIL {row['sku']}: {r.text}")

نصائح:

  • استخدم مفتاح Idempotency حتمي (مثل import-{client}-{sku}-{run}) فتقفز الإعادات على الصفوف المستوردة.
  • حد pro_plus 5000 طلب/دقيقة — كافٍ لاستيراد ~1000 منتج في 30 ثانية.
  • رفع الصور يمر عبر اللوحة حاليًا؛ الـ API سيدعم R2 PUT presigned في v1.1.

عمليات طلبات بالجملة​

تأكيد كل الطلبات pending لعميل واحد​

KEY="$(cat /etc/secrets/client-x.key)"
# 1. اسرد pending
curl -sS 'https://api.dzbuild.app/v1/orders?status=pending&limit=200' \
  -H "Authorization: Bearer $KEY" \
| jq -r '.data.items[].id' \
| while read OID; do
    # 2. أكّد كل واحد
    curl -sS -X PATCH "https://api.dzbuild.app/v1/orders/$OID" \
      -H "Authorization: Bearer $KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: confirm-$OID" \
      -d '{"status":"confirmed"}'
  done

تقرير إيرادات يومي عبر كل العملاء​

clients = json.load(open('clients.json'))  # [{name, key}, ...]
today = date.today().isoformat() + 'T00:00:00Z'

for c in clients:
    orders = requests.get(
        f'https://api.dzbuild.app/v1/orders?since={today}&limit=200',
        headers={'Authorization': f'Bearer {c["key"]}'},
    ).json()['data']['items']
    revenue = sum(o['total'] for o in orders if o['status'] == 'delivered')
    print(f"{c['name']}: {len(orders)} طلبات، {revenue} دج")

العلامة البيضاء (White-labeling)​

تريد أن تبدو متاجرك كأنها علامتك، لا DZBuild. الـ API يُمكّن ذلك:

  • ابنِ الواجهة بنفسك بأي ستاك/علامة (انظر الثيمات والواجهات المخصصة).
  • استخدم نطاقك الخاص (shop.yourbrand.com) — وجّهه إلى واجهتك المخصصة، وواجهتك تتحدث مع DZBuild عبر API.
  • لوحة التاجر في dzbuild.com/dashboard تبقى بعلامة DZBuild — هناك تؤكد الطلبات. عملاؤك النهائيون لا يرون علامة DZBuild أبدًا.

للعلامة البيضاء الكاملة بما فيها لوحة تاجر مخصصة، انظر خطط Enterprise.

Webhooks للموزّعين​

سجّل webhook واحد لكل متجر عميل يشير إلى back-office وكالتك:

curl -X POST 'https://api.dzbuild.app/v1/webhooks' \
  -H "Authorization: Bearer $CLIENT_X_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url":    "https://api.youragency.com/dz-hooks?store=client-x",
    "events": ["order.created","order.confirmed","order.shipped","order.delivered","order.cancelled"]
  }'

استعمل المعامل ?store=client-x فيمكن لنقطة واحدة معالجة كل العملاء. تحقّق من التوقيع بسر العميل ليتأكد أن DZBuild هي المنادية.

الحسابات متعددة المتاجر​

بعض العملاء يديرون عدة متاجر في حساب DZBuild واحد (ميزة Multi-store). كل متجر له مفتاحه — مستقلة. سمّها بوضوح في مدير الأسرار:

DZ_KEY_CLIENT_X_BRAND_A=dzpk_live_...
DZ_KEY_CLIENT_X_BRAND_B=dzpk_live_...

الخطط — ما توصي به​

حجم العميلالخطة المستحسنةالسبب
0–30 طلب/شهرFreeتحقق من الفكرة قبل الالتزام
30–500 طلب/شهرProيُزيل حدود الطلبات + يفتح API (طبقة pro)
500–2000 طلب/شهرPro+حد API يقفز إلى 5000 طلب/دقيقة — لازم لمزامنات بالجملة
2000+ / multi-brandEnterpriseحد بلا قيود، عقد مخصص، دعم أولوي

الـ API نفسه ضمن Pro فما فوق. متاجر Free لا يمكنها إنشاء مفاتيح API.

فوترة عملائك​

الـ API يُعطيك إشارات استخدام دقيقة لتفوتر بثقة:

  • GET /v1/usage — نداءات الشهر الحالي مقسمة حسب مجموعة النقاط
  • GET /v1/usage/history — آخر 12 شهرًا
  • GET /v1/orders?status=delivered&since=... — لنماذج عمولة لكل طلب

معظم الموزّعين يفوترون:

  • رسوم شهرية ثابتة لاستضافة الواجهة + إعادة بيع رخصة DZBuild
  • % عمولة على الطلبات المُسلَّمة (اقرأ من ?status=delivered)
  • أو اشتراك مدمج (مثل "10000 دج/شهر للكل")

اختر النموذج الذي يتوقعه سوقك.

نصائح تشغيلية​

  • بيئة لكل عميل. أسرار dev في dev. أسرار prod في prod. لا تشارك أبدًا.
  • استخدم Idempotency-Keys حتمية لأي حلقة إعادة (خصوصًا الاستيراد بالجملة / التأكيد بالجملة).
  • خزّن قراءات المنتجات. الحافة تُخزّن 30 ثانية لكن يمكنك إضافة طبقة 5 دقائق فوقها — المنتجات نادرًا ما تتغير لحظيًا.
  • حدّ نفسك. لا تقفز إلى 5000 طلب/دقيقة عند توفّرها — اترك هامشًا لحركة التاجر.
  • اضبط تنبيهات Telegram عندك على 429 rate_limited و 5xx وفشل تسليم webhook.
  • تدقيق ربع سنوي: دوّر مفاتيح المتاجر التي لا تديرها بعد. استعمل DELETE /v1/keys/{key_id}.

مرجع​