مزامنة العملاء · LoyVue مطورو LoyVue

البحث عن العملاء

GET /v1/customers

ابحث عن عميل برقم جواله الدقيق، أو بجزء من الاسم أو الرقم. النتائج مقسمة على صفحات.

معاملات الاستعلام

phone string: رقم الجوال الدقيق، دوليًا (+966557331312) أو محليًا مع country_code.
country_code string: رمز الاتصال الدولي بدون + (966) عندما يكون الرقم محليًا.
search string: جزء من الاسم أو الرقم.
page integer: رقم الصفحة، يبدأ من 1.
per_page integer: عدد النتائج في الصفحة، حتى 100 (الافتراضي 20).

curl -X GET 'https://api.loyvue.com/v1/customers?phone=557331312&country_code=966' \
  -H 'Authorization: Bearer rf_live_YOUR_KEY' \
  -H 'Accept: application/json'

const response = await fetch('https://api.loyvue.com/v1/customers?phone=557331312&country_code=966', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer rf_live_YOUR_KEY',
    Accept: 'application/json',
  },
});

const { ok, data } = await response.json();

$response = Http::withToken('rf_live_YOUR_KEY')
    ->acceptJson()
    ->get('https://api.loyvue.com/v1/customers', [
        'phone' => '557331312',
        'country_code' => '966',
    ]);

$data = $response->json('data');

الاستجابة 200

{
    "ok": true,
    "data": [
        {
            "id": "9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b",
            "name": "Sara Ahmed",
            "phone": "+966 55 733 1312",
            "email": "[email protected]",
            "birthday": null,
            "status": "active",
            "cards": [
                {
                    "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
                }
            ],
            "created_at": "2026-09-02T10:12:00+03:00",
            "last_visit_at": "2026-10-18T13:45:00+03:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1
    }
}

جلب عميل

GET /v1/customers/{id}

عميل واحد مع بطاقاته والمكافآت التي تنتظر الاستبدال.

معاملات المسار

id uuid مطلوب: معرّف العميل.

curl -X GET 'https://api.loyvue.com/v1/customers/9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b' \
  -H 'Authorization: Bearer rf_live_YOUR_KEY' \
  -H 'Accept: application/json'

const response = await fetch('https://api.loyvue.com/v1/customers/9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer rf_live_YOUR_KEY',
    Accept: 'application/json',
  },
});

const { ok, data } = await response.json();

$response = Http::withToken('rf_live_YOUR_KEY')
    ->acceptJson()
    ->get('https://api.loyvue.com/v1/customers/9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b');

$data = $response->json('data');

الاستجابة 200

{
    "ok": true,
    "data": {
        "id": "9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b",
        "name": "Sara Ahmed",
        "phone": "+966 55 733 1312",
        "email": "[email protected]",
        "birthday": null,
        "status": "active",
        "cards": [
            {
                "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
            }
        ],
        "created_at": "2026-09-02T10:12:00+03:00",
        "last_visit_at": "2026-10-18T13:45:00+03:00",
        "rewards": [
            {
                "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/customers

يسجّل العميل في البرنامج الذي يكسب عليه مفتاحك. رقم الجوال هو الهوية: الرقم المسجل مسبقًا يعيد 200 مع ذلك العميل بدل الخطأ، لذا يمكنك استدعاؤه قبل كل طلب. العميل الجديد يعيد 201.

معاملات الجسم

name string مطلوب: الاسم الكامل.
phone string مطلوب: رقم الجوال، دوليًا أو محليًا.
country_code string: رمز الاتصال الدولي بدون + (966) عندما يكون الرقم محليًا.
email string: البريد الإلكتروني.
birthday date: YYYY-MM-DD.

curl -X POST 'https://api.loyvue.com/v1/customers' \
  -H 'Authorization: Bearer rf_live_YOUR_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Sara Ahmed",
    "phone": "557331312",
    "country_code": "966",
    "email": "[email protected]"
}'

const response = await fetch('https://api.loyvue.com/v1/customers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer rf_live_YOUR_KEY',
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "Sara Ahmed",
      "phone": "557331312",
      "country_code": "966",
      "email": "[email protected]"
  }),
});

const { ok, data } = await response.json();

$response = Http::withToken('rf_live_YOUR_KEY')
    ->acceptJson()
    ->post('https://api.loyvue.com/v1/customers', [
        'name' => 'Sara Ahmed',
        'phone' => '557331312',
        'country_code' => '966',
        'email' => '[email protected]',
    ]);

$data = $response->json('data');

الاستجابة 201

{
    "ok": true,
    "message": "تم إنشاء العميل.",
    "data": {
        "id": "9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b",
        "name": "Sara Ahmed",
        "phone": "+966 55 733 1312",
        "email": "[email protected]",
        "birthday": null,
        "status": "active",
        "cards": [
            {
                "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
            }
        ],
        "created_at": "2026-09-02T10:12:00+03:00",
        "last_visit_at": "2026-10-18T13:45:00+03:00"
    }
}

تحديث عميل

PUT /v1/customers/{id}

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

معاملات المسار

id uuid مطلوب: معرّف العميل.

معاملات الجسم

name string: الاسم الكامل.
email string: البريد الإلكتروني.
birthday date: YYYY-MM-DD.

curl -X PUT 'https://api.loyvue.com/v1/customers/9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b' \
  -H 'Authorization: Bearer rf_live_YOUR_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]"
}'

const response = await fetch('https://api.loyvue.com/v1/customers/9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer rf_live_YOUR_KEY',
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "email": "[email protected]"
  }),
});

const { ok, data } = await response.json();

$response = Http::withToken('rf_live_YOUR_KEY')
    ->acceptJson()
    ->put('https://api.loyvue.com/v1/customers/9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b', [
        'email' => '[email protected]',
    ]);

$data = $response->json('data');

الاستجابة 200

{
    "ok": true,
    "message": "تم تحديث العميل.",
    "data": {
        "id": "9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b",
        "name": "Sara Ahmed",
        "phone": "+966 55 733 1312",
        "email": "[email protected]",
        "birthday": null,
        "status": "active",
        "cards": [
            {
                "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
            }
        ],
        "created_at": "2026-09-02T10:12:00+03:00",
        "last_visit_at": "2026-10-18T13:45:00+03:00"
    }
}