توثيق واجهة برمجة التطبيقات لبوابة المحافظ الإلكترونية VCash عبر منصة Whats360

التحديات المعمارية في أتمتة المحافظ النقدية المحلية

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

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

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

المعايير العامة والبنية التحتية للمصادقة البرمجية

تخضع كافة المسارات البرمجية في بوابة VCash لبروتوكولات الويب القياسية. تتميز الاستدعاءات بالخفة والسرعة مع التزام صارم بأسلوب النقل الآمن عبر بروتوكول HTTPS المشفر، مع إرجاع مخرجات معيارية بصيغة JSON.

الرابط الأساسي وترويسات الطلب الإلزامية

يجب أن تبدأ كافة مسارات استدعاء الـ API بالعنوان التالي:

https://whats360.live

تعتمد المنصة آلية التحقق عبر مفاتيح الوصول الحاملة (Bearer Token). يجب توليد التوكن الخاص بحسابك من واجهة المطورين في لوحة التحكم، وإدراجه داخل ترويسات الطلب كالتالي:

Authorization: Bearer {api_token}
Content-Type: application/json
Accept: application/json

مسار استعلام وإدارة الأجهزة والشرائح المتصلة

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

نموذج الاستدعاء عبر cURL

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

هيكل الاستجابة القياسية (JSON Response)

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

تحليل مفردات كائن الجهاز (Device Object Anatomy)

• id: المعرف الداخلي الفريد للجهاز، وهو المعامل البرمجي الحاسم الذي يلزم تمريره في كافة طلبات إرسال الرسائل وتنفيذ أوامر USSD اللاحقة.
• name: التسمية التوضيحية التي تم تحديدها للجهاز لتيسير مراقبته وتوجيهه في البيئات متعددة الهواتف.
• status: الحالة اللحظية للاتصال، وتأخذ قيمة online عندما يكون التطبيق متصلاً بخوادم المنصة وجاهزاً للمعالجة الفورية، أو offline في حال انقطاع الشبكة عن الهاتف.
• device_model: الموديل المصنعي للهاتف للتحقق من التوافقية ومطابقة العتاد.
• sim1_carrier & sim1_number: المشغل المعتمد للشريحة الأولى (مثل Vodafone أو Orange أو WE) ورقم الهاتف المتصل بالمحفظة النقدية.
• is_enabled: قيمة منطقية تشير إلى تفعيل أو تعطيل الجهاز إدارياً عبر لوحة التحكم.
• last_seen: الختم الزمني بنظام Unix Epoch لآخر إشارة استجابة تم تلقيها من الهاتف.

مسار إرسال الرسائل النصية القصيرة SMS برمجياً

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

محددات جسم الطلب (Payload Schema)

مثال الطلب البرمجي عبر 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": "شكراً لتعاملك معنا. تم تأكيد استلام مبلغ 500 جنيه بنجاح على طلبك رقم #4921.",
    "sim_slot": 1
  }'

هيكل الاستجابة للرسالة المرسلة

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

يُعيد النظام الحقل sms_id كمعرف فريد ومفتاح تتبع أساسي؛ حيث يمكن لموقعك أو نظامك الداخلي تخزينه في جدول الإشعارات للرجوع إليه عند التدقيق ومطابقة حالات التسليم لاحقاً.

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

تُعتبر القدرة على تنفيذ أوامر USSD عبر بروتوكولات الويب البرمجية الميزة الأبرز التي تحل معضلة المحافظ الذكية في الشرق الأوسط. تتيح لك الواجهة طلب الأكواد السريعة لتحويل الأموال، مثل *9*7*رقم_الهاتف*المبلغ#، أو أكواد استعلام الرصيد، وتلقي الردود بشكل مؤتمت وتفاعلي.

مثال الطلب البرمجي عبر 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
  }'

الاستجابة الأولية غير المتزامنة (Asynchronous Execution)

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

مسار تقارير الأرصدة والملخص المالي اللحظي

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

مثال الاستدعاء عبر cURL

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

هيكل البيانات المالية المسترجعة (Financial JSON Response)

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

يُقدم هذا المسار إحصاءات مالية مباشرة ومحسوبة تلقائياً استناداً إلى الرسائل النصية المعتمدة المستلمة على الجهاز. يتم حساب net_balance عن طريق طرح إجمالي المصروفات total_expense من إجمالي الإيرادات total_income مع توضيح عدد الحركات المسجلة transaction_count والعملة المقيدة بالجنيه المصري EGP.

مسار سجل المعاملات المالية المفصلة ومطابقة الحسابات

