سجل التغييرات

أصبح لكل تدوينة وصفحة توثيق ومرجع API نسخة Markdown نظيفة يمكنك إرسالها إلى ChatGPT أو Claude أو وكيل IDE المفضل لديك بنقرة واحدة.

النسخ لنموذج LLM

ستجد زرًا جديدًا بجوار العنوان في كل تدوينة وصفحة توثيق. يفتح الزر قائمة منسدلة تتضمن أربعة اختصارات: نسخ الصفحة بصيغة Markdown، وعرضها بصيغة Markdown، وفتحها في ChatGPT، وفتحها في Claude. يملأ الخياران الأخيران المحادثة مسبقًا بعنوان URL لنسخة Markdown، ليتمكن النموذج من التعامل مع المحتوى الفعلي، بدلًا من لقطة شاشة لصفحة HTML.

مرجع API بصيغة Markdown

أصبح مرجع API الكامل متاحًا على /api/docs.md، ويتم إنشاؤه من مواصفات OpenAPI الفعلية. ألصق عنوان URL في أي LLM واسأل: “كيف أنشئ عملية دفع مع تحديد القناة المنسوب إليها؟”، وستحصل على إجابة مستندة إلى المحتوى بدلًا من هلوسة.

تتوفر نسخ Markdown من صفحات التوثيق في المسار نفسه مع إلحاق .md به، مثل /docs/getting-started.md. تمت فهرستها جميعًا في llms.txt لاستخدامها من قبل وكلاء IDE.

كل معاملة يرسلها العميل ضمن دفعة واحدة باتت تُسجَّل كصف منفصل، وتظهر في كل مكان تنظر فيه إلى تلك الدفعة: صفحة الدفع العامة، لوحة تحكم التاجر، صفحة تفاصيل المسؤول، وحمولة الـ webhook.

لماذا هذا مهم

كان حقل tx_hash القديم يحتفظ بهاش واحد فقط. إذا دفع العميل أقل من المطلوب ثم أكمل النقص لاحقاً، كنت ترى المعاملة الأخيرة فقط. الآن ترى جميعها: المبلغ، الوقت، محفظة الدافع (حيث ينطبق)، ورابط إلى tonviewer.

بالنسبة لمدفوعات TON عبر المحفظة المؤقتة (ephemeral)، يسحب مراقب الـ cron كل أثر إيداع من TonAPI ويخزنه في جدول جديد payment_deposits. تتوفر البيانات لحظة وصول الإيداع.

مصفوفة payer_deposits الجديدة

أُضيفت إلى:

• GET /api/payments/:id (العامة، صفحة دفع العميل) — source_address محذوف.
• GET /api/merchant/payments/:id (لوحة تحكمك / واجهة headless) — يتضمن source_address.
• GET /api/admin/payments/:id — نفس الشيء.
• حمولة الـ webhook — نفس الشيء.

كل عنصر:

{
  "tx_hash": "fa67b42d...46d77c5",
  "amount": "1035691177",
  "amount_human": "1.04 TON",
  "received_at": 1779091349,
  "source_address": "UQABCxyz...EnD"
}

مرتبة من الأحدث إلى الأقدم. مصفوفة فارغة عند عدم وصول أي إيداع بعد.

tx_hash مهمل

حقل tx_hash الأعلى مستوى على كائن الدفعة يبقى موجوداً للتوافق العكسي، ويحمل الآن أحدث هاش دفع. التكاملات الجديدة ينبغي أن تقرأ payer_deposits[0].tx_hash بدلاً منه. توثيق OpenAPI على mutopay.com/api/docs يضع الحقل ضمن المهملات.

أين تراه

• صفحة دفع العميل: يظهر قسم “معاملاتك” أسفل عرض الحالة بمجرد وصول الأموال.
• لوحة تحكم التاجر: صف “Payer TX” في صفحة تفاصيل الدفع يعرض الآن كل إيداع مع مبلغه ووقته.
• لوحة المسؤول: قسم جديد “Payer Deposits” يجلس بين معلومات المحفظة المؤقتة وقائمة محاولات الـ sweep، مع عنوان الدافع الكامل على كل صف.

ملاحظة حول البيانات السابقة

فقط مدفوعات TON المكتملة بعد هذا الإصدار تملأ payer_deposits. المدفوعات الأقدم تستمر بعرض tx_hash واحد فقط مع مصفوفة إيداعات فارغة. السلاسل غير TON لا تزال تعرض هاشاً واحداً عبر الحقل القديم حتى تحصل على خط أنابيب إيداعات خاص بها.

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

القنوات التجريبية

