ربط زين كاش والمحافظ الإلكترونية في العراق مع VCash: API وWebhook وأتمتة المدفوعات

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

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

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

في هذا الدليل سنشرح آلية ربط زين كاش والمحافظ الإلكترونية التي تعتمد على إشعارات SMS، والمتطلبات الأساسية، وطريقة عمل VCash، بالإضافة إلى بوابة المطورين وواجهات API المذكورة للنظام، وطريقة المصادقة باستخدام API Token، وأمثلة cURL وJSON، وكيف يمكن استخدام Webhook وربط البيانات مع n8n أو نظام برمجي مخصص.

ما المشكلة التي يحلها ربط المحافظ الإلكترونية في العراق؟

عند استقبال المدفوعات عبر محفظة إلكترونية، قد تبدأ العملية بطريقة بسيطة جدًا: العميل يحول المبلغ إلى المحفظة، ثم تصل رسالة SMS تؤكد العملية.

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

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

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

كيف تعمل منظومة VCash مع زين كاش؟

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

عندما يقوم العميل بتحويل الأموال إلى المحفظة، تصل رسالة إلى الهاتف. يعمل تطبيق VCash Gateway على قراءة الرسالة وتحويل المعلومات الموجودة بها إلى بيانات يمكن للمنصة التعامل معها.

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

هل VCash مخصص لزين كاش فقط؟

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

إذا كانت المحفظة الرقمية ترسل إشعارًا عبر SMS عند استلام الأموال، فإن هذا الإشعار يمكن أن يمثل مصدرًا للبيانات التي يتعامل معها النظام.

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

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

ما الذي تحتاجه لبدء ربط محفظتك الإلكترونية؟

هاتف Android

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

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

تطبيق VCash Gateway

يتم تثبيت تطبيق VCash Gateway على الهاتف ومنحه الصلاحيات اللازمة للوصول إلى رسائل SMS، لأن الرسائل تمثل مصدر البيانات الذي تعتمد عليه آلية الرصد.

حساب في Whats360

يمكن إنشاء حساب على Whats360 ثم طلب تفعيل تجربة خدمة VCash من خلال الدعم الفني.

نظام تريد ربطه بالمدفوعات

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

مبرمج عند الحاجة إلى تكامل مخصص

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

ما هو Webhook في نظام VCash؟

الـ Webhook هو آلية تسمح بإرسال بيانات حدث معين إلى نظام خارجي حتى يستطيع التعامل معه تلقائيًا.

في سيناريو المدفوعات، يمكن تصور الـ Workflow بهذه الصورة:

إشعار SMS → VCash → بيانات العملية → Webhook → نظامك

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

على سبيل المثال، يمكن أن يصل الحدث إلى n8n، ثم يبدأ Workflow يحتوي على الإجراءات التي يحتاجها المشروع.

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

ربط VCash مع n8n

من السيناريوهات المهمة للمطورين وأصحاب الأنظمة استخدام n8n كطبقة أتمتة بين VCash وبقية الأنظمة.

يمكن أن يبدأ الـ Workflow من Webhook ثم يقوم n8n بمعالجة البيانات وفق المنطق الذي تم تصميمه للمشروع.

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

وبالتالي يستطيع المبرمج بناء Workflow واضح يبدأ من الحدث وينتهي بالإجراء المطلوب بدل وضع جميع المهام داخل تطبيق الهاتف.

بوابة مطوري VCash في Whats360

بالنسبة للمطورين، توفر بوابة VCash مجموعة من واجهات API المذكورة للتعامل مع أجهزة VCash ورسائل SMS وأوامر USSD وبعض البيانات المالية.

العنوان الأساسي Base URL المذكور لجميع طلبات الواجهة البرمجية هو:

https://whats360.live

وتُبنى عليه مسارات الواجهات البرمجية المختلفة.

وتشمل الواجهات المذكورة في المعلومات المتاحة:

• عرض الأجهزة المسجلة.
• إرسال رسائل SMS.
• تنفيذ أوامر USSD.
• عرض ملخص البيانات المالية.
• عرض سجل المعاملات المالية.

