الربط البرمجي مع باي كارد للمبتدئين: API والويب هوك وMCP خطوة بخطوة

إن كان لديك موقع خاص أو تطبيق أو نظام محاسبة، وتريد أن تطلب الشحن والأكواد منه مباشرة دون فتح لوحة «شركاء باي كارد»، فأنت تحتاج الربط البرمجي. هذا الدليل مكتوب للمبتدئ التقني: صاحب متجر يتعامل مع مبرمج، أو مبرمج يتعامل مع المنصة لأول مرة. سنشرح متى تحتاج API فعلا، وكيف تجهز الرمز وعناوين IP، وما فائدة الويب هوك وتوقيعه، وكيف تستخدم Pay Card MCP مع مساعدات الذكاء الاصطناعي، ثم كيف تمنح الصلاحية لموظفك التقني.

هل تحتاج API أصلا؟

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

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

أين تجد أدوات المطورين؟

كل شيء في صفحة واحدة: من «إدارة حساب التاجر» افتح «الربط والتقنية» (صفحة /api). ستجد فيها رابط «توثيق واجهة برمجة التطبيقات (API)» الذي يفتح توثيق API v1، وأقسام الرموز وعناوين IP والويب هوك.

ماذا تتيح API v1؟

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

الخطوة 1: إنشاء رمز API

1. افتح «الربط والتقنية».
2. انتقل إلى قسم «رموز واجهة برمجة التطبيقات (API)».
3. اضغط «إنشاء رمز».
4. انسخ الرمز فورا واحفظه في مكان آمن على الخادم، مثل متغيرات البيئة، لا داخل كود الواجهة الذي يراه الزوار.

الخطوة 2: تحديد عناوين IP المسموح بها

حتى لو تسرب الرمز، يمكنك تقليل الخطر بتحديد الأجهزة التي يسمح لها باستخدامه:

1. اعرف عنوان IP الثابت لخادمك من مزود الاستضافة.
2. في قسم «عناوين IP المسموح بها» اضغط «إضافة عنوان IP».
3. أضف عنوان كل خادم يرسل الطلبات، بما فيها خادم الاختبار إن وجد.

إن انتقلت إلى استضافة جديدة فأضف العنوان الجديد قبل النقل، حتى لا تتوقف طلباتك فجأة.

الخطوة 3: الويب هوك لمعرفة الحالة دون سؤال متكرر

بعد إنشاء الطلب قد يستغرق التنفيذ بعض الوقت. بدل أن يسأل نظامك كل ثوان «هل اكتمل؟»، تجعل المنصة تخبره بنفسها. هذا هو الويب هوك:

1. جهز في نظامك رابطا يستقبل الإشعارات، ويفضل أن يكون HTTPS.
2. من «الربط والتقنية» اضغط «إنشاء Webhook».
3. أدخل الرابط، واختر الحدث «تحديث حالة الطلب».
4. اكتب «الرمز السري» لتوقيع الإشعارات. هو اختياري، لكننا ننصح به دائما.

لماذا التوقيع مهم؟

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

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

طلبات API داخل لوحتك

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

Pay Card MCP: اسأل مساعدك الذكي عن متجرك

MCP طريقة تتيح لمساعدات مثل ChatGPT أو Claude الاتصال بحسابك والإجابة من بياناته الفعلية: كم رصيدي؟ ما سعر هذا المنتج؟ ما حالة الطلب الفلاني؟ هل ربط متجري سليم؟ لا تحتاج برمجة:

1. من «إدارة حساب التاجر» افتح «Pay Card MCP».
2. اضغط «أنشئ رابط MCP». الرابط يظهر مرة واحدة فقط، فانسخه فورا.
3. الوضع الافتراضي «قراءة فقط». وإن أردت أن يساعدك المساعد في ربط منتجات سلة بالكتالوج ففعل خيار «اسمح للمساعد بربط المنتجات».
4. في ChatGPT أو Claude افتح الإعدادات ثم Connectors ثم Add custom connector، والصق الرابط.

حدود MCP

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

شرح أوسع مع أمثلة على صفحة Pay Card MCP.

صلاحية الموظف التقني

إن كان المبرمج يعمل معك، فلا تعطه كلمة مرور حسابك. أنشئ له حسابا من «إدارة الموظفين»:

1. اضغط «إضافة موظف»، واكتب الاسم والبريد وكلمة المرور.
2. فعل «التحقق بالبريد عند الدخول».
3. اختر صلاحية «الـ API والويب هوك»، وأضف ما يحتاجه فقط، مثل «سجل الطلبات» لمتابعة الاختبارات.
4. اضغط «إنشاء الحساب».

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

قائمة فحص قبل التشغيل الفعلي

• الرمز محفوظ على الخادم فقط.
• عناوين IP لكل خوادمك مضافة.
• الويب هوك مضبوط بـ«الرمز السري»، ونظامك يتحقق من التوقيع.
• نظامك لا يتجاوز 120 طلبا في الدقيقة.
• جربت طلبا صغيرا وتابعت ظهوره في «الطلبات الداخلية».
• نظامك يعرض للعميل حالات الإلغاء والاكتمال الجزئي بوضوح.