دليل تشغيل Vodafone Cash API عبر Whats360 لأتمتة الدفع والعمليات عبر بروتوكول USSD برمجياً

تتصدر المحافظ الإلكترونية وفي مقدمتها محفظة “فودافون كاش” حركة المدفوعات اليومية في التجارة الإلكترونية داخل مصر. ورغم حجم التداول المليوني، اصطدم المطورون وأصحاب المشروعات الرقمية لسنوات بحاجز تقني معقد: عدم توفر واجهات برمجة تطبيقات رسمية ومفتوحة (Public APIs) للمطورين المستقلين والمتاجر الناشئة، مما فرض آلية عقيمة ترتكز على مطالبة العميل بإرسال لقطة شاشة (Screenshot) للتحويل، ثم مراجعتها يدوياً من موظفي خدمة العملاء. هذه العملية لا تستهلك ساعات العمل وتؤخر تسليم المنتجات الرقمية وشحن الطرود فحسب، بل فتحت باباً واسعاً للاحتيال عبر الصور المفبركة والمعدلة ببرامج التصميم.

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

المعمارية الهندسية لمنظومة VCash Gateway وآلية العمل

لفهم كيف يحقق النظام زمن استجابة شبه لحظي في التحقق من المعاملات المالية، يجب تفكيك المعمارية الهندسية إلى ثلاث طبقات تشغيلية مترابطة تعتمد على شبكة اتصالات مؤمنة ببروتوكولات TLS 1.3:

الصلاحيات الثلاث الحساسة وسر كفاءة خدمة Accessibility

يعمل تطبيق VCash Gateway دون الحاجة لترويض الهاتف (Root) أو التلاعب بنظام التشغيل، معتمداً على ثلاث أذونات نظام قياسية تضمن تشغيلاً آمناً ومستقراً:

• صلاحية قراءة الرسائل (RECEIVE_SMS & READ_SMS): تتيح للتطبيق الاستماع للبث الإذاعي الداخلي لنظام أندرويد (Broadcast Receiver) فور استلام الشريحة لرسالة قصيرة، مما يلغي تماماً الحاجة لعمليات الفحص الدوري (Polling) ويوفر استهلاك البطارية وموارد المعالج.
• صلاحية الإشعارات وتجاوز توفير الطاقة (Notification Listener & WakeLock): تضمن بقاء الاتصال السحابي المشفر بين الهاتف وخوادم المنصة مفتوحاً عبر مقبس ويب (WebSocket) دائم في الخلفية، دون أن يوقفه نظام إدارة الذاكرة العشوائية الصارم في أندرويد.
• خدمة إمكانية الوصول (Accessibility Service) – العصب التنفيذي للمنظومة: تُمثل هذه الميزة الاختراق الهندسي الحقيقي؛ فعند تنفيذ أوامر USSD المعقدة مثل الاستعلام عن الرصيد أو إجراء تحويلات كودية (`*9#`)، تفرض شركات المحمول شاشة تأكيد تفاعلية تطلب إدخال الرقم السري (PIN). لا تستطيع تطبيقات أندرويد العادية التفاعل مع هذه النوافذ المنبثقة التابعة لخدمات الهاتف. هنا تتدخل خدمة Accessibility لقراءة الشاشة برمجياً، والتعرف الفوري على مربع إدخال PIN، واستدعاء الرقم السري المحفوظ بأمان في إعدادات المنصة وحقنه آلياً في جزء من الثانية وضغط زر الإرسال.

خطوات الإعداد والربط السحابي خطوة بخطوة

تم تصميم عملية الربط لتكون قياسية ولا تستغرق أكثر من خمس دقائق، مما يتيح لك بناء البوابة وتجربتها مباشرة باتباع المسار العملي التالي:

مقارنة شاملة: المعالجة اليدوية مقابل البوابات التقليدية وVCash Gateway

يوضح الجدول التالي الفوارق التشغيلية والمالية بين خيارات تحصيل أموال المحافظ الإلكترونية المتاحة في السوق المصري:

أتمتة أوامر الـ USSD والحملات والسيناريوهات المتقدمة