Authentication وإدارة API Token

تعتمد الواجهات البرمجية المذكورة على API Token للمصادقة.

يتم إرسال التوكن في ترويسة HTTP باسم Authorization، وبالصيغة التالية:

Authorization: Bearer [TOKEN_ID]

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

كما تتضمن بوابة المطورين خيارًا لتجديد التوكن عند الحاجة.

واجهة API لعرض أجهزة VCash

الواجهة البرمجية الخاصة بعرض الأجهزة المسجلة هي:

GET /api/v1/vcash/devices

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

طلب cURL

curl -H "Authorization: Bearer [TOKEN_ID]" "https://whats360.live/api/v1/vcash/devices"

مثال استجابة JSON

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

الحقول الموجودة في المثال

الحقل	المعنى
id	معرف الجهاز
name	اسم الجهاز
status	حالة الجهاز
device_model	موديل الهاتف
sim1_carrier	شركة الاتصالات الخاصة بالشريحة
sim1_number	رقم الشريحة
is_enabled	حالة تفعيل الجهاز
last_seen	آخر وقت ظهر فيه الجهاز

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

واجهة إرسال SMS عبر VCash

من الواجهات المذكورة أيضًا واجهة إرسال رسائل SMS من خلال جهاز VCash.

المسار هو:

POST /api/v1/vcash/sms/send

يحتاج الطلب إلى تحديد الجهاز والمستلم ومحتوى الرسالة وشريحة SIM المستخدمة للإرسال.

طلب cURL

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

مثال الاستجابة

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

يوضح المثال أن العملية نجحت، كما يعيد النظام معرف الرسالة من خلال الحقل sms_id.

الحقل	وظيفته
device_id	تحديد الجهاز المستخدم للإرسال
recipient	رقم المستلم
message	نص الرسالة
sim_slot	رقم شريحة SIM المستخدمة

واجهة تنفيذ أوامر USSD

توفر الواجهات المذكورة أيضًا Endpoint لتنفيذ أوامر USSD على جهاز متصل.

المسار:

POST /api/v1/vcash/ussd/execute

يمكن أن يستخدم هذا النوع من التكامل لتنفيذ أوامر USSD على الجهاز مع تحديد شريحة SIM المطلوبة.

طلب cURL

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

مثال الاستجابة

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

في هذا المثال يتم إرسال الأمر إلى الجهاز وتظهر حالته pending، مع وجود معرف للعملية في command_id.

الحقل	الوظيفة
device_id	تحديد الجهاز الذي سينفذ الأمر
command	أمر USSD المطلوب تنفيذه
sim_slot	تحديد شريحة SIM المستخدمة

واجهة عرض ملخص الرصيد والبيانات المالية

من الواجهات المذكورة في بوابة المطورين Endpoint خاص بملخص البيانات المالية.

المسار:

GET /api/v1/vcash/balance

ويظهر في المثال استخدام device_id لتحديد الجهاز المطلوب.

طلب cURL

curl -H "Authorization: Bearer [TOKEN_ID]" \
"https://whats360.live/api/v1/vcash/balance?device_id=[DEVICE_ID]"

مثال الاستجابة

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

وتوضح الاستجابة مجموعة من الحقول التي يمكن استخدامها داخل نظام التقارير أو التطبيق:

• total_income لإجمالي الدخل.
• total_expense لإجمالي المصروفات.
• net_balance لصافي الرصيد.
• transaction_count لعدد المعاملات.
• currency للعملة.

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

واجهة عرض سجل المعاملات المالية

عند الحاجة إلى التعامل مع سجل العمليات المالية، يمكن استخدام:

GET /api/v1/vcash/transactions

وتوضح المعلومات المتاحة إمكانية استخدام معلمات لتحديد الجهاز ونوع العملية وعدد النتائج والإزاحة.

طلب cURL

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

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

