توثيق API لخدمة المحافظ الإلكترونية VCash عبر Whats360: شرح المصادقة والأجهزة وSMS وUSSD والمعاملات

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

المعلومات الفنية في هذا المقال تشرح مكونات صفحة التوثيق وطريقة فهمها واستخدامها، مع أمثلة برمجية تعتمد على معرفات وهمية مثل {api_token} و{device_id} بدلًا من أي بيانات اعتماد حقيقية.

ما هي صفحة API Docs لخدمة VCash؟

صفحة API Docs لخدمة VCash هي بوابة التوثيق الموجهة إلى المطورين الذين يريدون بناء تكامل برمجي مع خدمة المحافظ الإلكترونية من خلال Whats360.

الفكرة الأساسية هي توفير واجهة برمجية تستطيع الأنظمة الخارجية من خلالها إرسال طلبات HTTP إلى الخدمة بدلًا من الاعتماد على تنفيذ العمليات يدويًا من خلال الواجهة فقط.

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

البنية الأساسية للاتصال بـ VCash API

تبدأ عملية التكامل من تحديد عنوان الخدمة الأساسي ثم استخدام رمز المصادقة المخصص للتكامل. صفحة التوثيق تعرض النطاق الأساسي للخدمة ثم تبني عليه مسارات API المختلفة.

القيمة المستخدمة في التوثيق هي:

Base URL: https://whats360.live

أما المصادقة فتتم من خلال API Token، ويظهر المثال التوضيحي باستخدام معرف عام:

{api_token}

ويتم إرسال الرمز في ترويسة Authorization بصيغة Bearer Token:

Authorization: Bearer {api_token}

هذه النقطة أساسية لأن الطلبات التي لا تحتوي على رمز صالح أو تستخدم رمزًا منتهي الصلاحية يمكن أن تحصل على استجابة خطأ مرتبطة بالمصادقة.

الاستعلام عن أجهزة VCash

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

يمكن استخدام الطلب البرمجي بهذا الشكل:

curl -X GET "${BASE_URL}/api/v1/vcash/devices" \
-H "Authorization: Bearer {api_token}" \
-H "Accept: application/json"

الاستجابة الخاصة بقائمة الأجهزة يمكن أن تتضمن معلومات مثل:

• device_id: المعرف البرمجي للجهاز.
• device_name: اسم الجهاز.
• status: حالة الجهاز.
• model: طراز الجهاز.
• sim: بيانات مرتبطة بالشريحة والشبكة والرقم.
• activation: معلومات تفعيل الجهاز.
• last_seen: آخر ظهور أو اتصال مسجل للجهاز.

إرسال SMS من خلال VCash API

توفر صفحة التوثيق مسارًا لإرسال رسالة SMS من خلال جهاز VCash. ويحتاج الطلب إلى تحديد الجهاز والشريحة والبيانات الخاصة بالرسالة وفق الحقول التي يعرضها التوثيق.

المسار المخصص للإرسال هو:

POST /api/v1/vcash/sms/send

مثال توضيحي باستخدام cURL:

curl -X POST "${BASE_URL}/api/v1/vcash/sms/send" \
-H "Authorization: Bearer {api_token}" \
-H "Content-Type: application/json" \
-d '{
  "device_id": "{device_id}",
  "sim_slot": 1,
  "phone": "{recipient_phone}",
  "message": "{message_text}"
}'

ويظهر في الاستجابة الناجحة ما يشير إلى نجاح العملية، مع رسالة توضيحية ومعرف للرسالة يمكن استخدامه كمرجع داخل النظام.

{
  "success": true,
  "message": "{success_message}",
  "sms_id": "{sms_id}"
}

وجود sms_id في الاستجابة يجعل عملية الإرسال قابلة للتمييز داخل النظام البرمجي، خصوصًا عندما يتم تنفيذ عدد من عمليات الإرسال من خلال التطبيق.

تنفيذ أوامر USSD برمجيًا

من أكثر أجزاء VCash API أهمية للمطورين مسار تنفيذ أوامر USSD. هذا المسار يسمح للنظام الخارجي بإرسال أمر USSD إلى جهاز VCash بدلًا من إدخال الأمر يدويًا.

المسار هو:

POST /api/v1/vcash/ussd/execute

مثال توضيحي:

curl -X POST "${BASE_URL}/api/v1/vcash/ussd/execute" \
-H "Authorization: Bearer {api_token}" \
-H "Content-Type: application/json" \
-d '{
  "device_id": "{device_id}",
  "sim_slot": 1,
  "command": "{ussd_command}"
}'

