مرجع API

إنشاء حملة

ينشئ حملة ضمن المنظمة المعتمدة ببيانات موثقة وملكية المنشئ؛ ولا يعني إنشاء المسودة نشرها.

POSThttps://api.sparkglim.net/api/white-label/v1/campaigns

نموذج الوصول

نموذج الوصول: توقيع المنظمة HMAC من الخادم
الصلاحية المطلوبة: campaigns: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 كاملة واختيارية ومقيّدة بالنطاق.

الطلب

الاسم	النوع	التحقق من المدخلات
`title`مطلوب عنوان الحملة العام الذي يقدمه المنظم المصرح به.	`string`	التحقق: 3–255.
`description`مطلوب وصف يقدمه المنظم لشرح الحملة أو نوع التذكرة.	`string`	التحقق: 10–5000.
`campaign_type`مطلوب يحدد خدمة التذاكر أو التصويت أو التبرعات؛ ولا يمنح وحدة غير مصرح بها.	`enum`	التحقق: ticketing \| voting \| donation.
`start_date`مطلوب توقيت بداية الحملة بصيغة ISO.	`string`	التحقق: تاريخ ووقت بصيغة ISO.
`end_date`مطلوب توقيت إغلاق الحملة بصيغة ISO.	`string`	التحقق: تاريخ ووقت بصيغة ISO.
`country_code`اختياري رمز بلد البيع المهيأ؛ ويتحقق الخادم من أهلية الحساب والسوق.	`string`	التحقق: ISO2.
`currency_code`اختياري عملة الحملة المسموحة؛ ولا يجيز اختيار بلد عملة جديدة.	`string`	التحقق: ISO3.
`slug`اختياري معرّف مناسب للرابط للحملة القائمة أو المقال المنشور.	`string`	التحقق: مخطط المعرّف النصي المهيأ.
`status`اختياري الحالة المدعومة المطلوبة؛ وتتحكم قواعد الموافقة في النشر والوصول.	`enum`	التحقق: draft \| pending_approval \| approved \| rejected \| archived.
`vote_price`اختياري قيمة تهيئة المنتج بعملة الحملة أو وحدة سعتها الخاصة.	`number`	التحقق: >=0.
`donation_goal`اختياري قيمة تهيئة المنتج بعملة الحملة أو وحدة سعتها الخاصة.	`number`	التحقق: >=0.
`ticket_price`اختياري قيمة تهيئة المنتج بعملة الحملة أو وحدة سعتها الخاصة.	`number`	التحقق: >=0.
`ticket_capacity`اختياري قيمة تهيئة المنتج بعملة الحملة أو وحدة سعتها الخاصة.	`integer`	التحقق: >0.
`image_url`اختياري رابط صورة المورد المقدمة؛ استخدم وسائط عامة مصرحًا بها.	`string\|null`	التحقق: URL.
`banner_url`اختياري رابط غلاف الحملة المقدم من المنظم.	`string\|null`	التحقق: URL.
`category`اختياري فئة الحملة المهيأة أو فئة إعدادات معتمدة حسب المورد.	`string\|null`	التحقق: <=120.
`location`اختياري موقع الحملة العام أو مرشح الموقع؛ وهو منفصل عن بلد البيع المالي.	`string\|null`	التحقق: <=255.
`event_date`اختياري موعد الحدث، وهو منفصل عن فترة بيع الحملة.	`string\|null`	التحقق: تاريخ ووقت بصيغة ISO.
`verification_required`اختياري يحدد متطلب التحقق المدعوم دون تجاوز فحوص أهلية الخادم.	`boolean`	التحقق: القيمة الافتراضية: true.
`metadata`اختياري بيانات JSON إضافية يقبلها المخطط؛ ولا تتجاوز التفويض أو الأسعار أو الملكية.	`object`	التحقق: كائن JSON.

الطلب

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

POST /api/white-label/v1/campaigns

http

POST /api/white-label/v1/campaigns 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>
Content-Type: application/json

{
  "title": "Example campaign",
  "description": "An illustrative campaign description.",
  "campaign_type": "ticketing",
  "start_date": "2030-06-01T09:00:00.000Z",
  "end_date": "2030-06-02T18:00:00.000Z"
}

الاستجابة

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

json

{
  "success": true,
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "draft"
  },
  "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

نموذج الوصول

الترويسات

الطلب

الطلب

الاستجابة

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

توافق المصدر

تابع التطوير