المعامل	وظيفته	المثال
device_id	تحديد الجهاز	[DEVICE_ID]
type	تحديد نوع العملية	income
limit	عدد النتائج	20
offset	الإزاحة	0

ويمكن أن تكون هذه الواجهة مفيدة عند بناء صفحة تقارير أو لوحة تعرض سجل العمليات وفق فلاتر معينة.

كيف يصمم المبرمج تكامل الدفع بشكل صحيح؟

الخطأ الذي يجب تجنبه هو التفكير في التكامل على أنه مجرد طلب API واحد.

التكامل الجيد يبدأ من تعريف دورة العمل كاملة.

تحديد الحدث

يجب أولًا تحديد الحدث الذي يبدأ العملية، مثل وصول إشعار دفع.

تحديد البيانات المطلوبة

بعد ذلك يجب تحديد البيانات التي يحتاجها النظام لمعالجة العملية.

تحديد النظام المستهدف

هل سيتم إرسال البيانات إلى متجر؟ أم نظام اشتراكات؟ أم CRM؟ أم n8n؟ أم نظام برمجي خاص؟

تحديد منطق المعالجة

بعد استقبال البيانات يجب أن يعرف النظام ماذا سيفعل بها. هل سيبحث عن طلب؟ هل سيطابق بيانات معينة؟ هل سيغير حالة عملية؟ أم يبدأ Workflow جديدًا؟

تحديد النتيجة النهائية

يجب أن تكون هناك نتيجة واضحة للـWorkflow، لأن استقبال البيانات وحده ليس هو الهدف النهائي.

ربط VCash بالمتاجر الإلكترونية

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

يمكن أن يبدأ السيناريو من تحويل العميل للمبلغ، ثم وصول SMS، ثم معالجة البيانات، ثم إرسالها إلى نظام المتجر.

لكن يجب ألا يتحول مجرد وصول رسالة إلى قرار مالي غير مشروط.

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

بهذا يصبح التصميم أكثر تنظيمًا:

استقبال الإشعار → استخراج البيانات → التحقق والمعالجة → مطابقة الطلب → تنفيذ الإجراء

ربط المحافظ الإلكترونية بخدمات الاشتراكات

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

عندما يدفع العميل، يمكن أن تبدأ عملية معالجة الدفع من خلال البيانات التي تصل من VCash، ثم يقرر نظام الاشتراكات ما إذا كانت العملية مرتبطة بالاشتراك المطلوب.

بعد نجاح المعالجة يمكن للنظام تنفيذ الإجراء البرمجي الذي تم تصميمه للمشروع.

المهم هنا هو أن VCash يمثل طبقة استقبال ونقل للبيانات، بينما يظل منطق الاشتراك وتنفيذ الخدمة داخل النظام الذي يتم ربطه به.

ربط VCash مع أنظمة CRM

إذا كان النشاط التجاري يستخدم CRM لإدارة العملاء، يمكن أن تكون بيانات العمليات المالية جزءًا من سجل العميل أو من Workflow خاص بالمبيعات وخدمة العملاء.

وبدل انتقال الموظف بين الهاتف ونظام CRM، يمكن تصميم تدفق آلي يستقبل البيانات ثم يمررها إلى النظام وفق القواعد البرمجية المطلوبة.

وهنا تظهر أهمية الـAPI والـWebhook، لأنهما يسمحان بربط طبقة المدفوعات بطبقة إدارة البيانات بدل إبقاء المعلومات منفصلة.

ما الفرق بين API وWebhook في هذا السيناريو؟

رغم ارتباطهما بالتكامل، فإن لكل منهما وظيفة مختلفة.

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

Webhook: يسمح بإرسال حدث أو بيانات من النظام إلى عنوان خارجي عندما يحدث الحدث الذي تم تصميم التكامل للتعامل معه.

في مشروع واحد يمكن استخدام الاثنين معًا.

على سبيل المثال، قد يستخدم نظامك API لعرض الأجهزة أو إرسال أمر، بينما يستخدم Webhook لاستقبال حدث من النظام.