تتعدى قدرات المنظومة مجرد استقبال الأموال إلى التحكم الكامل في خدمات المحفظة التفاعلية التي تتم عبر بروتوكول USSD (مثل التحويل للغير، شحن الرصيد، أو دفع الفواتير)، مما يتيح لك بناء أنظمة دفع واسترداد أموال (Cashback / Refunds) مؤتمتة بنسبة 100%:

1. سيناريوهات التنفيذ متعددة الخطوات (Multi-Step Execution)

تتطلب بعض الخدمات المصرفية تتابعاً تفاعلياً مع الشبكة. عبر تبويب “السيناريوهات” في المنصة، يمكنك بناء مسار تنفيذي متكامل يتضمن:

• إرسال كود ابتدائي للشبكة (مثال: `*9#`).
• فترة انتظار زمنية لرد الشبكة يتم ضبطها بدقة (مثال: تأخير 2 ثانية – Delay 2s).
• استخدام متغيرات ديناميكية يتم تمريرها في المسار مثل `$phone` و `$amount`.
• حقن الرقم السري للمحفظة فور التعرف على شاشة المطالبة عبر الـ Accessibility Service وتأكيد الخروج.

2. حملات الـ USSD المجمعة (Bulk Campaigns Engine)

إذا كنت تدير منصة تسويق بالعمولة أو تدفع مستحقات مئات الموردين والمندوبين دورياً، يمكنك جدولة حملات تحويل مجمعة:

• تحديد قالب الأمر: صياغة الهيكل الكودي التلقائي مثل: *9*7*$phone$*$amount$#.
• قائمة المستلمين: لصق البيانات بضغطة واحدة بصيغة قياسية بسيطة (رقم المحفظة,المبلغ) في كل سطر.
• المعالجة التتابعية: يقوم محرك المنصة بتنفيذ العمليات عبر الهاتف واحدة تلو الأخرى مع إدارة فترات الانتظار لتجنب حظر الشريحة أو تعليق قناة الاتصال اللاسلكية.

التوثيق البرمجي الشامل لنقاط اتصال REST API

تعتمد المنصة على معايير RESTful صارمة. يتم إرسال كافة الطلبات إلى العنوان الأساسي الموحد وتتطلب وجود توكن المصادقة البرمجي في ترويسة الطلب:

نقطة الاتصال الأولى: استعلام الأجهزة المتصلة

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

GET /api/v1/vcash/devices

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

نموذج الاستجابة القياسية (200 OK):

{
 "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 برمجياً

إرسال رسائل نصية قصيرة إلى العملاء من خلال الشريحة المحددة في الهاتف، مع إمكانية تحديد منفذ الشريحة (`sim_slot`).

POST /api/v1/vcash/sms/send

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": "تم تأكيد عملية الدفع الخاصة بك بنجاح، رقم طلبك: 5541",
 "sim_slot": 1
 }'

نموذج الاستجابة القياسية (200 OK):

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

نقطة الاتصال الثالثة: تنفيذ أمر USSD خارجي برمجياً

توجيه أمر لاسلكي إلى شريحة الهاتف لتنفيذ عملية استعلام أو تحويل مالي فوراً.

POST /api/v1/vcash/ussd/execute

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
 }'

نموذج الاستجابة القياسية (200 OK):

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

نقطة الاتصال الرابعة: الاستعلام المالي عن الرصيد وحسابات المحفظة

توليد ملخص مالي كامل يوضح إجمالي المبالغ المحصلة والمصروفات وصافي الرصيد الإجمالي.

GET /api/v1/vcash/balance

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

نموذج الاستجابة القياسية (200 OK):

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

نقطة الاتصال الخامسة: استعلام وتصفية سجل المعاملات المالية

النقطة الجوهرية للتحقق من وصول دفعة عميل معين لتحديث حالة طلبه في قاعدة بياناتك برمجياً.

GET /api/v1/vcash/transactions

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

نموذج الاستجابة القياسية (200 OK):

{
 "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
}

مصفوفة أكواد الخطأ القياسية وطريقة معالجتها برمجياً

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

بروتوكول الأمان وحماية الأرصدة والخصوصية

التعامل مع المحافظ المالية يتطلب هندسة أمان وقائية على أعلى المستويات. تعتمد منظومة VCash على ثلاث طبقات تأمين متقدمة لمنع أي اختراق أو تسريب لأرصدتك:

الأسئلة الشائعة حول تشغيل واستخدام VCash API