مرجع API

بدء دفع التذاكر

يتحقق من صلاحية التذاكر والنوع والمشتري ثم ينشئ الدفع المركزي أو يستعيده بإيصال مرتبط بالنطاق.

POSThttps://api.sparkglim.net/api/white-label/v1/payments/initialize

نموذج الوصول

نموذج الوصول: توقيع المنظمة HMAC من الخادم
الصلاحية المطلوبة: payments:write
التوفر الموثّق: منفذ في المصدر

التوفر موثق من المصدر وليس ضمانًا لتشغيل الإنتاج.

يبقى التوقيع الخاص في خادمك؛ تستخدم واجهة الإصدار 1 تنسيق توقيع v2 ولا تصبح واجهة إصدار 2.

الترويسات

الاسم	النوع	التحقق من المدخلات
`x-white-label-domain`مطلوب اسم الموقع الموثق الذي يحدد حساب المنظمة المعتمد ويربط الطلب به.	`string`	التحقق: اسم مضيف HTTPS موثّق.
`x-white-label-key-id`مطلوب المعرّف المستخرج من قيمة المفتاح الخاص الواحدة؛ لا ترسل السر في هذه الترويسة.	`string`	التحقق: المعرّف الداخلي للمفتاح الخاص الصادر.
`x-white-label-signature-version`مطلوب يحدد تنسيق التوقيع المرتبط بالنطاق؛ وتبقى مسارات الواجهة في الإصدار 1.	`string`	التحقق: 2.
`x-white-label-timestamp`مطلوب توقيت توقيع الطلب بالمللي ثانية؛ يقارنه الخادم بساعته لرفض الطلبات القديمة.	`string`	التحقق: توقيت بالمللي ثانية من 13 رقمًا؛ ضمن خمس دقائق.
`x-white-label-nonce`مطلوب قيمة توقيع عشوائية جديدة يسجلها الخادم لمنع إعادة تشغيل الطلب الموقّع.	`string`	التحقق: قيمة جديدة: 16–128 [A-Za-z0-9_-].
`x-white-label-signature`مطلوب توقيع HMAC-SHA256 للنطاق ومفتاح عدم التكرار واعتماد الحملة والتوقيت وnonce والطريقة والمسار والاستعلام المرتب وبصمة الجسم الدقيقة.	`string`	التحقق: HMAC-SHA256 بالنظام الست عشري وبأحرف صغيرة.
`x-white-label-campaign-key`اختياري مفتاح حملة كامل اختياري يضيّق الطلب الخاص إلى الحملة المصرح بها نفسها.	`string`	التحقق: قيمة keyId:secret كاملة واختيارية ومقيّدة بالنطاق.
`X-Idempotency-Key`مطلوب هوية ثابتة للعملية تعاد في المحاولات بنفس التفاصيل؛ ويرفض تغيير التفاصيل تحت المفتاح نفسه.	`string`	التحقق: 16–128 [A-Za-z0-9_-].

الطلب

