دليل مطوري Whats360 VCash API: الهندسة الكاملة لأتمتة المحافظ الإلكترونية، وأوامر USSD، ورسائل SMS برمجياً

البنية التحتية لمنظومة VCash وتحويل هواتف الأندرويد إلى سيرفر مالي متصل

تعتمد الغالبية الساحقة من عمليات الدفع الرقمي والتجارة الإلكترونية في الشرق الأوسط ومصر تحديداً على محافظ شبكات المحمول، حيث تجري مئات الآلاف من المعاملات اليومية خارج القنوات المصرفية الكلاسيكية. وعلى الرغم من انتشار محافظ مثل فودافون كاش، أورنج موني، إي آند كاش، ووي باي، ظلت عمليات الربط البرمجي لهذه المنظومات تمثل عقبة تقنية مستحيلة أمام المطورين بسبب غياب واجهات برمجية بنكية مباشرة وميسرة لأصحاب المشروعات المتوسطة والصغيرة. كان البديل المتاح هو المراجعة اليدوية المرهقة للشاشات، مطابقة رسائل التحويل الورقية، أو تعيين فرق عمل مخصصة لمتابعة كل إشعار بنكي، وهو ما يسبب تأخيراً كارثياً في دورة حياة المبيعات ويعرض الأعمال لمخاطر الاحتيال وتكرار استخدام إيصالات التحويل الواحدة.

من هنا انطلقت الهندسة المعمارية لمنظومة VCash Gateway داخل منصة Whats360 لتوفير حل جذري يعيد ابتكار آلية معالجة المدفوعات. يعمل النظام كطبقة وسيطة تحول الهاتف الذكي المزود بنظام أندرويد وشريحة الاتصال إلى سيرفر حوسبة طرفية (Edge Computing Node) متصل بالسحابة عبر قنوات ويب سوكت مشفرة وتقنيات الرسائل اللحظية. بمجرد تنصيب تطبيق البوابة الخفيف على الهاتف، يتحول هذا الجهاز المادي إلى بوابة دفع وسحب واستعلام مؤتمتة بنسبة 100% تتلقى استدعاءات الـ REST API من خوادمك السحابية وتقوم بترجمتها في أجزاء من الثانية إلى نبضات برمجية تتحكم في عتاد المودم الداخلي للهاتف، وقراءة إشعارات الرسائل، وإطلاق أوامر الشبكات دون الحاجة للتعامل مع أي شاشات باليد.

يوفر هذا النموذج للمؤسسات والشركات استقلالية تشغيلية مطلقة؛ حيث تحتفظ بأموالك مباشرة داخل محفظتك الشخصية أو التجارية المسجلة باسم شركتك دون وجود وسيط مالي يحتجز مستحقاتك لفترات تسوية طويلة (Rolling Reserves)، مع خفض عمولات التحصيل إلى الصفر تقريباً مقارنة بنسب بوابات الدفع العالمية والمحلية التي تقتطع ما بين 2.5% إلى 4% من كل عملية بيع. وإلى جانب الحلول المالية المباشرة، يمكن تعزيز هذه البنية بأدوات التحصيل التكميلية المتخصصة عبر منصات مثل EGCash لتنويع قنوات الدفع المصرفي المتوازي.

المحددات التقنية وبروتوكول التوثيق والتهيئة الأمنية

تعتمد بوابة VCash API على أعلى معايير الحماية والتشفير المعتمدة في البيئات المصرفية السحابية لضمان عدم تعرض الأجهزة أو البيانات المالية الحساسة لأي اختراق أو تلاعب برمجي. تم تصميم كل مسار ليتعامل مع مدخلات معيارية بصيغة JSON، مع فرض قيود صارمة على طبقة النقل عبر استخدام بروتوكول TLS 1.3 حصرياً ورفض أي طلبات اتصال تأتي عبر روابط غير مشفرة أو عناوين IP مكشوفة.

العنوان الأساسي الموحد وإدارة جلسات الاتصال

كافة الاستدعاءات البرمجية الموجهة للبوابة عبر جميع المسارات تخاطب عنواناً أساسياً موحداً وثابتاً:

https://whats360.live

يضمن هذا العنوان الموحد استقرار نقاط الاتصال البرمجية (Endpoints Stability)، حيث تعمل سحابة Whats360 كطبقة توزيع أحمال جغرافية (Global Load Balancer) تضمن استجابة الخوادم في فترات ذروة المبيعات والحملات التسويقية الضخمة دون أي هبوط في الأداء أو تأخر في معالجة طلبات التحقق المالي.

ترويسة التوثيق الإلزامية ونموذج Bearer Token

