الانتقال إلى الوثائق
SparkGlimDeveloper
مركز التكامل بمساعدة الذكاء الاصطناعي
SparkGlimSparkGlim للمطوّرين
ابحث في جميع الوثائق

جرّب موضوعًا بلغتك أو مسار API دقيقًا.

    التنقل في الوثائق

    مرجع API

    بدء دفع الأصوات

    يتحقق من الحملة والمرشح ويهيئ دفع الأصوات القائم ويعيد العملية عند المحاولة؛ ويسجل الخادم الأصوات المكتملة.

    POSThttps://api.sparkglim.net/api/white-label/v1/votes/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_-].

    الطلب

    الاسمالنوعالتحقق من المدخلات
    campaignIdمطلوب

    سجل حملة قائم ضمن حساب الطالب وأي نطاق أضيق لمفتاح الحملة.

    		stringالتحقق: UUID.
    participantIdمطلوب

    المرشح المختار ضمن هذه الحملة؛ ويتحقق الخادم من الموافقة وقواعدها.

    		stringالتحقق: UUID.
    voteCountمطلوب

    عدد الأصوات للمرشح؛ يحدد الخادم السعر الصحيح ويسجل الأصوات المكتملة.

    		integerالتحقق: 1–100.
    phoneNumberمطلوب

    هاتف المشارك؛ وقد تتطلب وسائل الدفع وقواعد الحملة رقمًا دوليًا صحيحًا.

    		stringالتحقق: 8–32.
    callbackUrlمطلوب

    وجهة العودة المقبولة وفق عقد التكامل؛ ولا تثبت نجاح الدفع.

    		stringالتحقق: URL.
    emailاختياري

    بريد تواصل يستخدمه المسار المهيأ؛ ولا يمنح وحده صلاحية الوصول.

    		string|nullالتحقق: عنوان بريد إلكتروني.
    channelاختياري

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

    		enumالتحقق: web | ussd | telegram | whatsapp.
    payment_channelاختياري

    تفضيل وسيلة اختياري؛ لا تستخدم إلا الوسائل المفعلة لبلد البيع والعملة والتاجر الفعليين.

    		enumالتحقق: طريقة دفع مفعّلة.
    metadataاختياري

    بيانات JSON إضافية يقبلها المخطط؛ ولا تتجاوز التفويض أو الأسعار أو الملكية.

    		objectالتحقق: كائن JSON.

    الطلب

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

    POST /api/white-label/v1/votes/initialize
    http
    POST /api/white-label/v1/votes/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

{
  "campaignId": "11111111-1111-4111-8111-111111111111",
  "participantId": "33333333-3333-4333-8333-333333333333",
  "voteCount": 1,
  "phoneNumber": "+233200000000",
  "callbackUrl": "https://events.example.com/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

    تابع التطوير