ماذا يحتاج المبرمج من بيانات API؟

عند بناء التكامل، يحتاج المبرمج إلى معرفة العناصر الأساسية الخاصة بكل Endpoint.

• Base URL.
• HTTP Method.
• Endpoint.
• Authentication.
• Headers.
• Query Parameters.
• JSON Body.
• Response Format.
• معرفات الأجهزة والعمليات عند الحاجة.

ولهذا تعتبر أمثلة cURL وJSON مفيدة أثناء تطوير التكامل، لأنها توضح شكل الطلب وشكل الاستجابة المتوقعين.

أخطاء يجب الانتباه إليها أثناء بناء التكامل

كشف الـAPI Token

من أهم الأخطاء وضع الـToken في مكان يمكن للمستخدم النهائي الوصول إليه.

الاعتماد على الرسالة دون منطق تحقق

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

عدم تحديد الجهاز الصحيح

عند وجود أكثر من جهاز، يجب التعامل مع device_id بشكل واضح حتى لا يتم تنفيذ العملية على الجهاز غير المقصود.

عدم تصميم حالات الأخطاء

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

ربط API دون فهم النتيجة

استدعاء Endpoint بنجاح لا يعني أن Workflow التجاري اكتمل. يجب أن يعرف النظام ماذا يفعل بعد استلام الاستجابة.

متى تكون أتمتة المحافظ الإلكترونية مفيدة؟

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

ومن السيناريوهات التي يمكن أن تستفيد من هذا النوع من التكامل:

• المتاجر الإلكترونية.
• منصات الخدمات الرقمية.
• أنظمة الاشتراكات.
• أنظمة CRM.
• أنظمة الأتمتة.
• المنصات البرمجية المخصصة.
• المشاريع التي تحتاج إلى ربط بيانات الدفع بـ n8n.

هل تحتاج إلى مبرمج لربط زين كاش مع موقعك؟

إذا كان الهدف تشغيل VCash وتجهيز الهاتف وربطه بالخدمة، فهذه تختلف عن عملية بناء تكامل برمجي مخصص.

أما إذا كنت تريد أن تنتقل بيانات العمليات إلى موقعك أو CRM أو n8n أو نظام اشتراكات، فستحتاج إلى شخص يفهم أساسيات REST API وHTTP وJSON وAuthentication وWebhook.

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

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

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

فهم دورة العمل قبل استخدام VCash API

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

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

ما الذي يحتاجه المطور لبدء التكامل؟

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

ويعتمد التكامل على استخدام API Token في ترويسة الطلبات بالشكل التالي:

Authorization: Bearer [TOKEN_ID]

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

ومن الأفضل أن تتم طلبات API من الخادم Backend أو من طبقة وسيطة مثل نظام الأتمتة أو الـMiddleware، بحيث تظل بيانات المصادقة بعيدة عن متصفح المستخدم.

Base URL

العنوان الأساسي المذكور لواجهات VCash هو:

https://whats360.live

وبناءً عليه يتم تركيب مسار الـEndpoint المطلوب لتنفيذ العملية البرمجية.

على سبيل المثال، إذا كان المطلوب عرض الأجهزة المسجلة، يكون المسار:

GET /api/v1/vcash/devices

ويصبح عنوان الطلب الكامل:

https://whats360.live/api/v1/vcash/devices

عرض أجهزة VCash المسجلة عبر API

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

المسار هو:

GET /api/v1/vcash/devices

مثال باستخدام cURL:

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

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

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

المهم هنا أن المطور لا ينبغي أن يتعامل مع اسم الجهاز باعتباره المعرف الأساسي لتنفيذ العمليات. الأفضل استخدام قيمة id الخاصة بالجهاز عندما يتطلب الـEndpoint ذلك.

أهم الحقول في استجابة الأجهزة

