تسجيل دخول التاجر

لغة

neqat Platform

للمطورين

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

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

اقرأ المستندات لوحة تحكم الشريك

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

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

  • واجهة برمجة تطبيقات REST

    العملاء وبطاقات الولاء والطوابع والقسائم - قم بإنشاء البرامج وتشغيل عمليات الولاء اليومية باستخدام JSON في كل مكان.

  • خطافات الويب

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

  • مفاتيح واجهة برمجة التطبيقات

    الرموز المميزة لحاملها مع البادئة lpk_. قم بإنشاء المفاتيح وتدويرها وإبطالها من لوحة تحكم الشريك.

مرجع

وثائق واجهة برمجة التطبيقات

المصادقة ونقاط النهاية وخطافات الويب ومعالجة الأخطاء لـ v1.

ملخص

تتوفر واجهة برمجة تطبيقات Partner في الخطط ذات وصول المطور. يتم تحديد نطاق كل طلب لمؤسستك.

عنوان URL الأساسي

https://neqat.site/api/v1

إصدار v1 · أجسام JSON · UTF-8

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

بداية سريعة

من الصفر إلى أول طلب مصادق عليه في دقائق.

  1. قم بتسجيل الدخول إلى لوحة القيادة الشريكة.
  2. افتح المطور → مفاتيح API وأنشئ مفتاحًا مسمىًا.
  3. انسخ المفتاح على الفور، حيث يتم عرضه مرة واحدة ويتم تخزينه كتجزئة آمنة.
  4. أرسل Authorization: Bearer YOUR_KEY على كل طلب.
  5. اختياري: قم بتكوين خطافات الويب للأحداث في الوقت الفعلي.

المصادقة

تستخدم المفاتيح البادئة lpk_. تعود المفاتيح الملغاة 401. 

# قائمة العملاء
curl -X GET "https://neqat.site/api/v1/customers?per_page=15" \
  -H "Authorization: Bearer lpk_your_secret_key" \
  -H "Accept: application/json"
# نقاط الائتمان من الشراء
curl -X POST "https://neqat.site/api/v1/loyalty-cards/12/transactions" \
  -H "Authorization: Bearer lpk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"customer_email":"alex@example.com","reference":"POS-88421","amount":24.50,"currency":"USD"}'

الطلبات

الرؤوس والعجز ومظاريف الاستجابة.

  • Content-Type — application/json لأجسام POST.
  • Accept — application/json للردود.
  • Idempotency — Idempotency-Key عند إنشاء الطلبات وكتابتها بعد.
  • Pagination — data, meta, links.next.
# غلاف النجاح
{
  "data": { ... },
  "meta": { "request_id": "9f3c2a1e-..." }
}

نقاط النهاية

المسارات المتعلقة بـ https://neqat.site/api/v1

عملاء

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

GET /customers

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

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

طلب مثال

GET https://neqat.site/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://neqat.site/api/v1/customers?page=1",
    "last": "https://neqat.site/api/v1/customers?page=3",
    "prev": null,
    "next": "https://neqat.site/api/v1/customers?page=2"
  }
}
GET /customers/{id}

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

طلب مثال

GET https://neqat.site/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://neqat.site/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://neqat.site/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://neqat.site/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://neqat.site/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://neqat.site/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://neqat.site/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://neqat.site/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://neqat.site/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://neqat.site/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://neqat.site/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://neqat.site/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://neqat.site/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 الموقعة عندما يتفاعل الأعضاء مع برامجك.

# رؤوس التسليم
Content-Type: application/json
X-Loyalty-Event: loyalty.points_earned
X-Loyalty-Timestamp: 1715789400
X-Loyalty-Signature: <hmac-sha256-hex>

التحقق باستخدام HMAC-SHA256(timestamp + "." + raw_body, signing_secret) 

# الحمولة
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "loyalty.points_earned",
  "created_at": "2026-05-16T12:00:00+00:00",
  "data": { ... }
}

أنواع الأحداث

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

أخطاء

كائنات خطأ JSON المتسقة عبر واجهة برمجة التطبيقات.

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": { "email": ["The email field is required."] }
  }
}
HTTP معنى
400 اقتراح غير جيد — فشل التحقق من الصحة أو كان نص JSON مشوهًا.
401 غير مصرح به — مفتاح API مفقود أو غير صالح.
403 مُحرَّم — المفتاح صالح ولكنه غير مسموح به لهذا المورد أو الخطة.
404 لم يتم العثور عليه — المورد غير موجود أو أنه خارج مؤسستك.
429 طلبات كثيرة جدًا — تم تجاوز حد المعدل — أعد المحاولة مع التراجع الأسي.
500 خطأ في الخادم — فشل غير متوقع - اتصل بالدعم إذا استمر.