العملاء هم المستخدمون النهائيون الذين قدّموا طلبات على واجهة متجرك. يُنشَؤون تلقائيًا عند أول 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 صريحة.

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