الحقل	المعنى
id	المعرف الخاص بالجهاز
name	اسم الجهاز داخل النظام
status	حالة الجهاز مثل online
device_model	موديل الهاتف
sim1_carrier	شركة الاتصالات المرتبطة بالشريحة
sim1_number	معرف أو رقم الشريحة وفق البيانات المتاحة
is_enabled	حالة تفعيل الجهاز
last_seen	آخر وقت ظهر فيه الجهاز متصلًا

إرسال SMS من خلال جهاز VCash

يوفر النظام Endpoint لإرسال رسالة SMS من خلال جهاز VCash، مع إمكانية تحديد الجهاز وشريحة SIM المستخدمة.

مسار الواجهة البرمجية هو:

POST /api/v1/vcash/sms/send

ويحتاج الطلب إلى Authorization Header بالإضافة إلى Content-Type مناسب لأن البيانات يتم إرسالها بصيغة JSON.

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

في هذا المثال توجد عدة قيم مهمة يجب أن يفهمها المطور قبل تنفيذ الطلب.

المعلمة	وظيفتها
device_id	معرف جهاز VCash الذي سيقوم بتنفيذ الإرسال
recipient	رقم المستلم
message	محتوى الرسالة النصية
sim_slot	رقم شريحة SIM المستخدمة في الإرسال

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

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

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

تنفيذ أوامر USSD

من الواجهات المهمة أيضًا Endpoint الخاص بتنفيذ أوامر USSD على جهاز VCash.

ويكون المسار:

POST /api/v1/vcash/ussd/execute

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

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

وتتضمن البيانات الأساسية في الطلب:

• device_id: الجهاز المطلوب تنفيذ الأمر عليه.
• command: أمر USSD الذي سيتم إرساله.
• sim_slot: شريحة SIM المستخدمة.

ومن أمثلة الاستجابة:

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

وهنا توجد نقطة مهمة في تصميم التكامل: ظهور status بقيمة pending يعني أن إرسال الأمر للتنفيذ لا ينبغي التعامل معه تلقائيًا على أنه نتيجة نهائية للعملية.

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

عرض إجمالي الدخل والمصروفات والرصيد

يوفر النظام Endpoint لعرض الملخص المالي المرتبط بجهاز محدد.

المسار هو:

GET /api/v1/vcash/balance

ويتم تمرير معرف الجهاز من خلال Query Parameter باسم device_id.

curl -H "Authorization: Bearer [TOKEN_ID]" \
"https://whats360.live/api/v1/vcash/balance?device_id=[DEVICE_ID]"

ومن أمثلة الاستجابة:

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

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

البيانات التي يعرضها Endpoint الرصيد

الحقل	الوصف
total_income	إجمالي الدخل
total_expense	إجمالي المصروفات
net_balance	صافي الرصيد
transaction_count	عدد المعاملات
currency	العملة المرتبطة بالبيانات

عرض سجل المعاملات المالية

إذا كان المطلوب ليس مجرد معرفة إجمالي الدخل والمصروفات، وإنما معرفة العمليات نفسها، فيمكن استخدام Endpoint سجل المعاملات.

المسار:

GET /api/v1/vcash/transactions

ويمكن استخدام مجموعة من Query Parameters لتصفية النتائج، مثل معرف الجهاز ونوع العملية وعدد النتائج والإزاحة.

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

في هذا المثال يتم طلب معاملات الدخل الخاصة بجهاز محدد، مع طلب 20 نتيجة والبدء من الإزاحة رقم صفر.

فكرة limit وoffset

استخدام limit وoffset مهم عند التعامل مع عدد كبير من المعاملات. بدل تحميل كل السجل في طلب واحد، يمكن للنظام قراءة النتائج على دفعات.

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

ومن أمثلة الاستجابة:

{
  "transactions": [
    {
      "id": 1,
      "type": "income"
    }
  ]
}

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

كيف يمكن استخدام VCash مع زين كاش في العراق؟

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

يبدأ المسار من المحفظة عندما يقوم العميل بتحويل المبلغ، ثم تصل رسالة الإشعار إلى الهاتف المرتبط بالمحفظة. يقوم تطبيق VCash Gateway الموجود على هاتف Android بقراءة رسالة الـSMS وتحويل بياناتها إلى معلومات يمكن للمنصة التعامل معها.

