الربط البرمجي مع باي كارد للمبتدئين: API والويب هوك وMCP خطوة بخطوة
Team PayCard Partners · · 5 Minutes Read
تعرف متى تحتاج الربط البرمجي فعلا، وكيف تجهز رمز API وعناوين IP والويب هوك بأمان. ثم اربط مساعدك الذكي بحسابك عبر Pay Card MCP.
إن كان لديك موقع خاص أو تطبيق أو نظام محاسبة، وتريد أن تطلب الشحن والأكواد منه مباشرة دون فتح لوحة «شركاء باي كارد»، فأنت تحتاج الربط البرمجي. هذا الدليل مكتوب للمبتدئ التقني: صاحب متجر يتعامل مع مبرمج، أو مبرمج يتعامل مع المنصة لأول مرة. سنشرح متى تحتاج API فعلا، وكيف تجهز الرمز وعناوين IP، وما فائدة الويب هوك وتوقيعه، وكيف تستخدم Pay Card MCP مع مساعدات الذكاء الاصطناعي، ثم كيف تمنح الصلاحية لموظفك التقني.
هل تحتاج API أصلا؟
ليس كل تاجر يحتاج برمجة. المنصة تقدم قنوات جاهزة تكفي أغلب المتاجر، وكلها موضحة في التعريف بشركاء باي كارد. قارن قبل أن تبدأ:
| وضعك | Channel Occasion | هل تحتاج مبرمجا؟ |
|---|---|---|
| تبيع لعدد محدود وتطلب بنفسك | Order from Website | No |
| you have Store in Cart | App Cart and link Products | No |
| Your Store on Shopify or RMZ or WooCommerce | الربط الجاهز في صفحة «الربط والتقنية» | غالبا لا |
| تريد متجرا جاهزا باسمك دون منصة أخرى | "Merchant Kiosk" | No |
| لديك موقع أو تطبيق أو نظام مبني خصيصا | API v1 and the webhook | Yes |
| تريد أن تسأل مساعدا ذكيا عن رصيدك وطلباتك | Pay Card MCP | No |
إن كان وضعك في الصف قبل الأخير، فأكمل القراءة. وإن كان في صف سلة فالأسهل لك guide Link a Store Cart.
أين تجد أدوات المطورين؟
كل شيء في صفحة واحدة: من «إدارة حساب التاجر» افتح «الربط والتقنية» (صفحة /api). ستجد فيها رابط «توثيق واجهة برمجة التطبيقات (API)» الذي يفتح توثيق API v1، وأقسام الرموز وعناوين IP والويب هوك.
ماذا تتيح API v1؟
| Group | Usage |
|---|---|
| Balance | معرفة رصيد محفظتك قبل إرسال الطلبات |
| Categories | جلب قائمة التصنيفات لعرضها في نظامك |
| Products | جلب المنتجات وأسعارك الحالية |
| Orders | إنشاء طلب جديد وعرض الطلبات وحالاتها |
الحد المسموح 120 طلبا في الدقيقة. صمم نظامك بحيث لا يتجاوزه، مثلا بحفظ قائمة المنتجات مؤقتا بدل جلبها مع كل زيارة لموقعك. أسماء الحقول وشكل الطلب والرد كلها في التوثيق، فاعتمد عليه لا على التخمين.
الخطوة 1: إنشاء رمز API
- Open "Integration and Technical".
- انتقل إلى قسم «رموز واجهة برمجة التطبيقات (API)».
- اضغط «إنشاء رمز».
- انسخ الرمز فورا واحفظه في مكان آمن على الخادم، مثل متغيرات البيئة، لا داخل كود الواجهة الذي يراه الزوار.
الخطوة 2: تحديد عناوين IP المسموح بها
حتى لو تسرب الرمز، يمكنك تقليل الخطر بتحديد الأجهزة التي يسمح لها باستخدامه:
- اعرف عنوان IP الثابت لخادمك من مزود الاستضافة.
- في قسم «عناوين IP المسموح بها» اضغط «إضافة عنوان IP».
- أضف عنوان كل خادم يرسل الطلبات، بما فيها خادم الاختبار إن وجد.
إن انتقلت إلى استضافة جديدة فأضف العنوان الجديد قبل النقل، حتى لا تتوقف طلباتك فجأة.
الخطوة 3: الويب هوك لمعرفة الحالة دون سؤال متكرر
بعد إنشاء الطلب قد يستغرق التنفيذ بعض الوقت. بدل أن يسأل نظامك كل ثوان «هل اكتمل؟»، تجعل المنصة تخبره بنفسها. هذا هو الويب هوك:
- جهز في نظامك رابطا يستقبل الإشعارات، ويفضل أن يكون HTTPS.
- من «الربط والتقنية» اضغط «إنشاء Webhook».
- أدخل الرابط، واختر الحدث «تحديث حالة الطلب».
- اكتب «الرمز السري» لتوقيع الإشعارات. هو اختياري، لكننا ننصح به دائما.
لماذا التوقيع مهم؟
رابط الويب هوك قد يعرفه أي شخص، فيستطيع إرسال إشعار مزيف يقول إن طلبا اكتمل. عند ضبط «الرمز السري» يأتي الإشعار موقعا، فيتحقق نظامك من التوقيع بالرمز نفسه، ويرفض أي إشعار لا يطابق. طريقة حساب التوقيع ومكانه في الإشعار موضحة في Documentation.
ونصيحة عملية: اعتبر الويب هوك تنبيها، وعند الشك اسأل API عن حالة الطلب لتتأكد. الطلب قد يكتمل كاملا أو جزئيا أو يلغى ويسترد مبلغه، وفهم هذه الحالات ضروري لتعرضها لعميلك بشكل صحيح، وهي مشروحة في دليل حالات الطلبات والاسترجاع.
طلبات API داخل لوحتك
الطلبات التي تنشئها عبر API تظهر في «سجل الطلبات» ضمن «الطلبات الداخلية»، مع «مسار التنفيذ» و«سجل المحفظة» لكل طلب. وتنطبق عليها حماية المنصة نفسها: إن ارتفعت التكلفة عما دفعته يلغى الطلب قبل إرساله ويعود المبلغ إلى محفظتك. لذلك احرص أن يتعامل نظامك مع الطلب الملغى بشكل واضح، وأن يراقب الرصيد قبل الإرسال، فالرصيد غير الكافي يفشل الطلب. طرق الشحن في guide Wallet Top-up.
Pay Card MCP: اسأل مساعدك الذكي عن متجرك
MCP طريقة تتيح لمساعدات مثل ChatGPT أو Claude الاتصال بحسابك والإجابة من بياناته الفعلية: كم رصيدي؟ ما سعر هذا المنتج؟ ما حالة الطلب الفلاني؟ هل ربط متجري سليم؟ لا تحتاج برمجة:
- from "Merchant Account Management" Open "Pay Card MCP".
- اضغط «أنشئ رابط MCP». الرابط يظهر مرة واحدة فقط، فانسخه فورا.
- الوضع الافتراضي «قراءة فقط». وإن أردت أن يساعدك المساعد في ربط منتجات سلة بالكتالوج ففعل خيار «اسمح للمساعد بربط المنتجات».
- في ChatGPT أو Claude افتح الإعدادات ثم Connectors ثم Add custom connector، والصق الرابط.
limits MCP
- المساعد لا يشتري ولا ينشئ طلبات، ولا ينفق من محفظتك.
- أقصى ما يستطيع تغييره هو ربط المنتجات، وفقط إن سمحت له بذلك.
- الرابط سري مثل رمز API، فلا تشاركه.
شرح أوسع مع أمثلة على صفحة Pay Card MCP.
صلاحية الموظف التقني
إن كان المبرمج يعمل معك، فلا تعطه كلمة مرور حسابك. أنشئ له حسابا من «إدارة الموظفين»:
- اضغط «إضافة موظف»، واكتب الاسم والبريد وكلمة المرور.
- Enable "Email verification at sign-in".
- اختر صلاحية «الـ API والويب هوك»، وأضف ما يحتاجه فقط، مثل «سجل الطلبات» لمتابعة الاختبارات.
- Press "Create Account".
البيانات الشخصية والوثائق والعقد والتحقق الثنائي وإدارة الموظفين لا تمنح لأي موظف أبدا. وتذكر أن أي طلب ينشئه الموظف يخصم من محفظتك، وأن «سجل عمليات الموظفين» يعرض ما قام به.
قائمة فحص قبل التشغيل الفعلي
- Code Saved on Server only.
- عناوين IP لكل خوادمك مضافة.
- الويب هوك مضبوط بـ«الرمز السري»، ونظامك يتحقق من التوقيع.
- نظامك لا يتجاوز 120 طلبا في الدقيقة.
- جربت طلبا صغيرا وتابعت ظهوره في «الطلبات الداخلية».
- نظامك يعرض للعميل حالات الإلغاء والاكتمال الجزئي بوضوح.
FAQ
هل أحتاج API إذا كان متجري في سلة؟
غالبا لا، فتطبيق سلة وربط المنتجات ينفذان الطلبات آليا دون برمجة. الـ API مناسب للمواقع والأنظمة المبنية خصيصا.
كم طلبا يمكنني إرساله عبر API؟
الحد 120 طلبا في الدقيقة، فصمم نظامك بحيث لا يتجاوزه.
هل الرمز السري للويب هوك إلزامي؟
هو اختياري، لكنه يتيح لنظامك التحقق من أن الإشعار صادر من المنصة، لذلك ننصح بضبطه دائما.
هل يستطيع ChatGPT أو Claude الشراء من رصيدي عبر MCP؟
لا، المساعد لا يشتري ولا ينفق من المحفظة. الوضع الافتراضي قراءة فقط، ويمكنك السماح له بربط المنتجات فقط.
فقدت رابط MCP، هل يمكنني رؤيته مجددا؟
الرابط يظهر مرة واحدة عند إنشائه، فأنشئ رابطا جديدا من صفحة «Pay Card MCP» واحفظه فورا.
كيف أعطي المبرمج صلاحية دون كلمة مروري؟
أنشئ له حساب موظف من «إدارة الموظفين» وامنحه صلاحية «الـ API والويب هوك» فقط مع ما يحتاجه.