يتعين على خادمك تمرير مفتاح التوكن السري في كل استدعاء برمجي داخل ترويسة الطلب بصيغة Bearer Token. يُعد وجود هذا التوكن شرطاً أساسياً لا يمكن تجاوزه، وبدونه لن تتمكن بوابة الحماية من مطابقة حسابك مع الأجهزة المسجلة.

Authorization: Bearer WHATS360_API_TOKEN
Content-Type: application/json
Accept: application/json

في حال إرسال أي طلب يفتقر إلى هذا الترويس، أو عند كتابة التوكن دون كلمة Bearer تليها مسافة واحدة، أو في حالة استخدام مفتاح غير صالح، ستقوم بوابة الحماية برفض الطلب على الفور وإعادة كود الحالة 401 Unauthorized دون استهلاك أي وقت من المعالج.

إدارة دورة حياة المفاتيح والتجديد اللحظي

توفر لوحة تحكم المنصة خياراً يتيح للمطورين والمديرين إعادة توليد مفتاح التوكن السري بنقرة واحدة تحت اسم تجديد التوكن. عند اتخاذ هذا الإجراء لأسباب دورية أو عند الاشتباه في تسرب المفتاح، يقوم النظام فوراً بحذف التوكن القديم من قواعد البيانات وذاكرة الكاش المؤقتة، ويصدر مفتاحاً جديداً بالكامل. تتوقف كافة التطبيقات القديمة التي تستخدم المفتاح السابق عن العمل فوراً، مما يمنحك سيطرة أمنية كاملة لعزل أي تهديد دون المساس ببيانات الأجهزة المتصلة أو كشوف الحسابات المسجلة.

التوثيق البرمجي التفصيلي للمسارات الخمسة المدعومة

توفر بوابة المطورين خمس نقاط نهاية (Endpoints) قياسية مبنية بأسلوب RESTful تغطي كافة متطلبات التحكم في الأجهزة، إرسال الإشعارات، إدارة أرصدة المحافظ، واستعراض سجلات القيود المحاسبية. نستعرض في هذا القسم كل مسار بكافة تفاصيله البرمجية، مع نماذج استدعاء cURL جاهزة للاختبار، ونماذج استجابة JSON مفككة وموضحة حقلاً بحقل.

مسار جلب وعرض الأجهزة المسجلة عبر GET

يُستخدم هذا المسار لاسترجاع قائمة تفصيلية بجميع أجهزة الأندرويد المسجلة على حساب المطور في خدمة VCash، مع بيان حالة اتصال كل هاتف بالإنترنت لحظياً، وتفاصيل شرائح الاتصال المتاحة بداخله، والتوقيت الزمني لآخر اتصال بالسحابة.

نموذج استدعاء cURL:

curl -H "Authorization: Bearer WHATS360_API_TOKEN" \
  "https://whats360.live/api/v1/vcash/devices"

نموذج استجابة الاستدعاء الناجح:

{
  "devices": [
    {
      "id": "abc123",
      "name": "Office Phone",
      "status": "online",
      "device_model": "Samsung Galaxy A54",
      "sim1_carrier": "Vodafone",
      "sim1_number": "01012345678",
      "is_enabled": true,
      "last_seen": 1708300000
    }
  ]
}

مسار إرسال رسائل SMS وتحديد منفذ الشريحة عبر POST

يمنح هذا المسار تطبيقك الخارجي القدرة على إرسال رسائل نصية قصيرة SMS مباشرة عبر العتاد الفعلي للهاتف المتصل. يتميز المسار بقدرته على تحديد شريحة الاتصال المستهدفة، مما يتيح لك توجيه رسائل التأكيد والـ OTP عبر نفس شبكة العميل لتوفير التكلفة وضمان سرعة التسليم اللحظية. وللمنشآت التي تحتاج إلى حلول إرسال دولية ضخمة خارج نطاق شرائح الهاتف، يمكن التكامل بسلاسة مع بوابات الإرسال السحابية عبر SMS Control كخيار رديف.

نموذج استدعاء cURL:

curl -X POST -H "Authorization: Bearer WHATS360_API_TOKEN" \
  -H "Content-Type: application/json" \
  "https://whats360.live/api/v1/vcash/sms/send" \
  -d '{
    "device_id": "abc123",
    "recipient": "01012345678",
    "message": "Hello! This is a test message",
    "sim_slot": 1
  }'

نموذج استجابة الاستدعاء الناجح:

{
  "success": true,
  "message": "Message sent successfully",
  "sms_id": 42
}

مسار تنفيذ ومعالجة أوامر USSD التفاعلية عبر POST