يمكن أن يكون الأمر المستخدم مرتبطًا بالاستعلام عن الرصيد أو تنفيذ عملية مدعومة من خدمة المحفظة، بحسب السيناريو الذي يتم تنفيذه.

ومن العناصر المهمة في الاستجابة وجود command_id وحالة مثل pending عند بدء التنفيذ.

{
  "success": true,
  "message": "{confirmation_message}",
  "command_id": "{command_id}",
  "status": "pending"
}

الاستعلام عن رصيد VCash

توفر API أيضًا مسارًا لعرض ملخص الرصيد المرتبط بجهاز محدد. ويستخدم هذا المسار معرف الجهاز كمعامل في عنوان الطلب.

GET /api/v1/vcash/balance?device_id={device_id}

يستطيع النظام من خلال هذه البيانات الحصول على صورة مختصرة عن النشاط المالي المرتبط بالجهاز، وتشمل البيانات الموثقة عناصر مثل:

هذه البيانات مفيدة عند بناء لوحة تحكم داخلية تعرض حالة النشاط المالي بصورة مجمعة بدلًا من قراءة كل معاملة بشكل منفصل.

قراءة سجل معاملات VCash

إذا كان المطلوب ليس مجرد معرفة الرصيد، وإنما تحليل الحركة المالية نفسها، فإن API توفر مسارًا للحصول على سجل المعاملات.

GET /api/v1/vcash/transactions?device_id={device_id}&type=income&limit=20&offset=0

يحتوي الطلب على مجموعة من المعاملات التي تسمح بتحديد الجهاز ونوع العمليات وعدد النتائج وموقع البداية داخل النتائج.

وتتضمن بيانات المعاملات الموثقة عناصر مثل:

• transaction_id لمعرف المعاملة.
• type لنوع المعاملة.
• amount لقيمة العملية.
• currency للعملة.
• sender_phone لرقم المرسل عندما يكون متاحًا ضمن البيانات.
• txn_ref للمرجع المرتبط بالمعاملة.
• description لوصف العملية.
• created_at لتاريخ ووقت الإنشاء.
• total لإجمالي النتائج.

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

كيف تبدو الاستجابة الناجحة؟

تعتمد API على بنية استجابة واضحة تساعد التطبيق المستهلك على معرفة ما إذا كان الطلب قد نجح أو فشل.

في الاستجابة الناجحة يظهر الحقل:

"success": true

ويأتي معه message، وقد توجد بيانات إضافية في data وفق نوع endpoint والاستجابة الخاصة به.

كيف تبدو استجابة الخطأ؟

عند فشل الطلب تستخدم API بنية تشير إلى عدم النجاح، حيث تكون قيمة success هي false، مع وجود معلومات الخطأ المناسبة.

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

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

أكواد الأخطاء في VCash API

ماذا يعني خطأ 400 في التكامل؟

خطأ 400 يرتبط بطلب غير صحيح أو بيانات لا تتوافق مع المتطلبات. في هذه الحالة ينبغي للمطور مراجعة الحقول التي يرسلها التطبيق، مثل معرف الجهاز، الشريحة، رقم الهاتف، الأمر المطلوب، أو معاملات الاستعلام.

المهم هنا عدم إعادة إرسال الطلب نفسه بلا تعديل؛ لأن المشكلة في صحة الطلب أو بياناته وليست مجرد مشكلة اتصال.

ماذا يعني خطأ 401؟

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

Authorization: Bearer {api_token}

إذا كان التطبيق يرسل الرمز بطريقة مختلفة عن الصيغة الموثقة، فلن يستطيع الخادم التعامل معه باعتباره رمز مصادقة صالحًا.

ماذا يعني خطأ 403؟

خطأ 403 مختلف عن 401. هنا قد يكون المستخدم معروفًا ومصادقًا عليه، لكن العملية نفسها غير مسموحة بسبب الصلاحيات أو حدود الخطة.

وهذا مهم عند تصميم أنظمة تعتمد على API؛ فلا ينبغي للتطبيق أن يعرض للمستخدم رسالة تفيد بأن Token خاطئ لمجرد أن الخادم أعاد 403.

ماذا يعني خطأ 404؟

خطأ 404 يعني أن المورد المطلوب غير موجود. وفي سياق VCash API يمكن أن يرتبط ذلك بجهاز أو مورد غير موجود، أو بطلب يستخدم معرفًا غير صحيح.

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

ماذا يعني خطأ 500؟

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