الاسم	النوع	التحقق من المدخلات
`campaign_id`مطلوب سجل حملة قائم ضمن حساب الطالب وأي نطاق أضيق لمفتاح الحملة.	`string`	التحقق: UUID.
`ticket_id`مطلوب نوع التذكرة المختار التابع للحملة المحددة؛ يتحقق الخادم من الحالة والسعة والسعر.	`string`	التحقق: UUID.
`quantity`مطلوب عدد التذاكر المطلوبة؛ ويفرض الخادم المخزون وحدود الشراء للفرد.	`integer`	التحقق: 1–100.
`phone_number`مطلوب هاتف المشارك؛ وقد تتطلب وسائل الدفع وقواعد الحملة رقمًا دوليًا صحيحًا.	`string`	التحقق: رقم هاتف صالح وغير فارغ.
`email`اختياري بريد تواصل يستخدمه المسار المهيأ؛ ولا يمنح وحده صلاحية الوصول.	`string`	التحقق: عنوان بريد إلكتروني.
`discount_code`اختياري اعتماد خصم أو دعوة قائم وخاص بالحملة يعيد الخادم التحقق منه قبل الشراء.	`string`	التحقق: قيمة غير فارغة بعد حذف المسافات الطرفية.
`invite_code`اختياري اعتماد خصم أو دعوة قائم وخاص بالحملة يعيد الخادم التحقق منه قبل الشراء.	`string`	التحقق: قيمة غير فارغة بعد حذف المسافات الطرفية.
`luggage_quantity`اختياري كمية أمتعة لحدث يدعم فعلًا خيار الأمتعة المهيأ.	`integer`	التحقق: >=0.
`attendee_information`اختياري إجابات تطابق حقول الحملة الفعلية والقيم المطلوبة والخيارات المدعومة.	`object`	التحقق: قيم نصية تطابق الحقول المهيأة.
`payment_channel`اختياري تفضيل وسيلة اختياري؛ لا تستخدم إلا الوسائل المفعلة لبلد البيع والعملة والتاجر الفعليين.	`enum`	التحقق: card \| mobile_money \| apple_pay \| bank_transfer \| crypto؛ يتحكم الخادم في الإتاحة.
`network_code`اختياري اختيار شبكة جوال مهيأ عندما تتطلبه وسيلة الدفع المحددة.	`string`	التحقق: الشبكة المهيأة.
`is_app`اختياري سياق العميل القائم لاختيار تهيئة الويب أو التطبيق؛ ولا يمنح صلاحيات إضافية.	`boolean`	التحقق: سياق العميل.
`return_path`اختياري وجهة عودة نسبية على الموقع الحالي الموثق بعد الدفع المركزي.	`string`	التحقق: مسار نسبي على النطاق الموثّق نفسه.
`clientIp`اختياري عنوان IP الأصلي المقدم من خادم مصرح لاستخدامه في ضوابط الإساءة القائمة.	`string`	التحقق: عنوان IP صالح.

الطلب

تصف الأمثلة العقد ولا تُنفذ. استخدم سجلات اختبار مصرحًا بها، ولا تلصق أسرارًا حقيقية في هذه الصفحات.

POST /api/white-label/v1/payments/initialize

http

POST /api/white-label/v1/payments/initialize HTTP/1.1
Host: api.sparkglim.net
x-white-label-domain: events.example.com
x-white-label-key-id: <ISSUED_KEY_ID>
x-white-label-signature-version: 2
x-white-label-timestamp: <FRESH_MILLISECONDS>
x-white-label-nonce: <FRESH_SIGNING_NONCE>
x-white-label-signature: <SERVER_GENERATED_SIGNATURE>
X-Idempotency-Key: example_stable_operation_0001
Content-Type: application/json

{
  "campaign_id": "11111111-1111-4111-8111-111111111111",
  "ticket_id": "22222222-2222-4222-8222-222222222222",
  "quantity": 1,
  "phone_number": "+233200000000",
  "return_path": "/payment-return"
}

الاستجابة

استجابة النجاح · HTTP 200

json

{
  "success": true,
  "data": {
    "authorization_url": "https://checkout.sparkglim.net/gh/<SERVER_REFERENCE>",
    "reference": "<SERVER_REFERENCE>"
  },
  "requestId": "wlapi_example"
}

استجابة الخطأ · HTTP 400

json

{
  "success": false,
  "error": "<ERROR_MESSAGE>",
  "requestId": "wlapi_example"
}

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

الحدود وإعادة المحاولة

للمنظمات: 120 طلبًا لكل مفتاح و300 لكل IP في النافذة؛ التزم بـ Retry-After وترويسات X-RateLimit.

توافق المصدر

تتطلب العمليات المصرح بها اختبارًا خاصًا بالحساب.

server/src/api/router.ts
server/src/api/routes/white-label.ts
server/src/white-label/auth.ts
server/src/white-label/schemas.ts
server/src/white-label/organization-service.ts
server/src/white-label/service.ts

نموذج الوصول

الترويسات

الطلب

الطلب

الاستجابة

الحدود وإعادة المحاولة

توافق المصدر

تابع التطوير