يمثل هذا المسار القلب النابض لأتمتة العمليات المصرفية ومحافظ الاتصالات؛ حيث يجبر هاتف الأندرويد على تشغيل تطبيق الاتصال وطلب كود USSD الخاص بالشبكة بصورة آلية. يفيد ذلك في الاستعلام عن رصيد المحفظة الفعلي، إنشاء كود سحب نقدية من الصراف الآلي (ATM Cash-out Code)، أو تحويل مبالغ نقدية لعملاء وموردين دون لمس شاشة الهاتف.

نموذج استدعاء cURL:

curl -X POST -H "Authorization: Bearer WHATS360_API_TOKEN" \
  -H "Content-Type: application/json" \
  "https://whats360.live/api/v1/vcash/ussd/execute" \
  -d '{
    "device_id": "abc123",
    "command": "*9#",
    "sim_slot": 1
  }'

نموذج استجابة الاستدعاء الناجح:

{
  "success": true,
  "command_id": 15,
  "status": "pending",
  "message": "Command sent for execution"
}

مسار استعلام ملخص الأرصدة والتدفقات المالية عبر GET

يتيح هذا المسار للأنظمة المحاسبية ومواقع التجارة سحب تقرير مالي فوري يلخص إجمالي العمليات الواردة، المبالغ المصروفة، وصافي السيولة المتاحة داخل المحفظة المرتبطة بهاتف معين، بالإضافة إلى إجمالي عدد العمليات الموثقة بالعملة المعتمدة.

نموذج استدعاء cURL:

curl -H "Authorization: Bearer WHATS360_API_TOKEN" \
  "https://whats360.live/api/v1/vcash/balance?device_id=abc123"

نموذج استجابة الاستدعاء الناجح:

{
  "total_income": 15000.50,
  "total_expense": 8500.00,
  "net_balance": 6500.50,
  "transaction_count": 142,
  "currency": "EGP"
}

مسار كشف الحساب وسجل المعاملات والفلترة المتقدمة عبر GET

يُعد هذا المسار الأداة الأساسية لربط المتاجر الإلكترونية بعمليات التحقق الذاتي من الدفع؛ إذ يتيح استخراج كشف حساب دقيق للمعاملات مع إمكانية الفلترة بحسب نوع المعاملة (واردة أو صادرة)، وتحديد حجم النتائج وتطبيق الإزاحة الرقمية لتسهيل بناء واجهات الترقيم في لوحات التحكم.

نموذج استدعاء cURL:

curl -H "Authorization: Bearer WHATS360_API_TOKEN" \
  "https://whats360.live/api/v1/vcash/transactions?device_id=abc123&type=income&limit=20&offset=0"

نموذج استجابة الاستدعاء الناجح:

{
  "transactions": [
    {
      "id": 1,
      "type": "income",
      "amount": 500.00,
      "currency": "EGP",
      "from_phone": "01098765432",
      "txn_ref": "TXN-ABC123",
      "description": "Incoming transfer from 01098765432",
      "created_at": 1708300000
    }
  ],
  "total": 142
}

التطبيق العملي خطوة بخطوة لأتمتة استقبال مدفوعات فودافون كاش

لتوضيح الصورة العملية لكيفية استغلال هذه المسارات البرمجية في بيئة إنتاج حقيقية (Production Environment)، نستعرض السيناريو التالي لمتجر إلكتروني يرغب في تفعيل اشتراك المستخدم تلقائياً بمجرد تحويله المبلغ عبر محفظة فودافون كاش:

شاهد التطبيق العملي خطوة بخطوة لربط المحفظة واستقبال المدفوعات وتفعيل الخدمات برمجياً وتلقائياً:

محرك تحليل الرسائل والتعابير النمطية وإنشاء القيود المحاسبية الذاتية

تتنوع صياغة رسائل التأكيد النصية باختلاف شركات الاتصالات وتحديثاتها المستمرة، وهو ما كان يشكل كابوساً برمجياً للمطورين عند محاولة كتابة خوارزميات تحليل النصوص يدوياً. لحل هذه المشكلة جذرياً، تم تزويد محرك VCash داخل Whats360 بمحرك متقدم للتعابير النمطية (Regex Engine) وفلاتر الراسل المتقدمة:

فلترة الراسل وتصفية الرسائل الموثقة

لمنع إغراق النظام برسائل غير مرغوب فيها، تتيح إعدادات الجهاز تحديد أسماء الراسلين المعتمدين؛ مثل إدخال VodafoneCA أو vf-cash أو OrangeCash. يضمن هذا الفلتر تجاهل أي رسالة نصية واردة من أرقام شخصية عادية أو رسائل تسويقية عامة، مما يحمي موارد السيرفر ويضمن نقاء البيانات المحاسبية بنسبة 100%.

