للمطوّرين

بناء على لدينا واجهة برمجة تطبيقات الشريك

اربط الولاء بنقاط البيع أو تطبيق الجوال أو الخادم لديك. REST للقراءة والكتابة، وWebhooks لأحداث الولاء الفورية.

كل ما تحتاجه للتكامل

متوفر في خطط التاجر مع وصول المطور. كل حركة المرور هي JSON عبر HTTPS.

عنوان URL الأساسي: https://nizk.ai/api/v1
إصدار: v1
المصادقة: Bearer lpk_…

بداية سريعة

أنشئ مفتاح API من لوحة الشريك، ثم استخدمه كـ bearer token مع أي نقطة نهاية.

curl https://nizk.ai/api/v1/loyalty-cards \
  -H "Authorization: Bearer lpk_your_key_here" \
  -H "Accept: application/json"

المصادقة

المفاتيح مرتبطة بشريك واحد ومشفّرة عند التخزين — ولا يظهر بعد الإنشاء سوى بدايتها. يمكنك إلغاء أي مفتاح من اللوحة في أي وقت.

الطلبات

كل استجابة تحمل meta.request_id. القوائم مقسّمة بصفحات عبر ?page= و ?per_page= (بحد أقصى 100).

قم بإنشاء بطاقات الولاء، وبطاقات الأختام، والقسائم باستخدام POST، أو قم بإدارتها في لوحة تحكم الشريك. استخدم المسارات المتداخلة لتسجيل الأعضاء ونقاط الائتمان وإصدار الأختام واسترداد القسائم.

نقاط النهاية

عملاء

ابحث عن العملاء المؤهلين لبرامجك وأنشئهم.

GET/customers

قائمة العملاء

يدعم ?page= و ?per_page= (بحد أقصى 100) و ?search= (الاسم أو البريد الإلكتروني أو الهاتف).

الطلب

GET https://nizk.ai/api/v1/customers?search=alex&per_page=15

الاستجابة

{
  "data": [
    {
      "id": 1042,
      "name": "Alex Rivera",
      "email": "alex@example.com",
      "phone": "+15551234567",
      "created_at": "2026-04-02T14:30:00+00:00"
    }
  ],
  "meta": {
    "request_id": "9f3c2a1e-8b4d-4e1a-9c2d-1a2b3c4d5e6f",
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 42
  },
  "links": {
    "first": "https://nizk.ai/api/v1/customers?page=1",
    "last": "https://nizk.ai/api/v1/customers?page=3",
    "prev": null,
    "next": "https://nizk.ai/api/v1/customers?page=2"
  }
}

GET/customers/{id}

استرداد العميل

الطلب

GET https://nizk.ai/api/v1/customers/1042

الاستجابة