عند إنشاء قناة من لوحة التحكم، يمكنك الآن اختيار تجريبي بدلاً من الإنتاج. القنوات التجريبية تُصدر مفاتيح API ببادئة ep_test_… (الإنتاج يستمر في إصدار ep_…)، والوضع دائم. للانتقال إلى الإنتاج، أنشئ قناة إنتاج منفصلة واستبدل المفتاح في بيئتك. نفس النموذج المتبع في sk_test_ / sk_live_ لدى Stripe.

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

محاكاة نتائج الدفع

افتح رابط دفع تجريبي تماماً كما يفعل العميل. يظهر شريط “TEST MODE” أعلى بطاقة الدفع مع أربعة أزرار: محاكاة الإكمال، والفشل، وانتهاء الصلاحية، والنقص في الدفع. النقر على أي منها يُطلق الـ webhook المقابل إلى الرابط المهيأ لديك: حمولة حقيقية موقّعة (X-MutoPay-Signature)، مع سلوك إعادة المحاولة الحقيقي، وحقل إضافي "test": true لتتمكن المعالجة لديك من التفرّع إن لزم. كذلك يُطلق redirect_url للعميل تماماً كما يحدث في الإنتاج.

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

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

الإرسال اليدوي للتحويلات المباشرة

يمكن للعملاء الآن الدفع عن طريق نسخ عنوان التاجر وإرسال المبلغ الدقيق من أي محفظة. دون الحاجة لربط المحفظة. يعمل مع المدفوعات من نفس التوكن ونفس الشبكة على جميع شبكات EVM وTON. يولّد النظام مبلغاً فريداً (بأرقام غبار عشوائية) لكل عملية دفع ويكتشف التحويل تلقائياً على السلسلة.

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

إشعارات البريد الإلكتروني

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

استعادة الدفع

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

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

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

واجهة الدفع Headless

نقطة نهاية جديدة POST /api/payments/headless تُرجع عنوان إيداع والمبلغ الدقيق في استدعاء واحد. مصممة للمرسلين الذين يعرفون بالفعل من أي شبكة وأي توكن يريدون الدفع: أنظمة الدفع الآلية والمنصات الشريكة والسكربتات وتطبيقات المحفظة التي تتحكم في واجهتها الخاصة.

تدعم المسارات المباشرة (نفس التوكن، نفس الشبكة) ومسارات swap/bridge المبنية على الإيداع. تدفقات الطلب الموقع (EIP-712 intents، معاملات swap على السلسلة) غير مدعومة في وضع headless. يجب على عمليات التكامل الرجوع إلى صفحة /pay/{id} المستضافة لتلك المسارات.

صفحة الدفع ولوحة التحكم بـ 5 لغات

صفحة /pay/:id ولوحة التحكم الكاملة للتاجر متاحة الآن بالإنجليزية والإسبانية والتركية والأرمنية والروسية. تكتشف الواجهة لغة المتصفح تلقائياً وتتذكر الاختيار عبر الزيارات. محددات اللغة موجودة في تذييل صفحة الدفع، وتذييل صفحة Pay Me، والشريط الجانبي للوحة التحكم.

تحسينات الموثوقية

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

يضيف هذا الإصدار الوصول البرمجي بدون متصفح، تتبع مبالغ التسوية الدقيقة، رموز QR لمدفوعات الإيداع، وجولة من التعزيزات الأمنية.

تغيير جذري: تغيير مسار API