بعد ذلك يمكن إرسال البيانات إلى النظام الخارجي من خلال Webhook، بحيث يستطيع النظام اتخاذ الإجراء المناسب وفق المنطق البرمجي الذي تم تصميمه.

ربط VCash مع متجر إلكتروني

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

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

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

وهنا تظهر أهمية وجود طبقة Backend أو Middleware بين VCash والمتجر، بدل وضع منطق المعالجة بالكامل داخل واجهة المستخدم.

ربط VCash مع نظام اشتراكات

في أنظمة الاشتراكات، يمكن أن يكون السيناريو مختلفًا. الهدف قد يكون تفعيل اشتراك العميل أو تمديد فترة اشتراكه بعد تسجيل عملية الدفع.

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

ويمكن أن يكون الـWebhook هو نقطة الدخول التي تبدأ عندها هذه العملية البرمجية.

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

ربط VCash مع n8n

يمكن استخدام منصات الأتمتة مثل n8n كطبقة وسيطة بين بيانات VCash والنظام النهائي.

الفكرة هنا أن يصل الحدث إلى Webhook داخل workflow، ثم تتم معالجة البيانات، وبعدها يمكن توجيهها إلى الخطوة المناسبة، مثل تحديث سجل عميل أو إرسال إشعار أو تنفيذ طلب API آخر.

هذا النموذج مفيد عندما يكون المطلوب بناء Automation بدون كتابة Backend كامل لكل خطوة، مع الاحتفاظ بإمكانية إضافة منطق مخصص عند الحاجة.

مثال منطقي للـWorkflow

VCash

↓

Webhook

↓

قراءة بيانات العملية

↓

التحقق من البيانات

↓

البحث عن العميل أو الطلب

↓

تنفيذ الإجراء

↓

تسجيل العملية

ما الفرق بين API وWebhook في هذا النوع من التكامل؟

الـAPI والـWebhook يؤديان أدوارًا مختلفة، وفهم الفرق بينهما مهم جدًا عند بناء نظام يعتمد على المدفوعات الإلكترونية.

الـAPI يسمح لنظامك بإرسال طلب إلى المنصة للحصول على بيانات أو تنفيذ عملية. أما الـWebhook فيسمح للمنصة بإرسال حدث أو بيانات إلى عنوان URL خاص بنظامك عندما يحدث الحدث الذي تم إعداده له.

العنصر	الدور
API	نظامك يطلب أو ينفذ عملية من خلال المنصة
Webhook	المنصة ترسل بيانات أو حدثًا إلى نظامك

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

أمان API Token

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

وعند الحاجة إلى تغيير التوكن، يمكن استخدام آلية تجديد التوكن المتاحة في المنصة وفق إعدادات الحساب.

متى يحتاج المشروع إلى مبرمج؟

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

عندما يكون الهدف هو إنشاء Workflow برمجي، أو ربط VCash بقاعدة بيانات، أو بناء API Integration، أو مطابقة المدفوعات بالطلبات، فمن الأفضل وجود مطور يفهم Backend وREST API وWebhooks.

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

أخطاء شائعة عند بناء التكامل

وضع التوكن داخل Frontend

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

اعتبار pending نجاحًا نهائيًا

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

عدم التعامل مع تكرار الأحداث

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

الاعتماد على اسم الجهاز بدل المعرف

عند التعامل مع الأجهزة، يجب استخدام device_id وفق متطلبات الـEndpoint بدل الاعتماد على الاسم الظاهر للمستخدم.

خلط بيانات المحفظة مع منطق المتجر

من الأفضل فصل طبقة استقبال البيانات عن طبقة تنفيذ منطق الأعمال. هذا يجعل النظام أسهل في الصيانة والتوسع وربط أكثر من نظام مستقبل.

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

ربط WhatsApp API مع Webhook

دليل API Integration والأتمتة

أتمتة CRM وإدارة العملاء

