العملاء

العملاء هم المستخدمون النهائيون الذين قدّموا طلبات على واجهة متجرك. يُنشَؤون تلقائيًا عند أول checkout — لا يوجد تدفّق تسجيل عام في v1. كل عميل مقيّد بمتجر واحد: نفس رقم الهاتف على متجرين مختلفين يُنشئ صفّي customer منفصلين.

إزالة التكرار: عندما يصل checkout جديد، نطابق على المتجر + رقم الهاتف. إن كان العميل موجودًا، نُحدّث بريده/عنوانه/ولايته ونعيد استخدام سجلّه؛ وإلا نُنشئ سجلًا جديدًا. البريد الإلكتروني لا يُستخدم للإزالة — تاريخيًا يحصل التجار على طلبات مجهولة كثيرة بدون بريد.

عندما يُنشأ العميل عبر POST /v1/orders، تُخزَّن سلسلة customer.name كاملةً في first_name ويُترك last_name فارغًا — فتقسيم الاسم الأول/الأخير الظاهر في الأمثلة أدناه لا يحدث أبدًا للسجلات المُنشأة عبر الواجهة البرمجية. أما العميل الموجود مسبقًا والمطابَق برقم الهاتف فيُستبدَل فيه first_name فقط، ويُترك أي last_name موجود دون تغيير. قسّمه من جانب العميل إن احتجت ذلك.

GET /v1/customers

قائمة عملاء متجرك. ترقيم بالمؤشّر.

المصادقة: مفتاح منصة بصلاحية customers:read، وتحملها المفاتيح الجديدة افتراضيًا. بدونها يُرجع النداء 403 forbidden.

معاملات الاستعلام

المعامل	النوع	ملاحظات
limit	int 1–200	الافتراضي 50
cursor	string	غير شفاف
phone	string	تطابق تام مع الرقم المخزَّن. طلبات واجهة المتجر وصفحات الهبوط تخزّن أرقام الهاتف المحمول الجزائرية بصيغة 0XXXXXXXXX؛ أما أرقام POST /v1/orders والطلبات اليدوية من لوحة التحكم فتُخزَّن كما أُرسلت، فجرّب الصيغة الأخرى إن لم تجد تطابقًا
email	string	تطابق تام، غير حساس لحالة الأحرف

لا توجد في v1 فلاتر للتاريخ ولا بحث نصّي حر ولا فرز ولا فلتر is_banned؛ والنتائج دائمًا مرتّبة بالأحدث معرّفًا أولًا.

الطلب

curl 'https://api.dzbuild.app/v1/customers?limit=20' \
  -H "Authorization: Bearer $DZ_KEY"

الاستجابة 200

{
  "data": {
    "items": [
      {
        "id":           5578,
        "first_name":   "John",
        "last_name":    "Doe",
        "phone":        "0555000000",
        "email":        null,
        "wilaya_id":    16,
        "commune":      "Bab Ezzouar",
        "total_orders": 3,
        "total_spent":  4500,
        "is_banned":    false,
        "created_at":   "2026-03-17 15:18:13",
        "updated_at":   "2026-04-15 12:01:08"
      }
    ],
    "next_cursor": "NDk=",
    "has_more": true
  }
}

total_orders وtotal_spent عدّادات قديمة وليست تجميعات حيّة

لا تُزاد إلا عند إنشاء طلب من صفحة هبوط أو طلب يدوي من لوحة التحكم. ولا تُعدَّل أبدًا عند تغيّر الحالة (الطلب الملغى يبقى محسوبًا)، والطلبات المُنشأة عبر واجهة المتجر أو عبر POST /v1/orders لا تُحدّثها إطلاقًا. لا تستخدمها لتقارير الإيرادات — جمّع بنفسك من GET /v1/orders (أو /v1/customers/{id}/orders).

GET /v1/customers/{id}

تفاصيل كاملة.

المصادقة: مفتاح منصة بصلاحية customers:read.

الاستجابة 200

