تكامل الولاء (Partner Loyalty API)

المصادقة

مفتاح API لكل فرع — يولّده المالك من لوحة التحكم ← التكاملات (لكل فرع مفتاح وزر تشغيل مستقل). يُرسَل في كل طلب:

Authorization: Bearer <API_KEY>
# أو
x-api-key: <API_KEY>

Base URL

https://sahnqr.com/api/partner

صيغة الكيو آر

SAHNCUPN:<reward_code>

الصيغة

JSON · HTTPS فقط

التدفّق

1. الكاشير يمسح كيو آر العميل ← يستخرج reward_code من SAHNCUPN:<code>.
2. معاينة الخصم عبر /reward (لا يستهلك) — للتحقّق «كم خصم العميل».
3. عند تطبيق الخصم فعلاً على الفاتورة: استهلاك عبر /redeem (لمرة واحدة).
4. عند إتمام بيع: /points لإضافة النقاط تلقائياً (والمرتجع يخصمها).

يرجّع نوع الخصم وقيمته دون استهلاك الكوبون. آمن للاستدعاء أكثر من مرة.

curl -X POST https://sahnqr.com/api/partner/reward \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "reward_code": "AB12CD34" }'

الاستجابة — خصم على مستوى الطلب (type 1):

{
  "code": 200,
  "type": 1,
  "title": "خصم ١٠٪",
  "discount_amount": 10,
  "is_percent": true,
  "require_otp": false,
  "is_discount_taxable": false,
  "customer_name": "Fahad",
  "customer_mobile_number": "+9665XXXXXXXX"
}

مكافأة هدية (غير رقمية) ترجّع 422 — تُستبدل في تطبيق كاشير صحن.

نادِه عند تطبيق الخصم فعلاً. يعلّم الكوبون مستبدَلاً ذرّياً — النداء الثاني يرجّع 409. هذا النداء هو ما يجعل صحن يعرف يقيناً أن الخصم استُخدم.

curl -X POST https://sahnqr.com/api/partner/redeem \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "reward_code": "AB12CD34" }'

{ "code": 200, "description": "Success", "title": "خصم ١٠٪", "discount_amount": 10, "is_percent": true }

بيع مكتمل → إضافة نقاط. مرتجع (event=return) → خصم. العميل يُعرّف بالجوال (يُنشأ تلقائياً لو جديد). نفس الطلب لا يُحتسب مرتين (order_id).

curl -X POST https://sahnqr.com/api/partner/points \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_mobile_number": "05XXXXXXXX",
    "customer_name": "Fahad",
    "amount": 100,
    "event": "earn",
    "order_id": "POS-90ea37ca"
  }'

الاستجابة:

{ "code": 200, "description": "Success", "points": 100, "applied": 100 }

• amount → النقاط = المبلغ × معدّل المطعم. أو أرسل points صراحةً.
• event: earn (افتراضي) أو return (خصم).
• order_id اختياري لكنه مُوصى به لمنع الاحتساب المزدوج.

يرجّع ملف العميل بالجوال: الاسم، الإيميل، المدينة، الحي، النقاط، وعدد الزيارات لكل فرع.

curl -X POST https://sahnqr.com/api/partner/customer \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "customer_mobile_number": "05XXXXXXXX" }'

{
  "code": 200,
  "customer_name": "Fahad",
  "customer_mobile_number": "+9665XXXXXXXX",
  "email": "f@example.com",
  "city": "الخرج",
  "district": "الخالدية",
  "points": 120,
  "stamps": 3,
  "total_visits": 5,
  "visits": [
    { "branch_name": "فرع الخرج", "count": 4 },
    { "branch_name": "فرع العليا", "count": 1 }
  ]
}

رموز الحالة