{
  "data": {
    "id": 1042,
    "name": "Alex Rivera",
    "email": "alex@example.com",
    "phone": "+15551234567",
    "created_at": "2026-04-02T14:30:00+00:00"
  },
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

POST/customers

إنشاء أو إرجاع عميل حالي

إذا كان البريد الإلكتروني موجودًا بالفعل، فسيتم إرجاع ملف التعريف الموجود باستخدام HTTP 200.

الطلب

POST https://nizk.ai/api/v1/customers

{
  "email": "alex@example.com",
  "name": "Alex Rivera",
  "phone": "+15551234567"
}

الاستجابة

{
  "data": {
    "id": 1042,
    "name": "Alex Rivera",
    "email": "alex@example.com",
    "phone": "+15551234567",
    "created_at": "2026-05-16T10:00:00+00:00"
  },
  "meta": {
    "request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}

بطاقات الولاء

إنشاء البطاقات وإدراجها وتسجيل العملاء وترحيل معاملات النقاط.

GET/loyalty-cards

قائمة بطاقات الولاء

الطلب

GET https://nizk.ai/api/v1/loyalty-cards

الاستجابة

{
  "data": [
    {
      "id": 12,
      "name": "Insider Points",
      "card_identifier": "RIVERSIDE-INSIDER",
      "is_active": true,
      "earn_spend_amount": "10.00",
      "earn_points": 1,
      "earn_currency": "USD",
      "initial_bonus_points": 50,
      "expiry_date": "2027-12-31"
    }
  ],
  "meta": {
    "request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
  }
}

POST/loyalty-cards

إنشاء بطاقة الولاء

احذف Card_identifier لإنشاء رمز المحفظة تلقائيًا. يتطلب معرف موقع الشريك من حسابك.

الطلب

POST https://nizk.ai/api/v1/loyalty-cards

{
  "name": "Insider Points",
  "partner_location_id": 2,
  "date_issued": "2026-05-16",
  "earn_spend_amount": 10,
  "earn_points": 1,
  "earn_currency": "USD",
  "initial_bonus_points": 50,
  "is_active": true
}

الاستجابة

{
  "data": {
    "id": 13,
    "name": "Insider Points",
    "card_identifier": "042-118-307-591",
    "is_active": true,
    "earn_spend_amount": "10.00",
    "earn_points": 1,
    "earn_currency": "USD",
    "initial_bonus_points": 50,
    "expiry_date": null
  },
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

GET/loyalty-cards/{id}

استرجاع بطاقة الولاء

الطلب

GET https://nizk.ai/api/v1/loyalty-cards/12

الاستجابة

{
  "data": {
    "id": 12,
    "name": "Insider Points",
    "card_identifier": "RIVERSIDE-INSIDER",
    "is_active": true,
    "earn_spend_amount": "10.00",
    "earn_points": 1,
    "earn_currency": "USD",
    "initial_bonus_points": 50,
    "expiry_date": "2027-12-31"
  },
  "meta": {
    "request_id": "d4e5f6a7-b8c9-0123-def0-234567890123"
  }
}

POST/loyalty-cards/{id}/enrollments

تسجيل العميل على البطاقة

يطبق نقاط المكافأة الأولية للبطاقة عند تكوينها.

الطلب

POST https://nizk.ai/api/v1/loyalty-cards/12/enrollments

{
  "customer_email": "alex@example.com"
}

الاستجابة

{
  "data": {
    "enrollment": {
      "id": 88,
      "customer_id": 1042,
      "loyalty_card_id": 12,
      "created_at": "2026-05-16T10:05:00+00:00"
    },
    "initial_bonus_transactions": [
      {
        "id": 501,
        "type": "bonus",
        "customer_id": 1042,
        "loyalty_card_id": 12,
        "points_delta": 50,
        "points_balance_after": 50,
        "purchase_reference": null,
        "occurred_at": "2026-05-16T10:05:00+00:00"
      }
    ]
  },
  "meta": {
    "request_id": "e5f6a7b8-c9d0-1234-ef01-345678901234"
  }
}

POST/loyalty-cards/{id}/transactions

نقاط الائتمان من عملية شراء أو ضبط الرصيد

أرسل المبلغ + العملة لقواعد الربح المستندة إلى الشراء، أو أرسل النقاط وحدها لإجراء التعديل اليدوي.

الطلب

POST https://nizk.ai/api/v1/loyalty-cards/12/transactions

{
  "customer_email": "alex@example.com",
  "reference": "POS-88421",
  "amount": 24.50,
  "currency": "USD",
  "notes": "Counter sale"
}

الاستجابة

{
  "data": {
    "id": 502,
    "type": "earn",
    "customer_id": 1042,
    "loyalty_card_id": 12,
    "points_delta": 2,
    "points_balance_after": 52,
    "purchase_reference": "POS-88421",
    "occurred_at": "2026-05-16T10:12:00+00:00"
  },
  "meta": {
    "request_id": "f6a7b8c9-d0e1-2345-f012-456789012345"
  }
}

بطاقات الأختام

قم بإنشاء بطاقات الأختام وإدراجها، ثم قم بإصدار الأختام بعد عملية شراء مؤهلة.

GET/stamp-cards

قائمة بطاقات الأختام

الطلب

GET https://nizk.ai/api/v1/stamp-cards

الاستجابة

{
  "data": [
    {
      "id": 7,
      "name": "Coffee Club",
      "is_active": true,
      "stamps_required_for_reward": 10,
      "stamps_per_purchase": 1,
      "valid_from": "2026-01-01",
      "valid_until": "2026-12-31"
    }
  ],
  "meta": {
    "request_id": "a7b8c9d0-e1f2-3456-0123-567890123456"
  }
}

POST/stamp-cards

إنشاء بطاقة ختم

الطلب

POST https://nizk.ai/api/v1/stamp-cards

{
  "name": "Coffee Club",
  "partner_location_id": 2,
  "valid_from": "2026-01-01",
  "valid_until": "2026-12-31",
  "stamps_required_for_reward": 10,
  "stamps_per_purchase": 1,
  "reward_title": "Free coffee",
  "is_active": true
}

الاستجابة

{
  "data": {
    "id": 8,
    "name": "Coffee Club",
    "is_active": true,
    "stamps_required_for_reward": 10,
    "stamps_per_purchase": 1,
    "valid_from": "2026-01-01",
    "valid_until": "2026-12-31"
  },
  "meta": {
    "request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}

POST/stamp-cards/{id}/stamps

إصدار الأختام للعميل

الطلب

POST https://nizk.ai/api/v1/stamp-cards/7/stamps

{
  "customer_id": 1042,
  "reference": "POS-88422",
  "amount": 5.50,
  "currency": "USD",
  "notes": "Latte purchase"
}

الاستجابة

{
  "data": [
    {
      "id": 301,
      "type": "earn",
      "customer_id": 1042,
      "stamp_card_id": 7,
      "stamps_delta": 1,
      "stamps_balance_after": 4,
      "purchase_reference": "POS-88422",
      "occurred_at": "2026-05-16T10:15:00+00:00"
    }
  ],
  "meta": {
    "request_id": "b8c9d0e1-f2a3-4567-1234-678901234567"
  }
}

قسائم

أنشئ القسائم وأدرجها، ثم استبدلها بالعميل عند الخروج.

GET/vouchers

قائمة القسائم

الطلب

GET https://nizk.ai/api/v1/vouchers

الاستجابة

{
  "data": [
    {
      "id": 3,
      "name": "Spring Savings",
      "voucher_code": "SPRING20",
      "is_active": true,
      "discount_type": "percent",
      "discount_value": "20.00",
      "valid_from": "2026-03-01",
      "valid_until": "2026-05-31"
    }
  ],
  "meta": {
    "request_id": "c9d0e1f2-a3b4-5678-2345-789012345678"
  }
}

POST/vouchers

إنشاء قسيمة

يجب أن يكون رمز القسيمة فريدًا داخل مؤسستك (أحرف وأرقام وشرطات وشرطات سفلية).

الطلب

POST https://nizk.ai/api/v1/vouchers

{
  "name": "Spring Savings",
  "partner_location_id": 2,
  "voucher_code": "SPRING20",
  "valid_from": "2026-03-01",
  "valid_until": "2026-05-31",
  "discount_type": "percent",
  "discount_value": 20,
  "is_active": true
}

الاستجابة

{
  "data": {
    "id": 4,
    "name": "Spring Savings",
    "voucher_code": "SPRING20",
    "is_active": true,
    "discount_type": "percent",
    "discount_value": "20.00",
    "valid_from": "2026-03-01",
    "valid_until": "2026-05-31"
  },
  "meta": {
    "request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
  }
}

POST/vouchers/{id}/redeem

استبدال قسيمة لأحد العملاء

الطلب

POST https://nizk.ai/api/v1/vouchers/3/redeem

{
  "customer_email": "alex@example.com",
  "order_amount": 45.00,
  "order_reference": "POS-88423",
  "partner_location_id": 2,
  "notes": "In-store checkout"
}

الاستجابة

{
  "data": {
    "id": 19,
    "voucher_id": 3,
    "customer_id": 1042,
    "voucher_code": "SPRING20",
    "order_amount": "45.00",
    "discount_amount": "9.00",
    "order_reference": "POS-88423",
    "redeemed_at": "2026-05-16T10:18:00+00:00"
  },
  "meta": {
    "request_id": "d0e1f2a3-b4c5-6789-3456-890123456789"
  }
}

خطافات الويب

عمليات تسليم HTTPS الموقعة عندما يربح الأعضاء نقاطًا أو يجمعون الأختام أو يستردون العروض.

customer.created
تم إنشاء العميل
يتم ربط ملف تعريف العميل الجديد بمؤسستك.
customer.updated
تم تحديث العميل
تغيير ملف تعريف العميل أو تفاصيل التسجيل.
loyalty.enrolled
تم تسجيل بطاقة الولاء
يقوم العميل بالتسجيل في بطاقة الولاء.
loyalty.points_earned
النقاط المكتسبة
يتم إضافة النقاط من عملية شراء أو مكافأة.
loyalty.points_redeemed
تم استبدال النقاط
يتم إنفاق النقاط على المكافأة أو الاسترداد.
loyalty.reward_claimed
تم المطالبة بالمكافأة
يطالب العميل بمكافأة الولاء.
stamp.issued
تم إصدار الأختام
تتم إضافة ختم إلى بطاقة ختم العميل.
stamp.reward_fulfilled
تم استيفاء مكافأة الأختام
يتم وضع علامة استيفاء على مكافأة بطاقة الأختام.
voucher.redeemed
تم استرداد القسيمة
يتم استرداد القسيمة في مكان ما.
referral.completed
اكتملت الإحالة
تم الانتهاء من معلم برنامج الإحالة.

أخطاء

الرمز	العنوان	الوصف
400	اقتراح غير جيد	فشل التحقق من الصحة أو كان نص JSON مشوهًا.
401	غير مصرح به	مفتاح API مفقود أو غير صالح.
403	مُحرَّم	المفتاح صالح ولكنه غير مسموح به لهذا المورد أو الخطة.
404	لم يتم العثور عليه	المورد غير موجود أو أنه خارج مؤسستك.
429	طلبات كثيرة جدًا	تم تجاوز حد المعدل — أعد المحاولة مع التراجع الأسي.
500	خطأ في الخادم	فشل غير متوقع - اتصل بالدعم إذا استمر.