العملاء

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

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

GET /v1/customers

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

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

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

المعامل	النوع	ملاحظات
limit	int 1–200	الافتراضي 50
cursor	string	غير شفاف
phone	string	تطابق تام
email	string	تطابق تام (حساس لحالة الأحرف في v1)

الطلب

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 يبقيان متزامنين تلقائيًا كلما تغيّرت حالة طلبات العميل؛ لا تحتاج إلى إعادة حسابهما.

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":        "Prefers afternoon delivery",
    "total_orders": 3,
    "total_spent":  4500,
    "fraud_score":  10,
    "is_banned":    false,
    "created_at":   "2026-03-17 15:18:13",
    "updated_at":   "2026-04-15 12:01:08"
  }
}

الحقل	ملاحظات
notes	تعليق خاص بالتاجر يُضبط من لوحة التحكم
fraud_score	0-100 قياس داخلي (مرتفع = مشبوه)
is_banned	يُضبط إن قمت بحظره من اللوحة. الطلبات المستقبلية تُرفض تلقائيًا.
device_fingerprint	لا يُكشف عبر الواجهة البرمجية لأسباب خصوصية

GET /v1/customers/{id}/orders

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

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

الطلب

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-AD3C", "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.

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

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