{
  "data": {
    "id":           5578,
    "first_name":   "John",
    "last_name":    "Doe",
    "phone":        "0555000000",
    "email":        "[email protected]",
    "wilaya_id":    16,
    "commune":      "Bab Ezzouar",
    "address":      "12 Rue X",
    "notes":        null,
    "total_orders": 3,
    "total_spent":  4500,
    "fraud_score":  0,
    "is_banned":    false,
    "created_at":   "2026-03-17 15:18:13",
    "updated_at":   "2026-04-15 12:01:08"
  }
}

الحقل	ملاحظات
notes	محجوز. لا لوحة التحكم ولا الواجهة البرمجية تكتبه، فتوقّع null لدى أغلب العملاء.
fraud_score	دائمًا 0 في v1 — الحقل محجوز ولا يُملأ أبدًا عبر الواجهة البرمجية. ومؤشّر المخاطر الذي تراه في صفحة العملاء بلوحة التحكم غير مكشوف هنا. لا تبنِ منطق مكافحة احتيال على هذا الحقل.
is_banned	يُضبط عند حظر العميل من لوحة التحكم. عمليات الدفع في واجهة المتجر وفي صفحات الهبوط ترفض العملاء المحظورين — لكن POST /v1/orders لا تفحص قائمة الحظر، فطلبات الواجهة البرمجية تمرّ للعملاء المحظورين. تحقّق من is_banned بنفسك قبل الإرسال.
إشارات الجهاز/الهوية	لا تُكشف عبر الواجهة البرمجية لأسباب خصوصية

GET /v1/customers/{id}/orders

طلبات العميل، ترقيم بالمؤشّر، الأحدث أولًا.

المصادقة: مفتاح منصة بصلاحية customers:read.

يُفحص معرّف العميل من حيث الملكية أولًا، لذا فالمعرّف المجهول أو العائد لمتجر آخر يُرجع 404 not_found وليس قائمة فارغة.

الطلب

curl 'https://api.dzbuild.app/v1/customers/5578/orders?limit=10' \
  -H "Authorization: Bearer $DZ_KEY"

الاستجابة 200

{
  "data": {
    "items": [
      { "id": 6894, "order_number": "ORD-13-20260317-AD3C91F7", "status": "confirmed",
        "payment_status": "pending", "total": 1000, "created_at": "2026-03-17 15:18:13" }
    ],
    "next_cursor": null,
    "has_more": false
  }
}

هذا مجموعة فرعية من /v1/orders مفلترة بـ customer_id، بملخص أقصر: id وorder_number وstatus وpayment_status وtotal وcreated_at فقط. للحصول على جسم الطلب الكامل اطلب /v1/orders/{id}.

أنماط شائعة

"ابحث عن عميل برقم الهاتف ثم اعرض طلباته"

PHONE="0555000000"
CUST=$(curl -sS "https://api.dzbuild.app/v1/customers?phone=$PHONE&limit=1" \
  -H "Authorization: Bearer $DZ_KEY" | jq -r '.data.items[0].id')

[ -z "$CUST" ] && { echo "no customer"; exit 1; }

curl -sS "https://api.dzbuild.app/v1/customers/$CUST/orders" \
  -H "Authorization: Bearer $DZ_KEY"

"أعلى 10 منفقين هذا الشهر"

لا يوجد فلتر فرز-بالإنفاق في v1، وtotal_spent عدّاد قديم (انظر التحذير أعلاه). اطلب /v1/orders?since=... واجمع total لكل customer_phone: ملخص القائمة يحمل رقم الهاتف لا معرّف العميل. استبعد الطلبات cancelled وreturned إن أردت المبيعات التي بقيت فقط.

ملاحظات الخصوصية

• الواجهة البرمجية لا تكشف أبدًا بصمات الأجهزة ولا أي رابط هوية بين المتاجر.
• بريد العميل وهاتفه بيانات شخصية — احذر تسجيلها.
• طلبات حق المحو المستقبلية (نمط RGPD) يجب أن تمر عبر لوحة التحكم/الدعم؛ الواجهة ستحصل على نقطة DELETE /v1/customers/{id} في إصدار قادم بقواعد cascade صريحة.