# العملاء

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

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

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

## `GET /v1/customers`[​](#get-v1customers "رابط مباشر إلى get-v1customers")

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

**المصادقة:** مفتاح منصة بصلاحية `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[​](#الاستجابة-200 "رابط مباشر إلى الاستجابة 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}`[​](#get-v1customersid "رابط مباشر إلى get-v1customersid")

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

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

### الاستجابة 200[​](#الاستجابة-200-1 "رابط مباشر إلى الاستجابة 200")

```
{

  "data": {

    "id":           5578,

    "first_name":   "John",

    "last_name":    "Doe",

    "phone":        "0555000000",

    "email":        "john@example.com",

    "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`[​](#get-v1customersidorders "رابط مباشر إلى get-v1customersidorders")

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

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

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

### الطلب[​](#الطلب-1 "رابط مباشر إلى الطلب")

```
curl 'https://api.dzbuild.app/v1/customers/5578/orders?limit=10' \

  -H "Authorization: Bearer $DZ_KEY"
```

### الاستجابة 200[​](#الاستجابة-200-2 "رابط مباشر إلى الاستجابة 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 منفقين هذا الشهر"[​](#أعلى-10-منفقين-هذا-الشهر "رابط مباشر إلى \"أعلى 10 منفقين هذا الشهر\"")

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

## ملاحظات الخصوصية[​](#ملاحظات-الخصوصية "رابط مباشر إلى ملاحظات الخصوصية")

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