أنماط الاستخراج الذكي للحقول المالية

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

• قيمة المبلغ المحول: استخلاص الأرقام العشرية والصحيحة المرتبطة بكلمات مثل “تم استلام مبلغ” أو “تم تحويل”.
• رقم هاتف الراسل الفعلي: التقاط أرقام الهواتف المحولة المكونة من 11 رقماً محلياً واستبعاد الأرقام المختصرة للشبكة.
• الرقم المرجعي للعملية: اقتناص الأكواد المميزة المرافقة لإشعار الشبكة لضمان تفرد القيد المحاسبي.
• إنشاء المعاملة المالية الذاتية: بمجرد نجاح المطابقة، يُنشئ النظام تلقائياً قيداً مالياً في جدول الحسابات لتظهر العملية مباشرة في مسار الاستعلامات /transactions وتنعكس فوراً على رصيد الجهاز في مسار /balance دون أي تدخل بشري.

تنفيذ أوامر USSD المعقدة وإدارة الحملات المتعددة الخطوات

تفرض مشغلات شبكات المحمول في كثير من الأحيان تنفيذ العمليات عبر قوائم تفاعلية متعددة الطبقات (Interactive Menus)؛ كأن تطلب إدخال رقم الخدمة أولاً، ثم إدخال رقم المستلم، ثم المبلغ، وتأكيد العملية برمز PIN. يمتلك محرك VCash القدرة على التعامل مع هذه السيناريوهات المعقدة عبر آليتين متطورتين:

حملات أوامر USSD المجمعة عبر القوالب الديناميكية

تتيح المنصة إطلاق حملات مجمعة لتحويل الأموال أو صرف المكافآت لآلاف المستفيدين دفعة واحدة عبر بناء قوالب أوامر ديناميكية تحتوي على متغيرات مخصصة؛ مثل كتابة الكود بالصيغة:

*9*7*$phone*$amount#

يقوم النظام بقراءة جدول المستفيدين المكون من أعمدة الأرقام والمبالغ، ويتولى الهاتف تنفيذ هذه الأوامر بالتتابع وبفواصل زمنية مدروسة تمنع تعرض الشريحة للإيقاف من قبل شركة الاتصالات، مع إمكانية إيقاف الحملة مؤقتاً واستئنافها في أي وقت بنقرة زر.

سيناريوهات الخطوات المتسلسلة وفترات الانتظار

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

هندسة الأمان الصارمة وحماية وتشفير الرمز السري PIN

يمثل الأمان المالي الركيزة الأهم في منظومة VCash، وتتبع المنصة سياسات هندسية تمنع وصول أي طرف للبيانات البنكية أو رموز التحكم الحساسة:

الدليل المرجعي لمعالجة الأخطاء البرمجية وأكواد HTTP

تعتمد بوابة VCash API أكواد الحالة القياسية لبروتوكول HTTP لإبلاغ الخادم الخارجي بنتيجة معالجة الطلب. يوضح الجدول التالي تفنيداً شاملاً لهذه الأكواد، وأسبابها البرمجية، وكيفية التعامل معها داخل نظامك:

الهيكل القياسي الموحد لاستجابات النظام البرمجية

تعتمد كافة الاستجابات البرمجية الصادرة عن المنصة هيكلاً موحداً يسهل التعامل معه برمجياً في مختلف لغات البرمجة (مثل PHP، Python، Node.js، وc#):

في حالة النجاح التام:

{
  "success": true,
  "message": "...",
  "data": { }
}

في حالة حدوث خطأ أو رفض الطلب:

{
  "success": false,
  "error": "error description"
}

مصفوفة القرار التشغيلي والمفاضلة بين الربط البرمجي وواجهة التحكم

حرصاً على كفاءة استثمار الموارد ومنع إرهاق الفرق التقنية وغير التقنية بتكاليف ربط غير ضرورية، تقدم المنصة خيارين واضحين للتشغيل، ويمكنك استخدام مصفوفة القرار التالية لتحديد الأسلوب الأمثل لنشاطك:

الأسئلة الشائعة حول Whats360 VCash API

مقالات ذات صلة

• دليل ربط المحافظ الإلكترونية بالـ CRM عبر Whats360
• أتمتة مدفوعات فودافون كاش واستقبال التحويلات في المتاجر
• تنفيذ أوامر USSD برمجياً والتحكم في الهواتف عن بعد
• بناء بوابة إرسال رسائل SMS عبر هواتف أندرويد

curl -X GET "https://whats360.live/api/v1/vcash/devices" \
  -H "Authorization: Bearer WHATS360_API_TOKEN" \
  -H "Accept: application/json"