مرجع API

بدء تبرع عام

يبدأ تبرعًا بعد التحقق من المبلغ والقواعد والحماية؛ ولا يمثل مساهمة مكتملة.

POSThttps://api.sparkglim.net/api/public/donate

نموذج الوصول

نموذج الوصول: وصول عام مع تحقق
التوفر الموثّق: منفذ في المصدر

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

افتح رابط الدفع المعاد؛ ويتحكم SparkGlim Server في الأسعار والوسائل والتحقق والتنفيذ، والعودة مجرد تنقل.

الطلب

الاسم	النوع	التحقق من المدخلات
`campaign_id`مطلوب سجل حملة قائم ضمن حساب الطالب وأي نطاق أضيق لمفتاح الحملة.	`string`	التحقق: UUID.
`amount`مطلوب مبلغ المساهمة أو السحب المطلوب بعملة الحملة أو الحساب؛ ويتحقق الخادم من الصلاحية المالية والشروط النهائية.	`number`	التحقق: 1–1000000؛ بزيادات 0.01 بعملة الحملة.
`donor_country_code`اختياري سياق بلد المتبرع المنفصل عن بلد بيع حملة التبرع وعملتها.	`string`	التحقق: رمز ISO2 بأحرف كبيرة.
`email`اختياري بريد تواصل يستخدمه المسار المهيأ؛ ولا يمنح وحده صلاحية الوصول.	`string`	التحقق: عنوان بريد إلكتروني.
`phone_number`اختياري هاتف المشارك؛ وقد تتطلب وسائل الدفع وقواعد الحملة رقمًا دوليًا صحيحًا.	`string`	التحقق: رقم هاتف صالح عندما تتطلبه القناة.
`donor_name`اختياري اسم عرض العضو أو المساهم؛ ولا يغيّر ملكية الحساب.	`string`	التحقق: بعد حذف المسافات الطرفية.
`anonymous`اختياري يطلب سلوك المساهمة المجهولة القائم؛ ولا ترسل حقول إخفاء متعارضة.	`boolean`	التحقق: يجب ألا يتعارض مع is_anonymous.
`is_anonymous`اختياري يطلب سلوك المساهمة المجهولة القائم؛ ولا ترسل حقول إخفاء متعارضة.	`boolean`	التحقق: يجب ألا يتعارض مع anonymous.
`custom_data`اختياري إجابات تطابق حقول الحملة الفعلية والقيم المطلوبة والخيارات المدعومة.	`object`	التحقق: الحقول المخصصة المهيأة.
`payment_channel`اختياري تفضيل وسيلة اختياري؛ لا تستخدم إلا الوسائل المفعلة لبلد البيع والعملة والتاجر الفعليين.	`enum`	التحقق: الطريقة المهيأة فقط.
`network_code`اختياري اختيار شبكة جوال مهيأ عندما تتطلبه وسيلة الدفع المحددة.	`string`	التحقق: الشبكة المهيأة.
`is_app`اختياري سياق العميل القائم لاختيار تهيئة الويب أو التطبيق؛ ولا يمنح صلاحيات إضافية.	`boolean`	التحقق: سياق العميل.
`web_abuse_context`مطلوب بيانات حماية المتصفح والجهاز القائمة والمطلوبة قبل تهيئة الدفع العام؛ ولا تحل محل تفويض الخادم.	`object`	التحقق: كائن صارم؛ JSON للحقل device_details <=12000 حرف.
`web_abuse_context.device_id`مطلوب إشارة حماية قائمة للمتصفح أو الجهاز يقبلها مخطط حماية الدفع العام الحالي.	`string`	التحقق: 12–160.
`web_abuse_context.device_fingerprint`مطلوب إشارة حماية قائمة للمتصفح أو الجهاز يقبلها مخطط حماية الدفع العام الحالي.	`string`	التحقق: 12–160.
`web_abuse_context.browser_signature`اختياري إشارة حماية قائمة للمتصفح أو الجهاز يقبلها مخطط حماية الدفع العام الحالي.	`string\|null`	التحقق: 12–160.
`web_abuse_context.hardware_signature`اختياري إشارة حماية قائمة للمتصفح أو الجهاز يقبلها مخطط حماية الدفع العام الحالي.	`string\|null`	التحقق: 12–160.
`web_abuse_context.device_details`اختياري إشارة حماية قائمة للمتصفح أو الجهاز يقبلها مخطط حماية الدفع العام الحالي.	`object`	التحقق: كائن JSON.
`web_abuse_context.client_pattern_detected`اختياري إشارة حماية قائمة للمتصفح أو الجهاز يقبلها مخطط حماية الدفع العام الحالي.	`boolean`	التحقق: حماية الجهاز القائمة.
`client_attempt_id`اختياري معرّف عملية ثابت لاستعادة المحاولة القائمة ورفض محاولات الإعادة المختلفة.	`string`	التحقق: هوية عملية ثابتة وموحّدة.
`return_path`اختياري وجهة عودة نسبية على الموقع الحالي الموثق بعد الدفع المركزي.	`string`	التحقق: مسار نسبي من المصدر نفسه؛ دون // أو شرطة مائلة عكسية.

الطلب

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

POST /api/public/donate

http

POST /api/public/donate HTTP/1.1
Host: api.sparkglim.net
Content-Type: application/json

{
  "campaign_id": "11111111-1111-4111-8111-111111111111",
  "amount": 10,
  "anonymous": true,
  "web_abuse_context": {
    "device_id": "<EXISTING_DEVICE_ID>",
    "device_fingerprint": "<EXISTING_DEVICE_FINGERPRINT>"
  },
  "client_attempt_id": "example_stable_attempt_0001"
}

الاستجابة

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

json

{
  "success": true,
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "pending"
  }
}

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

json

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

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

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

الحد الافتراضي: 100 طلب لكل عنوان IP خلال 60 ثانية، مع ضوابط إضافية حسب المورد.

توافق المصدر

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

server/src/api/router.ts
server/src/api/routes/public.ts

نموذج الوصول

الطلب

الطلب

الاستجابة

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

توافق المصدر

تابع التطوير