واجهة API لبوابة الدفع بالعملات الرقمية: 12 نقطة تفحصها قبل الربط
كل API للدفع بالعملات الرقمية يستطيع إنشاء فاتورة، لكن الفروق تظهر عند إعادة المحاولة والمدفوعات الجزئية وفشل الـ webhooks. قائمة تحقق من 12 نقطة للمطورين، مع طريقة تعامل API mistKET مع كل نقطة.
كل واجهة API لبوابة الدفع بالعملات الرقمية تعد بالشيء نفسه: أنشئ فاتورة، واقبض المبلغ، واستلم الـ callback. لا تظهر الفروق إلا لاحقًا — عندما يتسابق طلبان، أو يرسل العميل أقل قليلًا من قيمة الفاتورة، أو يتوقف خادمك ساعة كاملة، أو يعيد مهاجم إرسال طلب اعترضه. اختيار الـ API بعناية يوفّر وقتًا أكثر بكثير من ربطه بسرعة.
هذه قائمة تحقق للمطورين والمديرين التقنيين (CTO) الذين يقارنون واجهات API للدفع بالعملات الرقمية قبل كتابة أي سطر برمجي. في كل نقطة سترى ما الذي تبحث عنه، ولماذا يهم، وكيف يتعامل معه API mistKET. إذا كنت قد اخترت بالفعل وتريد الكود خطوة بخطوة، فانتقل إلى دليل ربط API الدفع بالعملات الرقمية.
الحد الأدنى من نقاط النهاية (Endpoints)
لا يكفي أن يوفّر API الدفع بالعملات الرقمية «إنشاء دفعة». ابحث على الأقل عن:
| القدرة | لماذا تحتاجها | نقطة النهاية في mistKET |
|---|---|---|
| إنشاء فاتورة | طلب دفع واحد لكل طلب شراء، مع مدة صلاحية | POST /invoices |
| جلب فاتورة | المطابقة عندما يفوتك webhook | GET /invoices/{uuid} |
| عرض الفواتير وتصفيتها | شاشات الإدارة والمطابقة الليلية | GET /invoices |
| إلغاء فاتورة | تحرير المخزون عند التخلي عن الطلب | POST /invoices/{uuid}/cancel |
| الأصول المدعومة | عرض الشبكات القابلة للدفع الآن فقط | GET /assets |
| عرض سعر الصرف | إظهار المبلغ بالعملة الرقمية قبل إنشاء الفاتورة | GET /rate |
| فحص الحالة | المراقبة والتراجع السلس عند الأعطال | GET /health |
إذا لم يكن المزوّد يتيح جلب الفواتير أو عرضها، فستضطر إلى الثقة بالـ webhooks ثقة عمياء — وهو موقف سيئ عند أول فشل في التسليم.
1. المصادقة: هل كل طلب موقّع؟
مفتاح API يُرسل في ترويسة هو الخيار الأضعف: كل من يعترضه أو يُسرّبه يستطيع إنشاء الفواتير وإلغاءها. فضّل API يُوقَّع فيه كل طلب بسرّ لا ينتقل عبر الشبكة أبدًا. تحمل طلبات mistKET الترويسات X-Api-Key وX-Api-Timestamp وتوقيع HMAC-SHA256 للطابع الزمني والجسم الخام للطلب. ويُعرض السرّ مرة واحدة فقط في لوحة التاجر.
2. الحماية من إعادة الإرسال (Replay)
التوقيع وحده لا يمنع أحدًا من إعادة إرسال طلب اعترضه. ابحث عن نافذة زمنية للطابع الزمني ودعم للـ nonce. يرفض mistKET الطوابع الزمنية التي تبتعد أكثر من ±300 ثانية عن وقت الخادم، ولا يقبل التوقيع نفسه مرتين في الطلبات التي تغيّر الحالة. ويضيف الإصدار 2 من التوقيع nonce لكل طلب ويوقّع الطريقة (method) والمسار أيضًا، فلا يمكن إعادة استخدام التوقيع على نقطة نهاية أخرى.
3. الـ Idempotency عند إنشاء الفاتورة
انتهاء مهلة الاتصال أمر واقع في الشبكات. إذا أعادت صفحة الدفع لديك محاولة استدعاء «إنشاء فاتورة»، فيجب ألا ينتهي بك الأمر بفاتورتين لطلب واحد. يوفّر الـ API الجيد مفتاح idempotency. في mistKET يؤدي order_id الخاص بك هذا الدور: الاستدعاء مجددًا برقم الطلب نفسه يعيد الفاتورة الموجودة مع "idempotent": true بدلًا من إنشاء فاتورة جديدة.
4. نموذج حالات يغطي المدفوعات الحقيقية
«مدفوع / غير مدفوع» لا يكفي. يرسل العملاء أقل قليلًا لأن منصة التداول اقتطعت رسومًا، أو أكثر من المطلوب، أو يدفعون بعد انتهاء الصلاحية. تأكد أن الـ API يُظهر هذه الحالات صراحةً. تمر فواتير mistKET بالحالات new وpending وunderpaid وpaid وconfirmed وoverpaid وexpired وcancelled، مع حقول مثل paid_amount وremaining_amount وcan_pay_remaining وunder_review حتى لا يضطر الكود لديك إلى التخمين أبدًا.
paid أن التحويل اكتُشف وينتظر التأكيدات؛ لا تسلّم الطلبات إلا عند confirmed أو overpaid.5. تأكيدات يمكنك رؤيتها
يجب أن يخبرك الـ API بعدد تأكيدات الكتل التي حصلت عليها الدفعة وعدد المطلوب منها، إضافةً إلى تجزئة المعاملة (hash) ورابط المستكشف. هكذا تتحول تذاكر دعم المدفوعات إلى عمليات بحث سريعة. يعيد mistKET لكل فاتورة confirmations وrequired_confirmations ومصفوفة transactions[] تتضمن الـ hash والمبلغ والحالة ورابط المستكشف.
6. تثبيت سعر الصرف وعملات التسعير
أنت تسعّر بالعملة التقليدية والعميل يدفع بالعملات الرقمية. اسأل عن عملات الفيات المقبولة وعن المدة التي يبقى فيها السعر المعروض ثابتًا. يقبل mistKET الأسعار بـ USD وEUR وTRY وRUB وGBP وAED (أو مباشرةً برمز العملة الرقمية)، ويثبّت السعر طوال عمر الفاتورة، ويتيح لك ضبط هذا العمر بين 5 و1,440 دقيقة لكل فاتورة.
7. اختيار الشبكة
هل يمكنك تحديد الشبكة في استدعاء الـ API، أم تترك للعميل اختيارها في الصفحة المستضافة؟ كلاهما مفيد: التحديد المسبق يناسب البوتات والمسارات المؤتمتة، وترك الاختيار للعميل يقلّل الدفع على شبكة خاطئة. يدعم mistKET الطريقتين عبر pay_currency + network أو asset_id، ويعيد GET /assets القيمة available: false عندما لا يتوفر عنوان شاغر على شبكة ما. اليوم USDT على TRON (TRC-20) مفعّل، وتُفعَّل أصول وشبكات إضافية لكل تاجر عند الطلب. راجع USDT TRC20 مقابل ERC20 لتعرف لماذا تُعد TRON الخيار الافتراضي الشائع.
8. Webhooks موقّعة ومُعاد إرسالها وقابلة للتتبع
الـ webhooks هي المكان الذي تتعطل فيه معظم عمليات الربط. افحص أربعة أمور: أن الحمولة موقّعة، وأن هناك طابعًا زمنيًا لرفض عمليات التسليم القديمة، وأن عمليات التسليم الفاشلة يُعاد إرسالها لساعات (لا لثوانٍ)، وأن لكل عملية تسليم معرّفًا تستخدمه لإزالة التكرار. يوقّع mistKET الـ webhooks بسرّ webhook منفصل، ويرسل الترويستين X-Mistket-Delivery وX-Mistket-Event، ويعيد المحاولة عند أي استجابة غير 2xx بعد 10 ثوانٍ و30 ثانية ودقيقتين و10 دقائق و30 دقيقة وساعة وساعتين و3 ساعات، مع ظهور سجل التسليم في لوحة التحكم. يتناول مقالنا عن webhooks الدفع بالعملات الرقمية تصميم المعالج بالتفصيل.
9. أخطاء وحدود طلبات موثّقة
يجب أن تعرف مسبقًا كيف يبدو خطأ التوقيع أو حظر الـ IP أو خطأ التحقق من البيانات. يعيد mistKET جسمًا ثابت الصيغة { "success": false, "error": … } مع تفاصيل لكل حقل في أخطاء التحقق، ويستخدم رموزًا قياسية (401 و403 و404 و422 و429 و503)، ويوثّق حدّه: 120 طلبًا في الدقيقة لكل مفتاح API.
10. ضوابط على مستوى الشبكة
قائمة السماح بعناوين IP تعني أن المفتاح المسرَّب لا فائدة منه من أي مكان سوى خوادمك. يتيح لك mistKET ضبطها في لوحة التحكم، وتحصل الطلبات القادمة من عناوين أخرى على 403. ومع الطلبات الموقّعة والنوافذ الزمنية القصيرة، يُغلق ذلك أكثر مسارات الهجوم شيوعًا.
11. لا ارتباط إجباري بـ SDK
حزم SDK مريحة إلى أن تتأخر عن إصدار لغتك البرمجية. الـ API المبني على HTTPS وJSON ببساطة، حيث التوقيع مجرد استدعاء HMAC واحد، يعمل من PHP أو Node.js أو Python أو Go أو سكربت shell. ينشر mistKET عملاء جاهزين للنسخ واللصق بلغات PHP وNode.js وPython في توثيق الـ API، لكن لا شيء منها إلزامي.
12. مسار يدوي لغير المطورين
حتى الأنشطة التي تعتمد على الـ API أولًا تحتاج أحيانًا إلى إصدار فاتورة لعميل لمرة واحدة. تأكد أن الفواتير يمكن إنشاؤها أيضًا من لوحة تحكم ومشاركتها كرابط، حتى لا يضطر فريقا المبيعات والدعم إلى الاستعانة بالمطورين. في mistKET، الفواتير نفسها متاحة في لوحة التاجر، وكل صفحة دفع مستضافة تعمل بوصفها رابط دفع.
GET /invoices/{uuid} وقارن. بذلك تتحقق من التوقيع ومعالج الـ webhook والمطابقة دفعة واحدة.علامات تحذيرية عند تقييم API للدفع بالعملات الرقمية
- Webhooks غير موقّعة أو webhooks «محمية» برابط سري فقط.
- لا توجد طريقة لجلب الفاتورة بعد إنشائها.
- لا توجد حالة للدفع الناقص أو الزائد — فتنتهي الحالات الاستثنائية في محادثات الدعم.
- إعادة المحاولة لبضع دقائق فقط، أو غياب سجل التسليم.
- حدود طلبات وصيغ أخطاء غير موثّقة.
- تسعير غير واضح لكل معاملة — قارن مع دليلنا عن رسوم بوابات الدفع بالعملات الرقمية.
كيف تحصل على وصول إلى API mistKET؟
يقبل فريق mistKET التجار بنفسه: راسل @mistnetwork على Telegram بموقعك الإلكتروني ونوع نشاطك وحجم المعاملات المتوقع. بعد الموافقة تُنشئ مفتاح الـ API والسرّ وإعدادات الـ webhook في لوحة التاجر. يستغرق الربط المعتاد فترة بعد الظهر.
راجع قسم المطورين والأسعار ومرجع الـ API الكامل قبل أن تبدأ.