أتمتة الدفع في المتاجر الإلكترونية

الأسئلة الشائعة حول VCash API وربط المحافظ الإلكترونية

ما هي بوابة المطورين الخاصة بـVCash؟

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

ما هو Base URL الخاص بواجهات VCash؟

العنوان الأساسي المذكور للواجهات البرمجية هو https://whats360.live، ويتم تركيب مسار الـEndpoint المطلوب عليه.

كيف تتم المصادقة مع VCash API؟

يتم إرسال API Token داخل Authorization Header باستخدام صيغة Bearer Token.

Authorization: Bearer [TOKEN_ID]

كيف يمكن عرض الأجهزة المسجلة؟

يتم استخدام:

GET /api/v1/vcash/devices

مع إرسال Authorization Header.

هل يمكن إرسال SMS من خلال VCash API؟

نعم، توجد واجهة لإرسال SMS باستخدام جهاز VCash وتحديد المستلم والرسالة وشريحة SIM المستخدمة.

هل يمكن تنفيذ أوامر USSD؟

توجد واجهة لتنفيذ أوامر USSD على جهاز محدد، مع تحديد أمر USSD وشريحة SIM.

هل يمكن عرض إجمالي الدخل والمصروفات؟

نعم، توجد واجهة /api/v1/vcash/balance لعرض ملخص مالي مرتبط بجهاز محدد.

هل يمكن الحصول على سجل المعاملات؟

نعم، يمكن استخدام /api/v1/vcash/transactions لعرض سجل المعاملات مع إمكانية استخدام معاملات تصفية مثل الجهاز ونوع العملية وعدد النتائج والإزاحة.

هل يمكن ربط زين كاش في العراق بالنظام؟

الفكرة المعروضة في هذا التكامل تعتمد على قراءة إشعارات SMS الواردة إلى الهاتف المرتبط بالمحفظة ثم تحويل البيانات إلى نظام يمكنه التعامل معها آليًا. ويعتمد التنفيذ الفعلي على المحفظة وإشعاراتها وإعدادات النظام.

هل أحتاج إلى مبرمج لربط VCash بموقعي؟

إذا كان المطلوب مجرد تشغيل الخدمة فهذا يختلف عن بناء تكامل برمجي مخصص. أما ربط VCash بمتجر أو نظام اشتراكات أو CRM أو API آخر فيحتاج عادةً إلى فهم للـAPI والـWebhook والـBackend ومنطق معالجة البيانات.

هل يمكن استخدام n8n في التكامل؟

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

الخلاصة

ربط المحافظ الإلكترونية في العراق مثل زين كاش بالأنظمة البرمجية لا يتوقف عند معرفة كيفية إرسال Request إلى API. القيمة الحقيقية تظهر عندما يتم تحويل العملية المالية إلى Workflow منظم يستطيع النظام التعامل معه تلقائيًا.

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

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

وهنا تظهر أهمية تصميم التكامل من البداية باعتباره دورة عمل كاملة، وليس مجرد مجموعة من طلبات API منفصلة.

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

يمكن أن يبدأ الـWorkflow بوصول عملية دفع إلى محفظة زين كاش أو أي محفظة إلكترونية أخرى تدعم إشعارات SMS.

يتم التقاط إشعار العملية، ثم تحويل البيانات المستخرجة إلى النظام، وبعد ذلك يمكن إرسالها إلى الـWebhook أو النظام البرمجي المسؤول عن معالجة الطلب.

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

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

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

أهمية Webhook في أتمتة المدفوعات

الـWebhook هو أحد أهم الأجزاء في عملية الربط، لأنه يسمح للنظام باستقبال البيانات الناتجة عن العملية بدلًا من الاعتماد على المراجعة اليدوية المستمرة.

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

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

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

ربط زين كاش مع أنظمة الاشتراكات

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

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

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

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

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

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

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

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

هذه النقطة مهمة لأن وجود مبلغ مالي في المحفظة لا يعني بالضرورة أن النظام يعرف تلقائيًا لأي طلب أو عميل تعود العملية.