لإتمام دورة المراجعة ومطابقة الحوالات المستلمة مع سلة مشتريات المتجر، يوفر مسار المعاملات مصفوفة غنية تتيح الفرز والتصفية واستعراض أرقام الحوالات المرجعية الصادرة من شركات الاتصالات.

مثال الاستدعاء عبر cURL مع الفلترة والتقسيم (Pagination)

curl -X GET \
  -H "Authorization: Bearer WHATS360_API_TOKEN" \
  -H "Accept: application/json" \
  "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
}

معمارية الاستجابات وهيكل الأخطاء البرمجية القياسي

تلتزم منصة Whats360 بنمط استجابة برمجي موحد لكافة العمليات، مما يُمكّن المطورين من كتابة كود معالجة استثناءات (Exception Handling) نظيف وموثوق في لغات البرمجة المختلفة.

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

{
  "success": false,
  "error": "وصف دقيق لسبب الخطأ"
}

دليل تشخيص أكواد الحالة HTTP وإجراءاتها التصحيحية

أمثلة برمجية عملية للربط في بيئات التشغيل

فيما يلي نماذج برمجية متكاملة مكتوبة بأشهر لغات تطوير الواجهات الخلفية (Node.js/TypeScript و PHP) توضح كيفية دمج الاستدعاءات مع معالجة الأخطاء بصورة هندسية سليمة.

نموذج متكامل بلغة TypeScript و Node.js (باستخدام مكتبة Axios)

import axios, { AxiosError } from 'axios';

interface SendSmsResponse {
  success: boolean;
  message: string;
  sms_id?: number;
  error?: string;
}

async function sendCustomerSms(
  deviceId: string,
  phoneNumber: string,
  textMessage: string
): Promise<number | null> {
  const url = 'https://whats360.live/api/v1/vcash/sms/send';
  const apiToken = process.env.WHATS360_API_TOKEN;

  try {
    const response = await axios.post<SendSmsResponse>(
      url,
      {
        device_id: deviceId,
        recipient: phoneNumber,
        message: textMessage,
        sim_slot: 1
      },
      {
        headers: {
          'Authorization': `Bearer ${apiToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        },
        timeout: 10000
      }
    );

    if (response.data.success && response.data.sms_id) {
      console.log(`[+] تم إرسال الرسالة بنجاح. معرف الإشعار: ${response.data.sms_id}`);
      return response.data.sms_id;
    }
    return null;
  } catch (error) {
    const err = error as AxiosError<SendSmsResponse>;
    if (err.response) {
      console.error(`[-] رفض الطلب من الخادم (${err.response.status}): ${err.response.data.error}`);
    } else {
      console.error(`[-] فشل الاتصال بالشبكة: ${err.message}`);
    }
    return null;
  }
}

نموذج متكامل بلغة PHP Native (باستخدام cURL)

<?php

function fetchVcashTransactions(string $deviceId, string $apiToken, int $limit = 20): ?array {
    $endpoint = "https://whats360.live/api/v1/vcash/transactions?device_id=" . urlencode($deviceId) . "&type=income&limit=" . $limit;

    $curl = curl_init();
    curl_setopt_array($curl, [
        CURLOPT_URL => $endpoint,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer {$apiToken}",
            "Accept: application/json"
        ]
    ]);

    $response = curl_exec($curl);
    $statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    $curlError = curl_error($curl);
    curl_close($curl);

    if ($curlError) {
        error_log("CURL Network Error: " . $curlError);
        return null;
    }

    $decoded = json_decode($response, true);

    if ($statusCode === 200 && isset($decoded['transactions'])) {
        return $decoded['transactions'];
    }

    error_log("API Failed with HTTP [{$statusCode}]: " . ($decoded['error'] ?? 'Unknown error'));
    return null;
}

أفضل الممارسات الهندسية لتشغيل البوابة في بيئات الإنتاج

لضمان أعلى معايير الاستقرار عند معالجة آلاف الحوالات اليومية، يوصي مهندسو النظم باتباع القواعد التصميمية التالية:

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

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

• دليل ربط فودافون كاش والمحافظ الإلكترونية بمتاجر ووكومرس وشوبيفاي
• توثيق واجهة برمجة تطبيقات واتساب للأعمال وحلول الويب هوك للمطورين
• كيف تنشئ بوابة إرسال رسائل SMS محلية باستخدام أجهزة أندرويد
• مقارنة شاملة بين بوابات الدفع الإلكتروني والمحافظ الرقمية في مصر

خريطة المعرفة البرمجية واستعلامات التكامل الدلالي (Semantic & AEO Hub)