الموارد الأساسية
الاستبدال
تحقق من رمز المكافأة الذي يعرضه العميل ثم استبدله.
التحقق من رمز مكافأة
POST
/v1/rewards/check
يُدخل الكاشير الرمز الذي يعرضه العميل، فتعرف ما تمنحه المكافأة قبل تطبيقها دون أن يتغير شيء بعد. لا يعمل الرمز إلا مع رقم جوال العميل نفسه.
معاملات الجسم
-
reward_codestring مطلوب - الرمز الذي يعرضه العميل، مثل RW-7KQ2XP.
-
phonestring مطلوب - رقم جوال العميل.
-
country_codestring - رمز الاتصال الدولي بدون + (966) عندما يكون الرقم محليًا.
curl -X POST 'https://api.loyvue.com/v1/rewards/check' \
-H 'Authorization: Bearer rf_live_YOUR_KEY' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"reward_code": "RW-7KQ2XP",
"phone": "557331312",
"country_code": "966"
}'const response = await fetch('https://api.loyvue.com/v1/rewards/check', {
method: 'POST',
headers: {
Authorization: 'Bearer rf_live_YOUR_KEY',
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"reward_code": "RW-7KQ2XP",
"phone": "557331312",
"country_code": "966"
}),
});
const { ok, data } = await response.json();$response = Http::withToken('rf_live_YOUR_KEY')
->acceptJson()
->post('https://api.loyvue.com/v1/rewards/check', [
'reward_code' => 'RW-7KQ2XP',
'phone' => '557331312',
'country_code' => '966',
]);
$data = $response->json('data');
الاستجابة
200
{
"ok": true,
"data": {
"code": "RW-7KQ2XP",
"status": "available",
"name": "Free latte",
"description": null,
"type": "product",
"allowed_products": {
"quantity": 1,
"products_list": [
"9f1c2d4e-5b6c-4d7e-8f90-a1b2c3d4e5f6"
]
},
"customer_id": "9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b",
"earned_at": "2026-10-11T09:30:00+03:00",
"expires_at": null,
"redeemed_at": null
}
}استبدال مكافأة
POST
/v1/rewards/redeem
استدعِه بعد تسوية الطلب الذي طُبّقت عليه المكافأة. مكافأة النقاط تخصم ثمنها من البطاقة. الاستدعاء الثاني يعيد 422 reward_unavailable، فلا يمكن أن تُستبدل المكافأة مرتين.
معاملات الجسم
-
reward_codestring مطلوب - الرمز الذي يعرضه العميل.
-
phonestring مطلوب - رقم جوال العميل.
-
country_codestring - رمز الاتصال الدولي بدون + (966) عندما يكون الرقم محليًا.
-
branch_iduuid - الفرع الذي استُبدلت فيه.
-
order_referencestring - معرّف طلبك، يُحفظ مع الاستبدال.
curl -X POST 'https://api.loyvue.com/v1/rewards/redeem' \
-H 'Authorization: Bearer rf_live_YOUR_KEY' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"reward_code": "RW-7KQ2XP",
"phone": "557331312",
"country_code": "966",
"branch_id": "9f1c2d4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"order_reference": "POS-10046"
}'const response = await fetch('https://api.loyvue.com/v1/rewards/redeem', {
method: 'POST',
headers: {
Authorization: 'Bearer rf_live_YOUR_KEY',
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"reward_code": "RW-7KQ2XP",
"phone": "557331312",
"country_code": "966",
"branch_id": "9f1c2d4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"order_reference": "POS-10046"
}),
});
const { ok, data } = await response.json();$response = Http::withToken('rf_live_YOUR_KEY')
->acceptJson()
->post('https://api.loyvue.com/v1/rewards/redeem', [
'reward_code' => 'RW-7KQ2XP',
'phone' => '557331312',
'country_code' => '966',
'branch_id' => '9f1c2d4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f',
'order_reference' => 'POS-10046',
]);
$data = $response->json('data');
الاستجابة
200
{
"ok": true,
"message": "تم استبدال المكافأة.",
"data": {
"reward": {
"code": "RW-7KQ2XP",
"status": "redeemed",
"name": "Free latte",
"description": null,
"type": "product",
"allowed_products": {
"quantity": 1,
"products_list": [
"9f1c2d4e-5b6c-4d7e-8f90-a1b2c3d4e5f6"
]
},
"customer_id": "9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b",
"earned_at": "2026-10-11T09:30:00+03:00",
"expires_at": null,
"redeemed_at": "2026-10-18T14:02:11+03:00"
},
"card": {
"id": "9f1c2d4e-6c7d-4e8f-9a01-b2c3d4e5f6a7",
"serial_number": "NS-48213",
"status": "active",
"program": {
"id": "9f1c2d4e-2b3c-4d5e-8f90-1a2b3c4d5e6f",
"name": "Coffee Points",
"type": "point"
},
"visits": 5,
"points": 236,
"spent": 236
}
}
}