إرسال الطلب لا يعني بالضرورة نجاح العملية؛ لذلك يجب أن يظل منطق التطبيق مرتبطًا بالاستجابة الفعلية.

كيف يبني المطور تكاملًا عمليًا مع VCash API؟

التكامل العملي يبدأ من فهم العلاقة بين الأجهزة والعمليات. التطبيق يحتاج إلى معرفة الجهاز، ثم استخدام المعرف المناسب في endpoint المطلوب، ثم تحليل الاستجابة.

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

التعامل مع العمليات المالية يحتاج إلى تحقق واضح

عند استخدام API في سياق محافظ إلكترونية، يجب أن يكون منطق التطبيق أكثر دقة من مجرد إرسال HTTP Request وانتظار كود استجابة.

ففي حالة تنفيذ USSD، مثلًا، قد تظهر حالة pending. وبالتالي فإن قبول الطلب لا ينبغي أن يتم تفسيره تلقائيًا باعتباره نتيجة نهائية لعملية مالية.

الأمان عند استخدام API Token

رمز API هو جزء حساس من عملية المصادقة، ولذلك يجب استخدام معرفات وهمية داخل المقالات والشروحات والمستودعات العامة.

في هذا المقال تم استخدام:

{api_token}

بدلًا من أي Token فعلي.

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

لماذا تعتبر بنية API Docs مهمة للمطور؟

قيمة صفحة التوثيق لا تتوقف على وجود endpoints فقط. المطور يحتاج إلى معرفة طريقة الاتصال، طريقة المصادقة، الحقول المطلوبة، شكل الاستجابة، الأخطاء المتوقعة، ومعنى كل قيمة حتى يستطيع بناء تكامل مستقر.

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

كما أن تقسيم API إلى وظائف منفصلة يجعل النظام أكثر قابلية للفهم. فهناك endpoint للأجهزة، وآخر لإرسال SMS، وآخر لـUSSD، ومسارات مستقلة للرصيد والمعاملات.

استخدام بيانات الأجهزة في لوحة تحكم داخلية

يمكن للنظام الخارجي استخدام بيانات endpoint الخاص بالأجهزة لبناء واجهة تعرض قائمة الأجهزة ومعلوماتها الأساسية، مثل الاسم والمعرف والحالة والطراز ومعلومات الشريحة وآخر ظهور.

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

استخدام بيانات المعاملات في التقارير

Endpoint المعاملات يفتح المجال أمام بناء تقارير داخلية تعتمد على بيانات العمليات بدلًا من عرض الرصيد فقط.

وجود الحقول الخاصة بالمعرف والقيمة والعملة والمرجع والوصف والتاريخ يسمح للنظام بالتعامل مع كل معاملة كوحدة بيانات مستقلة.

كما أن وجود limit وoffset يجعل من الممكن تقسيم البيانات إلى صفحات داخل واجهة المستخدم بدلًا من تحميل مجموعة ضخمة دفعة واحدة.

الفرق بين قراءة الرصيد وقراءة المعاملات

الربط مع أنظمة الأعمال

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

بهذه الطريقة لا تكون API مجرد صفحة توثيق للمطور، وإنما طبقة اتصال بين خدمة VCash والبرامج الخارجية التي تحتاج إلى قراءة البيانات أو تنفيذ العمليات المدعومة.

أخطاء شائعة عند قراءة توثيق VCash API

من الأخطاء الشائعة التعامل مع API وكأن كل endpoint يعمل بنفس الحقول والاستجابة. في الواقع، لكل وظيفة مسارها والبيانات المناسبة لها.

• استخدام endpoint الأجهزة بدل endpoint المعاملات.
• نسيان إرسال Authorization بصيغة Bearer.
• إرسال معرف جهاز غير صحيح.
• إرسال بيانات لا تتوافق مع الطلب.
• اعتبار حالة pending نتيجة نهائية.
• الخلط بين 401 و403.
• اعتبار كل استجابة HTTP ناجحة دليلًا على نجاح العملية.
• نشر API Token حقيقي داخل أمثلة أو ملفات عامة.
• افتراض وجود endpoint غير موثق لمجرد أن التطبيق يحتاج إليه.

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

مقالات واتساب API وتكاملات البرمجة

أتمتة أوامر USSD في Whats360

المحافظ الإلكترونية وربطها بالأنظمة

تحليل رسائل المحافظ الإلكترونية باستخدام Regex

مقالات Whats360 API والتكاملات البرمجية

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

Authorization: Bearer {api_token}