البحث عن العميل متاح

عند الدفع، ابحث عن حالة ولاء العميل اللحظية ليعرض الكاشير رصيده ومستواه والمكافآت التي يمكنه استردادها الآن وتقدّم أختامه. هذه قراءة صرفة — لا تُغيّر أي شيء أبداً.

GET /api/partner/v1/customers/lookup

مُصادَق بـ X-Api-Key فقط — طلب GET لا يحمل جسماً، فلا يحتاجX-Signature. يُستخرَج التاجر من مفتاحك.

افشل مفتوحاً عند الكاشير

عامِل هذا الاستدعاء على أنه أفضل جهد ممكن: إذا كان بطيئاً أو غير متاح، أتمّ عملية البيع دون معاينة الولاء بدلاً من إعاقة العميل. فحوصات الاسترداد والإرجاع وحدها تفشل مغلقة.

تحديد العميل

مرّر واحداً فقط من مُعامِلات الاستعلام التالية. عدم إرسال أيٍّ منهما، أو إرسالهما معاً، يُنتج 400 INVALID_REQUEST.

المُعامِل	المعنى
`phone`	رقم هاتف بصيغة E.164 يُدخَل عند الكاشير، مثل `+966512345678`.
`customerId`	معرّف عميل قروش (UUID)، يُمسَح من هوية العميل أو من QR المحفظة.

العميل غير المعروف ليس خطأ — يُرجِع 200 معisEnrolled: false وكل الحقول الأخرى null.

الاستجابة

الحقل	النوع	ملاحظات
`isEnrolled`	boolean	`false` تعني عدم وجود ملف لهذا العميل — كل الحقول الأخرى null.
`customerId`	string (UUID) / null	معرّف العميل في قروش.
`externalCustomerId`	string / null	معرّفك لهذا العميل. Null لعميل أصيل في قروش لم يُزامَن من نظامك أبداً.
`phone`	string / null	بصيغة E.164.
`name`	string / null	الاسم المعروض.
`profileStatus`	enum / null	`Active` أو `Imported` (مُستورَد بصمت، لم يسجّل الدخول أبداً).
`currentPointsBalance`	integer / null	رصيد النقاط القابل للاسترداد.
`tierName`	string / null	مستوى الولاء، إن كان المتجر يُشغّل المستويات.
`redeemableRewards`	array / null	المكافآت التي يمكن للعميل استردادها الآن — رصيد كافٍ، نشطة، ضمن مدتها.
`stampProgress`	array / null	تقدّم الأختام لكل بطاقة وأهلية فترة الانتظار.

redeemableRewards[]:

الحقل	النوع	ملاحظات
`rewardId`	string (UUID)	أعِده عند التحقق من استبدال.
`nameAr` / `nameEn`	string	يُعرَض حسب لغة نقطة البيع عندك.
`source`	enum	كيف تُدفَع: `Points` أو `Stamps` أو `Reward`.
`rewardType`	enum	`Product` أو `Service` أو `Coupon`.
`pointsCost`	integer / null	يُعيَّن فقط لمكافآت النقاط.

stampProgress[]:

الحقل	النوع	ملاحظات
`stampCardId`	string (UUID)	البطاقة.
`stampCardName`	string	الاسم المعروض.
`collected` / `total`	integer	التقدّم نحو بطاقة كاملة.
`eligibleForStamp`	boolean	`false` أثناء سريان فترة انتظار لكل زيارة — أخفِ البطاقة بلون باهت.
`cooldownUntil`	string (ISO) / null	متى تصبح البطاقة مؤهلة مجدداً؛ null عندما تكون مؤهلة أصلاً.

سيناريوهات

مُسجَّل

{
  "isEnrolled": true,
  "customerId": "0195d0d0-0000-7000-8000-000000000abc",
  "externalCustomerId": "cust_012345",
  "phone": "+966512345678",
  "name": "Sara Al-Otaibi",
  "profileStatus": "Active",
  "currentPointsBalance": 420,
  "tierName": "Gold",
  "redeemableRewards": [
    {
      "rewardId": "0195d0e0-0000-7000-8000-000000000001",
      "nameAr": "قهوة مجانية",
      "nameEn": "Free coffee",
      "source": "Points",
      "rewardType": "Product",
      "pointsCost": 200
    }
  ],
  "stampProgress": [
    {
      "stampCardId": "0195d0b0-0000-7000-8000-0000000000aa",
      "stampCardName": "Coffee card",
      "collected": 6,
      "total": 10,
      "eligibleForStamp": true,
      "cooldownUntil": null
    }
  ]
}

عميل غير معروف

200 عادية، وليست خطأ.

{
  "isEnrolled": false,
  "customerId": null,
  "externalCustomerId": null,
  "phone": null,
  "name": null,
  "profileStatus": null,
  "currentPointsBalance": null,
  "tierName": null,
  "redeemableRewards": null,
  "stampProgress": null
}

مُستورَد (لم يسجّل الدخول أبداً)

ملف أنشأه قروش بصمت من بيانات CustomerSynced عندك. يكسب من اليوم الأول؛ وprofileStatus يكون Imported.

{
  "isEnrolled": true,
  "externalCustomerId": "cust_012346",
  "phone": "+966512345679",
  "name": "Faisal Al-Harbi",
  "profileStatus": "Imported",
  "currentPointsBalance": 60,
  "tierName": null,
  "redeemableRewards": [],
  "stampProgress": []
}

أصيل في قروش (QR ممسوح)

عميل قروش لم يُزامَن من نظامك أبداً — externalCustomerId يكون null. ابحث عنه بـ customerId من QR هويته.

{
  "isEnrolled": true,
  "customerId": "0195d0d0-0000-7000-8000-000000000abe",
  "externalCustomerId": null,
  "phone": "+966512345680",
  "name": "Noura Al-Qahtani",
  "profileStatus": "Active",
  "currentPointsBalance": 1500,
  "tierName": "Platinum",
  "redeemableRewards": [],
  "stampProgress": []
}

بطاقة أختام في منتصف فترة الانتظار

{
  "stampProgress": [
    {
      "stampCardId": "0195d0b0-0000-7000-8000-0000000000ab",
      "stampCardName": "Lunch card",
      "collected": 3,
      "total": 8,
      "eligibleForStamp": false,
      "cooldownUntil": "2026-07-17T00:00:00Z"
    }
  ]
}

مثال

using System.Net.Http.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://api.quroosh.io/") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

// Identify by E.164 phone OR Quroosh customerId — exactly one.
var customer = await http.GetFromJsonAsync<CustomerLookupResponse>(
    "api/partner/v1/customers/lookup?phone=+966512345678");

if (customer!.IsEnrolled)
    Console.WriteLine($"{customer.Name}: {customer.CurrentPointsBalance} points");

السكيما الكاملة وأداة تجربة مباشرة موجودتان فيمرجع API.