انتقلت جميع نقاط النهاية من /api/dashboard/* إلى /api/merchant/*. المسارات القديمة لم تعد تعمل. حدّث عمليات التكامل لديك.

مفتاح API الرئيسي

يمكن للتجار الآن إنشاء مفتاح API رئيسي (بادئة msk_) من لوحة التحكم → الإعدادات. هذا المفتاح يصادق على جميع نقاط /api/merchant/* (إنشاء المدفوعات، إدارة القنوات، ضبط التسوية)، بدون جلسة متصفح. مفيد للخدمات الخلفية والسكربتات.

إدارة المفتاح الرئيسي (الإنشاء، التدوير، الإلغاء) تتطلب تسجيل دخول عبر المتصفح. المفتاح الرئيسي لا يمكنه تدوير أو إلغاء نفسه.

مبلغ التسوية في الـ Webhooks

حمولة الـ webhook تتضمن الآن dest_amount وdest_decimals: العدد الدقيق من التوكنات التي وصلت إلى محفظتك. هذا ضروري لتسويات العملات غير المستقرة (مثل TON) حيث amount_usd لا يخبرك بعدد التوكنات. اقسم dest_amount على 10^dest_decimals للحصول على الرقم المقروء.

رموز QR لمدفوعات الإيداع

العملاء الذين يدفعون عبر الإيداع (مسارات Rubic عبر الشبكات، TON، Tron) يرون الآن رمز QR قابل للمسح فوق حقول النسخ. روابط ذكية حسب الشبكة: EIP-681 لـ EVM، وton://transfer مع المذكرة لـ TON، وSolana Pay لـ Solana، وBIP-21 لـ BTC.

صفحة تعديل القناة

لكل قناة الآن صفحة تعديل مخصصة في /dashboard/channels/:id مع أقسام للعلامة التجارية، رابط webhook، إعدادات التسوية، تدوير مفتاح API، ومنطقة خطر لإلغاء الوصول.

قناة صفحة “ادفع لي”

إعداد صفحة “ادفع لي” الآن ينشئ تلقائياً قناة مخصصة لها. هذا يمنح صفحتك علامة تجارية وتسوية وwebhook مستقلة عن قنواتك الأخرى.

موثوقية الـ Webhooks

مهمة cron جديدة تُطلق webhooks لأي دفعة اكتملت عبر استطلاع الحالة المباشر ولكن تم تخطي webhook-ها بصمت. لا مزيد من الإشعارات المفقودة.

الأمان

• تحديد معدل تسجيل دخول المسؤول (5 محاولات / 15 دقيقة لكل IP)
• تقييد CORS على mutopay.com + localhost
• رأس Content-Security-Policy على جميع الصفحات
• تشفير AES-256-GCM لمفاتيح API المخزنة
• حماية من إعادة التوجيه المفتوح على روابط العودة

أصبح بإمكان التجار الآن إنشاء وإدارة قنوات API مباشرةً من لوحة التحكم، دون الحاجة لإضافة WooCommerce. كما يمكن لكل قناة أن تمتلك وجهة تسوية مستقلة عن الإعداد الافتراضي للحساب.

إنشاء القنوات من لوحة التحكم

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

هذه هي الطريقة الأسهل لدمج MutoPay في أي واجهة متجر مخصصة أو تطبيق موبايل أو خدمة خلفية دون المرور بعملية OAuth.

تسوية مستقلة لكل قناة

يمكن الآن لكل قناة امتلاك شبكتها الخاصة وعملتها وعنوان محفظتها للتسوية. إذا لم يُحدَّد تجاوز، تستخدم القناة الإعداد الافتراضي لحسابك. تُدار التجاوزات مباشرةً في بطاقة القناة: انقر «تجاوز» لتعيين واحد، أو أيقونة القلم للتعديل، أو «إزالة التجاوز» للرجوع إلى الإعداد الافتراضي.

الحقول الثلاثة (الشبكة والعملة وعنوان المحفظة) تُحفظ وتُحذف دائمًا كمجموعة واحدة، مما يمنع أي تعارض في الإعدادات.

تعديل القنوات مباشرةً

يمكن الآن تعديل أسماء القنوات وروابط Webhook مباشرةً. انقر أيقونة القلم بجانب أي حقل وعدِّله واحفظ دون مغادرة الصفحة.

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

تبسيط الإعداد الأولي

يدمج تدفق الإعداد الأولي الجديد خطوتَي اختيار الشبكة/العملة وعنوان المحفظة في خطوة واحدة. تُضبط جميع إعدادات التسوية معًا في نموذج واحد وتُحفظ في طلب API واحد.

واجهة API

أربعة نقاط نهاية جديدة في لوحة التحكم تدعم هذه المزايا:

الطريقة	المسار	الوصف
POST	/api/dashboard/channels	إنشاء قناة يدوية؛ تُرجع { channel, api_key }
PATCH	/api/dashboard/channels/:id/webhook-url	تحديث رابط Webhook
PUT	/api/dashboard/channels/:id/settlement	تعيين تجاوز التسوية للقناة
DELETE	/api/dashboard/channels/:id/settlement	إزالة التجاوز (الرجوع إلى الإعداد الافتراضي)

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

روابط «ادفع لي»

يحصل كل تاجر على صفحة شخصية على mutopay.com/pay/@اسمك. يُدخل الزوار أي مبلغ وملاحظة اختيارية. مفيد للإكراميات والفواتير الحرة والطلبات المفتوحة. أعِدَّ صفحتك من لوحة التحكم ← الإعدادات ← صفحة «ادفع لي».

تصميم جديد

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

دعم الموبايل

كل صفحة (سواء كانت صفحة الدفع أو لوحة تحكم التاجر أو لوحة الإدارة) أصبحت الآن متجاوبة بالكامل. يمكن للعملاء والتجار استخدام MutoPay من أي جهاز.

وصف الدفعة

يمكن للتجار إرفاق وصف مقروء عند إنشاء دفعة (مثلاً “الطلب #1042 – قميص أزرق”). يظهر هذا الوصف على صفحة الدفع للعميل كسياق لما يدفع مقابله.

علامة القناة التجارية

يمكن لكل قناة تاجر الآن تجاوز الاسم التجاري الافتراضي والشعار المعروض للعملاء. مفيد للتجار الذين لديهم متاجر متعددة على حساب واحد. تُدار من لوحة التحكم ← القنوات ← تعديل القناة.

تغطي MutoPay الآن ثلاث شبكات رئيسية خارج EVM. يمكن للعملاء الدفع من محافظ TON وSolana وTron، ويمكن للتجار التسوية بعملاتها الأصلية.

شبكات جديدة

• TON: اقبل TON أو USDT على TON. يتصل المشترون بـ Tonkeeper أو MyTonWallet أو أي محفظة متوافقة مع TonConnect بنقرة واحدة. مثالي لروبوتات Telegram وتطبيقات mini-app.
• Solana: ادفع بأي رمز SPL، وسوِّ بعملة USDC الأصلية على Solana. دعم Phantom وBackpack.
• Tron: اقبل وسوِّ USDT-TRC20، أكثر منصات العملات المستقرة تداولاً في الأسواق الناشئة.

مقارنة عروض الأسعار

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

تدفق الإيداع اليدوي

بالنسبة للمسارات التي لا يمكننا توقيعها مباشرةً (NEAR Intents وغيرها من الجسور القائمة على النية)، تعرض صفحة الدفع عنوان إيداع قابلًا للنسخ ومبلغًا دقيقًا، ثم تتقدم تلقائيًا عند وصول الإيداع.

أحداث Webhook جديدة

• payment.kyc_required: وضع مزود التوجيه تعليقًا مؤقتًا أثناء قيام المشتري بالتحقق من هويته. لا حاجة لإجراء من التاجر؛ حدث payment.completed أو payment.failed اللاحق هو الإشارة النهائية.
• payment.needs_manual_check: أرجع المزود حالة غير متوقعة. سيحقق فريق عمليات MutoPay قبل أن تصل الدفعة إلى حالة نهائية.

كل دفعة تصل الآن إلى نتيجة محددة. لا يمكن لأي دفعة أن تتوقف بصمت في حالة pending.

صفحة الدفع

ربط المحفظة يتدفق الآن مباشرةً إلى الدفع. لا حاجة إلى نقرة ثانية بعد الاتصال.

يمكن الآن إنشاء المدفوعات بأي عملة من أكثر من 50 عملة تقليدية. يُحوّل المبلغ إلى USD بأسعار صرف البنوك المركزية اللحظية عند إنشاء الدفعة.

الميزات

• أكثر من 50 عملة تقليدية: سعّر بالـ EUR أو GBP أو SAR أو AED أو JPY أو AMD وغيرها. التحويل يتم على الخادم باستخدام أسعار من Frankfurter API، المصدرة من أكثر من 30 بنكًا مركزيًا.
• أسعار صرف قابلة للتدقيق: كل دفعة تخزّن المبلغ الأصلي والعملة وسعر الصرف المستخدم عند الإنشاء. مرئية في لوحة التحكم ولوحة الإدارة وحمولات Webhook.
• عملة WooCommerce التلقائية: إضافة MutoPay ترسل عملة متجرك تلقائيًا الآن. متجر EUR ينشئ مدفوعات EUR بدون أي إعداد إضافي.
• API متوافق مع الإصدارات السابقة: حقل amount_usd الموجود يستمر بالعمل. حقلا amount + currency الجديدان إضافيان.
• تخزين مؤقت مرن للأسعار: أسعار الصرف مخزنة في Cloudflare KV بفترة تحديث ساعتين واحتياطي 24 ساعة، لتستمر المدفوعات بالعمل حتى عند عدم توفر مزود الأسعار مؤقتًا.

يسعدنا إطلاق MutoPay v1.0: بوابة الدفع بالعملات الرقمية التي تحول أي عملة إلى عملات مستقرة.

الميزات

• API الدفع: أنشئ روابط دفع بطلب POST واحد
• دعم متعدد الشبكات: Ethereum وPolygon وArbitrum وBase وOptimism وAvalanche وBNB Chain
• أكثر من 1,000 عملة: اقبل أي عملة واستلم دائمًا USDC أو USDT أو DAI
• ربط عبر الشبكات: توجيه تلقائي عبر أفضل بروتوكول متاح
• لوحة تحكم التاجر: راقب المدفوعات وأدر مفاتيح API وخصص webhooks
• لوحة الإدارة: تحليلات شاملة للمنصة وإدارة التجار وتعديل الرسوم
• إشعارات Webhook: موقعة بـ HMAC-SHA256 مع إعادة محاولة تلقائية وتراجع أسي
• حفظ ذاتي: الأموال تصل مباشرة إلى محفظة التاجر