العملاء

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

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

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

GET /v1/customers

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

المصادقة: أي مفتاح منصة نشِط للمتجر (customers:read ممنوحة افتراضيًا وغير مطبَّقة بشكل منفصل في v1).

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

المعامل	النوع	ملاحظات
limit	int 1–200	الافتراضي 50
cursor	string	غير شفاف
phone	string	تطابق تام، غير حساس لحالة الأحرف
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 غير مطبَّقة بشكل منفصل في v1).

الاستجابة 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":        "Prefers afternoon delivery",
    "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	تعليق خاص بالتاجر يُضبط من لوحة التحكم
fraud_score	دائمًا 0 في v1 — الحقل محجوز ولا يُملأ أبدًا عبر الواجهة البرمجية. ومؤشّر المخاطر الذي تراه في صفحة العملاء بلوحة التحكم غير مكشوف هنا. لا تبنِ منطق مكافحة احتيال على هذا الحقل.
is_banned	يُضبط عند حظر العميل من لوحة التحكم. عمليات الدفع في واجهة المتجر وفي صفحات الهبوط ترفض العملاء المحظورين — لكن POST /v1/orders لا تفحص قائمة الحظر، فطلبات الواجهة البرمجية تمرّ للعملاء المحظورين. تحقّق من is_banned بنفسك قبل الإرسال.
إشارات الجهاز/الهوية	لا تُكشف عبر الواجهة البرمجية لأسباب خصوصية

GET /v1/customers/{id}/orders

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

المصادقة: أي مفتاح منصة نشِط للمتجر (customers:read غير مطبَّقة بشكل منفصل في v1).

يُفحص معرّف العميل من حيث الملكية أولًا، لذا فالمعرّف المجهول أو العائد لمتجر آخر يُرجع 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 — الحقول مطابقة لملخص قائمة الطلبات. للحصول على جسم الطلب الكامل اطلب /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. اقرأ القائمة ورتّبها من جانب العميل؛ مجموعة البيانات صغيرة (متجر نموذجي يملك أقل من 5000 عميل نشط). أو اطلب /v1/orders?since=... وجمّع حسب customer_id.

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

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