الموارد الأساسية

الكسب

أبلغ عن الطلبات المدفوعة والملغاة والمستردة ليكسب العملاء.

الإبلاغ عن طلب

POST /v1/orders

أرسل كل طلب عند دفعه، ومرة أخرى إذا أُلغي أو استُرد. الطلب المدفوع يكسب على بطاقة العميل (ويُنشأ العميل إن كان جديدًا)، والإلغاء والاسترداد يستعيدان ما كسبه. المرجع يجعل كل نتيجة تحدث مرة واحدة، فإعادة المحاولة آمنة دائمًا. الطلب الذي لا يكسب شيئًا ليس خطأً: يعيد 200 مع النتيجة «skipped» وسببها.

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

reference string مطلوب: معرّف طلبك، فريد في مساحة العمل. أحرف وأرقام و . _ - / #
status string مطلوب: paid أو void أو refunded.
total number مطلوب: المبلغ المدفوع شاملًا الضريبة بعد الخصومات. مطلوب عند الدفع.
customer.phone string مطلوب: رقم جوال العميل. مطلوب عند الدفع.
customer.country_code string: رمز الاتصال الدولي بدون + (966) عندما يكون الرقم محليًا.
customer.name string: يُستخدم عندما يكون العميل جديدًا.
branch_id uuid: الفرع الذي سُجّل فيه الطلب (انظر الفروع).
occurred_at datetime: وقت دفع الطلب بصيغة ISO 8601. الافتراضي الآن.
currency string: رمز ISO 4217. الافتراضي عملة مساحة العمل.
items[] array: بنود الطلب: product_id و name و quantity و unit_price.
subtotal number: قبل الخصومات، لسجلاتك.
discount number: الخصم المطبق، لسجلاتك.

curl -X POST 'https://api.loyvue.com/v1/orders' \
  -H 'Authorization: Bearer rf_live_YOUR_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "POS-10045",
    "status": "paid",
    "occurred_at": "2026-10-18T13:45:00+03:00",
    "branch_id": "9f1c2d4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "customer": {
        "phone": "557331312",
        "country_code": "966",
        "name": "Sara Ahmed"
    },
    "items": [
        {
            "product_id": "9f1c2d4e-5b6c-4d7e-8f90-a1b2c3d4e5f6",
            "name": "Latte",
            "quantity": 2,
            "unit_price": 18
        }
    ],
    "subtotal": 36,
    "discount": 0,
    "total": 36
}'

const response = await fetch('https://api.loyvue.com/v1/orders', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer rf_live_YOUR_KEY',
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "reference": "POS-10045",
      "status": "paid",
      "occurred_at": "2026-10-18T13:45:00+03:00",
      "branch_id": "9f1c2d4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "customer": {
          "phone": "557331312",
          "country_code": "966",
          "name": "Sara Ahmed"
      },
      "items": [
          {
              "product_id": "9f1c2d4e-5b6c-4d7e-8f90-a1b2c3d4e5f6",
              "name": "Latte",
              "quantity": 2,
              "unit_price": 18
          }
      ],
      "subtotal": 36,
      "discount": 0,
      "total": 36
  }),
});

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

$response = Http::withToken('rf_live_YOUR_KEY')
    ->acceptJson()
    ->post('https://api.loyvue.com/v1/orders', [
        'reference' => 'POS-10045',
        'status' => 'paid',
        'occurred_at' => '2026-10-18T13:45:00+03:00',
        'branch_id' => '9f1c2d4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f',
        'customer' => [
            'phone' => '557331312',
            'country_code' => '966',
            'name' => 'Sara Ahmed',
        ],
        'items' => [
            [
                'product_id' => '9f1c2d4e-5b6c-4d7e-8f90-a1b2c3d4e5f6',
                'name' => 'Latte',
                'quantity' => 2,
                'unit_price' => 18,
            ],
        ],
        'subtotal' => 36,
        'discount' => 0,
        'total' => 36,
    ]);

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

الاستجابة 201

{
    "ok": true,
    "data": {
        "outcome": "awarded",
        "reason": null,
        "reference": "POS-10045",
        "transaction": {
            "id": "9f1c2d4e-7d8e-4f90-a1b2-c3d4e5f6a7b8",
            "type": "purchase",
            "amount": 36,
            "currency": "SAR",
            "points": 36,
            "visits": 1
        },
        "customer_id": "9f1c2d4e-3c4d-4e5f-9a0b-1c2d3e4f5a6b",
        "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
        }
    }
}