لذلك يجب تصميم آلية واضحة للربط بين بيانات الدفع والطلب أو الحساب داخل النظام.

استخدام n8n في أتمتة العمليات

يمكن أيضًا استخدام أدوات الأتمتة مثل n8n كطبقة وسيطة بين بيانات VCash والأنظمة الأخرى.

في هذا السيناريو يمكن استقبال البيانات ثم تنفيذ مجموعة من الإجراءات بناءً على محتوى العملية.

مثلًا يمكن أن يبدأ الـWorkflow باستقبال Webhook، ثم قراءة بيانات العملية، ثم البحث عن العميل أو الطلب، وبعد ذلك تنفيذ الإجراء المناسب داخل النظام.

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

ما الذي يحتاجه المبرمج قبل بدء التكامل؟

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

• معرفة الـBase URL المستخدم في طلبات API.
• الحصول على API Token صالح.
• تحديد الـEndpoints المطلوبة.
• معرفة الحقول التي يجب إرسالها في كل Request.
• فهم شكل JSON Response المتوقع.
• تحديد طريقة التعامل مع حالات الخطأ.
• تحديد منطق ربط العملية بالعميل أو الطلب.
• تحديد الإجراء الذي سيتم تنفيذه بعد نجاح المعالجة.

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

التعامل مع API Token

يجب التعامل مع API Token باعتباره بيانات حساسة مرتبطة بحساب النظام.

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

الأفضل أن تتم طلبات API الحساسة من الخادم Backend، وأن يتم تخزين بيانات المصادقة في بيئة آمنة مناسبة للنظام المستخدم.

كما يجب عدم وضع التوكن الحقيقي داخل أمثلة منشورة أو مستودعات عامة، واستخدام قيمة بديلة مثل [TOKEN_ID] عند توثيق التكامل.

اختبار التكامل قبل تشغيله على المدفوعات الفعلية

قبل الاعتماد على التكامل في العمليات المالية، يجب اختبار جميع السيناريوهات المهمة.

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

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

وجود آلية واضحة للتعامل مع هذه الحالات يساعد على منع حدوث أخطاء في حالة الطلبات أو الحسابات.

تسجيل المعاملات ومراجعتها

من المهم أن يحتفظ النظام بسجل واضح للعمليات التي تم استقبالها ومعالجتها.

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

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

كلما كان السجل أكثر وضوحًا، أصبح اكتشاف الأخطاء ومراجعة العمليات أسهل.

ماذا تفعل إذا كان لديك أكثر من جهاز؟

عند تشغيل أكثر من جهاز VCash، يجب ألا يعتمد النظام على جهاز واحد بشكل عشوائي.

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

وهذا مهم في الأنظمة التي تعمل على أكثر من رقم أو أكثر من محفظة.

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

متى تحتاج إلى مطور؟

إذا كان المطلوب مجرد تشغيل جهاز VCash وربطه بالخدمة، فعملية الإعداد تختلف عن بناء تكامل برمجي كامل.

أما إذا كان الهدف هو ربط المحافظ الإلكترونية مع متجر أو CRM أو نظام اشتراكات أو منصة SaaS، فستحتاج إلى تنفيذ برمجي يعتمد على API وWebhooks ومنطق معالجة البيانات.

وهنا يكون دور المبرمج هو بناء الطبقة التي تربط بين VCash والنظام الخاص بك، وليس مجرد إرسال طلب API واحد.

إذا كان لديك نظام قائم بالفعل وتريد إضافة الدفع عبر المحافظ الإلكترونية في العراق، فمن الأفضل تحديد الـWorkflow المطلوب أولًا ثم تحديد الـEndpoints والبيانات التي يحتاج إليها النظام.

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

ربط WhatsApp API مع Webhook

دليل API Integration والأتمتة

ربط CRM مع WhatsApp والأتمتة

التجارة الإلكترونية والدفع الإلكتروني

الأسئلة الشائعة

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

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