وثائق الواجهة البرمجية
توثيق تكامل واجهة Tovanix البرمجية المفتوحة، مقسّم حسب الخدمة: دفع متعدد السلاسل, تأجير الطاقة, SMTP API, API الذكاء الاصطناعي, بطاقة افتراضية, البريد الإلكتروني, تخزين الكائنات, التحقّق ومخاطر المعاملات, الوصول عبر MCP. المختبرات: استوديو العقود, إعادة تشغيل الدفع, مختبر توجيه الذكاء الاصطناعي.
- دفع متعدد السلاسل
- تأجير الطاقة
- SMTP API
- API الذكاء الاصطناعي
- بطاقة افتراضية
- البريد الإلكتروني
- تخزين الكائنات
- التحقّق ومخاطر المعاملات
- الوصول عبر MCP
USDT / USDC / ETH / TRX / BTC · TRON / EVM / Bitcoin · توقيع مزدوج HMAC-SHA256 للدفع + RSA-2048 للصرف · إشعار تسوية خلال 30 ثانية
تكامل بـ3 خطوات
- 1 سجّل حسابًا + أنشئ تطبيقًا احصل على app_id وapp_key من «تطبيقاتي» ثم اضبط notify_url سجّل مجانًا →
- 2 نفّذ أداة التوقيع يستخدم الدفع HMAC-SHA256 المتماثل، والصرف RSA-2048 غير المتماثل. تغلّف SDK الرسمية الاثنين بأمثلة كاملة عبر اللغات.
- 3 اختر وضعًا ونفّذ أول معاملة واحد إلى واحد، عنوان مربوط بالمستخدم مناسب للمحافظ والشحن · تدوير، عنوان لكل طلب مناسب لدفع التجارة الإلكترونية
نظرة عامة
تدعم Tovanix وضعي دفع يمكن تفعيلهما معًا:
وضع واحد إلى واحد
يربط المستخدم عنوانًا ثابتًا، وتُدفع إشعارات كل دخل تلقائيًا. مناسب للشحن والتحصيل.
- يربط المستخدم عنوان استقبال ثابتًا
- إشعارات دخل في الوقت الفعلي
- يدعم الدفع المتكرّر
- تحقّق مستقل من التوقيع
وضع التدوير
يُخصّص العنوان ديناميكيًا عند إنشاء الطلب ويُعاد للمجموعة عند انتهائه. مناسب للدفع لمرة واحدة.
- تخصيص عنوان ديناميكي
- التحكّم بانتهاء الطلب
- تحويل تلقائي بسعر الصرف
- صفحة الدفع
خوارزمية التوقيع
تستخدم إشعارات واحد إلى واحد webhook_secret للتوقيع، وليس app_key.
1. استخدم HMAC-SHA256 بالسر كمعامل مفتاح HMAC، لا بإلحاقه بالسلسلة
2. التوقيع سلسلة سداسية من 64 حرفًا صغيرًا؛ المقارنة حسّاسة لحالة الأحرف
3. عند الإنشاء يجب أن يكون amount بمنزلتين، مثل 100.00، وtimeout سلسلة عدد صحيح؛ حتى لو حُذف timeout يجب توقيعه بقيمة timeout=0 لأن الخادم يضمّه دائمًا
4. تُستبعد الحقول الفارغة من حساب التوقيع
الحماية من إعادة الطلب
لمنع إعادة إرسال الطلبات التي تم اعتراضها، يمكن أن تحمل الطلبات الموقّعة طابعًا زمنيًا وقيمة nonce؛ وكلاهما يدخل في التوقيع. إغلاق الطلب وربط العنوان وإلغاء ربط العنوان تتطلب هذين الحقلين وتعيد 400 عند غيابهما؛ وهما اختياريان في بقية نقاط النهاية.
/api/v1/pay/close: يلزم timestamp وnonce. في /api/v1/pay/bind-address و/api/v1/pay/unbind-address يلزم sign_ts وnonce، ويقبل حقل الوقت اسم timestamp أيضًا. يستخدم /api/v1/pay/get-address حقل sign_ts اختياريًا. تستخدم نقاط الإنشاء والاستعلام والإعداد timestamp اختياريًا؛ بوجود الاثنين يُفحص الوقت وnonce، وبوجود أحدهما أو غيابهما يُفحص التوقيع فقط.
يجب أن يكون timestamp ضمن 300 ثانية من وقت الخادم؛ زامن عبر NTP. لا يُعاد nonce خلال 5 دقائق. يُرفض الوقت خارج النافذة أو nonce المكرّر بـ HTTP 400 للإنشاء والاستعلام و401 للباقي؛ ويبيّن message السبب.
ربط عنوان
POST /api/v1/pay/bind-address
خصّص عنوان دفع ثابتًا لمستخدم. يُعاد الحالي إن كان مربوطًا.
استعلام الربط
POST /api/v1/pay/get-address
استعلم عن عنوان الدفع المربوط بالمستخدم.
فك ربط عنوان
POST /api/v1/pay/unbind-address
فك ربط عنوان دفع المستخدم.
إنشاء طلب
POST /api/v1/pay/create
أنشئ طلب دفع؛ يخصّص النظام عنوان استقبال تلقائيًا.
حقول الرد
يقبل amount عددًا أو سلسلة: 100 أو "100". للتوقيع استخدم دائمًا منزلتين مثل "100.00".
استعلام طلب
GET /api/v1/pay/query
استعلم عن الحالة بمعرّف طلبك. تُرسل المعاملات عبر استعلام العنوان.
إغلاق طلب
POST /api/v1/pay/close
أغلق طلبًا غير مدفوع يدويًا لإعادة العنوان للمجموعة. يُغلق المعلّق فقط، status=0.
استعلام إعداد التطبيق
GET /api/v1/pay/app-config
استعلم عن الوضع والرموز المفعّلة وإعدادات الإشعار وغيرها دون كشف بيانات حسّاسة.
إشعار واحد إلى واحد
عند استقبال عنوان مربوط تحويلًا، يرسل النظام POST إلى notify_url المهيّأ.
تُوقّع الإشعارات بـ webhook_secret، ويُعرض أو يُجدّد في تفاصيل التطبيق.
حقول الإشعار
بعد الاستقبال أعد HTTP 200 أو {"code": 0}؛ وإلا تُعاد المحاولة حتى 10 مرات بتراجع أُسّي.
إشعار استدعاء الطلب
بعد دفع طلب تدوير يرسل النظام استدعاءً إلى notify_url.
تُوقّع الاستدعاءات بـ webhook_secret، ويُعرض أو يُعيّن مجددًا في تفاصيل التطبيق.
حقول الاستدعاء
أي رمز حالة 2xx يُعدّ تسليمًا، ولا يُفحص نص الاستجابة (إرجاع {"code": 0} مع حالة غير 2xx يبقى فشلًا). الحالة غير 2xx، وعدم الرد خلال 10 ثوانٍ، وفشل الاتصال، وإعادة التوجيه كلها تُعدّ فشلًا؛ تعيد المنصة المحاولة بعد 30 ثانية ودقيقة ودقيقتين و5 دقائق، ثم كل 10 دقائق، حتى 10 مرات. تحتفظ المحاولات بنفس notify_id لكنها تحمل sign_ts وnonce وتوقيعًا جديدة — أزل التكرار بالاعتماد على notify_id.
جلب سعر الصرف
GET /api/v1/rate
اجلب سعر الصرف الفوري بين عملتين
تحويل المبلغ
POST /api/v1/convert
حوّل مبلغًا بسعر الصرف الفوري
أسعار صرف دفعة
GET /api/v1/rates
استعلم عن أسعار عملات متعددة، رموز مفصولة بفواصل
جميع أسعار الصرف
GET /api/v1/rates/all
اجلب أسعار كل العملات المدعومة
أسعار العملات التقليدية
GET /api/v1/rates/fiat
اجلب الأسعار وفق عملة تقليدية أساس، أكثر من 30 عملة مجمّعة إقليميًا
حالة الطلب
تمرّ الطلبات بالحالات التالية:
رموز الأخطاء
رموز موحّدة لأخطاء API الدفع (/api/v1/pay/*)؛ ورموز الصرف في قسم المرجع.
نظرة عامة / متطلبات الصرف
واجهة Payout API هي جانب صرف الأموال في منتج المدفوعات متعددة السلاسل — ترسل برمجيًا الأصول التي جُمعت في المحفظة المركزية إلى عناوين خارجية. توقيع متبادل RSA-2048 + قائمة IP مسموحة + بث مؤجّل + اعتراض عبر إشعارات متعددة القنوات + رد تأكيد على السلسلة.
واجهة Payout API لا تصرف إلا الأصول المجمّعة في المحفظة المركزية ضمن وضع الحفظ لدى النظام. إذا كان تطبيق الدفع لديك يعمل بوضع الحفظ الذاتي — تصل الأموال مباشرة إلى عناوينك ولا تجمعها المنصة أبدًا — فلن ينشأ أي رصيد «مجمّع بانتظار الصرف»، ولذلك لا يمكن إجراء عمليات صرف عبر هذه الواجهة.
تفعيل في 4 خطوات
- افتح الدفع متعدد السلاسل → الصرف API في اللوحة
- أنشئ زوج RSA-2048 محليًا وارفع المفتاح العام
- اضبط إدخالًا واحدًا على الأقل في قائمة IP المسموحة (إلزامي)؛ ويمكنك اختياريًا ضبط قائمة عناوين مسموحة / حد لكل معاملة / مهلة تأخير للصرف
- فعّل المفتاح الرئيسي؛ يولّد النظام تلقائيًا زوج مفاتيح المنصة للحساب — انسخ المفتاح العام للمنصة إلى طرفك للتحقق من ردود callback
التوقيع · RSA-2048 للصرف
يجب أن تحمل جميع نقاط /api/v1/withdraw* ترويسات الطلب التالية. بخلاف HMAC المتماثل في واجهة الدفع، يستخدم الصرف RSA غير المتماثل — المنصة لا تحتفظ إلا بمفتاحك العام، فالخطر الوحيد هو تسرّب مفتاحك الخاص.
- X-API-Key — قيمة API Key لمفتاح API على المنصة (تحصل عليه من لوحة التحكم ضمن الأدوات والإعدادات ← إدارة API)؛ ويجب أن يملك المفتاح صلاحية withdraw
- X-Timestamp — unix حالي بالمللي ثانية؛ فرق الخادم ≤60 ثانية
- X-Nonce — nonce من نوع uuid لمرة، دون إعادة خلال 5 دقائق
- X-Withdraw-Signature — RSA-PKCS1v15-SHA256(caller_private_key, signString), Base64
قاعدة ربط سلسلة التوقيع
هنا BODY هو جسم HTTP الخام (سلسلة JSON كما هي حرفيًا — لا تُعد تسلسلها). في طلبات GET يكون BODY سلسلة فارغة.
إضافةً إلى توقيع RSA على مستوى الحساب وقائمة IP المسموحة على مستوى الحساب المذكورين أعلاه، يجب أن يملك مفتاح API المستخدم صلاحية withdraw، ويخضع لقائمته البيضاء الخاصة بعناوين IP المصدر: غياب الصلاحية يعيد 403 / 4032، وعنوان IP مصدر خارج القائمة البيضاء للمفتاح يعيد 403 / 4033. يُطبَّق الفحصان على /api/v1/withdraw و/api/v1/balance/withdrawable و/api/v1/fee/quote. المفاتيح التي كانت موجودة قبل هذا التغيير تملك صلاحية withdraw تلقائيًا ولا تتأثر؛ وللمفاتيح الجديدة اخترها من الأدوات والإعدادات ← إدارة API. يمكنك معرفة صلاحيات المفتاح عبر GET /api/v1/whoami (يُستدعى بـ X-API-Key + X-Secret-Key أو بتوقيع HMAC).
استدعاء نتيجة الصرف
يمكنك تمرير callback_url في الجسم عند إنشاء الطلب؛ وبعد اكتمال الصرف / فشله / إلغائه ترسل المنصة النتيجة بطلب POST إلى ذلك العنوان.
- يُوقَّع جسم callback بـالمفتاح الخاص للمنصة ويوضع التوقيع في الترويسة X-Platform-Signature
- يجب أن يتحقق طرفك من التوقيع بـالمفتاح العام للمنصة (يمكن نسخه من صفحة الإعدادات)؛ وخوارزمية التحقق مطابقة لاتجاه الطلب
- عند الفشل تُعاد المحاولة بتراجع زمني على الفترات 1m / 5m / 30m / 2h / 6h / 24h — 6 مرات إجمالًا — ثم يتوقف النظام ويحيل الأمر إلى المعالجة اليدوية
- يلزم HTTP 2xx؛ غيره فشل
ترويسات الطلب
- X-Timestamp — الطابع الزمني الحالي بصيغة unix بالمللي ثانية
- X-Platform-Signature — Base64(RSA-PKCS1v15-SHA256(المفتاح الخاص للمنصة، سلسلة التوقيع))
قاعدة ربط سلسلة التوقيع
PATH هو مسار callback_url (بدون النطاق وسلسلة الاستعلام)، وBODY هو نص الطلب المستلم كما هو — لا تُعِد تسلسله. تحقّق باستخدام المفتاح العام للمنصة من صفحة الإعدادات.
قيم status: completed / failed / failed_onchain / cancelled؛ المبالغ والرسوم سلاسل نصية؛ created_at وcompleted_at بالثواني بصيغة unix، و0 عند عدم وجود وقت إتمام. لا يتغير النص بين محاولات الطلب نفسه — أزل التكرار بالاعتماد على order_id.
بدء الصرف
POST /api/v1/withdraw
بعد إنشاء الطلب تكون حالته pending، بانتظار انقضاء مهلة التأخير قبل أن يبثّه عامل تلقائيًا. خلال هذه النافذة يمكنك إيقافه مؤقتًا / تعجيله / إلغاؤه من لوحة التحكم.
وصف الحقول
- chain — string — نعم — tron / eth / bsc / polygon / arbitrum / base / optimism / avax / xlayer / btc
- symbol — string — نعم — USDT / TRX / ETH وغيرها
- amount — string — نعم — حتى 18 منزلة؛ استخدم سلسلة لتجنّب أخطاء الفاصلة العائمة
- to_address — string — نعم — عنوان وجهة يجب إضافته إن فُعّلت القائمة
- memo — string — لا — وصف ≤500 حرف، يُرسل للمستخدم مع الإشعار
- callback_url — string — لا — عنوان النتيجة؛ لا استدعاء إن فارغ
- request_id — string — موصى به بشدة — مفتاح منع التكرار؛ نفسه للحساب نفسه يعيد الأصلي؛ إذا اختلفت السلسلة أو العملة أو العنوان أو المبلغ يُرجَع 409 ولا يُنشأ طلب بدونه لا توجد حماية من التكرار: إعادة المحاولة بعد انتهاء المهلة أو استجابة 5xx تُنشئ دفعة حقيقية ثانية.
حقول الرد
- order_id — string — معرّف السحب لاستعلام واحد
- status — string — الحالة الحالية للطلب، بالقيم نفسها الواردة في status_label ضمن نقطة الاستعلام. الطلب الجديد يكون pending (خُصم الرصيد، وبانتظار مهلة ضبط المخاطر والبث)؛ وإعادة إرسال request_id نفسه تعيد الحالة الفعلية للطلب، وقد تكون completed أو failed أو غيرهما.
- amount — string — مبلغ السحب كسلسلة
- fee — string — رسم متوقع مُثبّت وقت الطلب
- fee_mode — string — in_amount: من المبلغ، المستلم=amount−fee والخصم=amount؛ out_amount: منفصل، المستلم=amount والخصم=amount+fee
- delayed_until — string | null — موعد البث بعد تأخير المخاطر؛ null دون تأخير
استعلام حالة صرف واحد
GET /api/v1/withdraw/:id
تفاصيل للاستطلاع؛ يبقى الاستدعاء موصى به.
حقول الرد
- id — string — معرّف طلب السحب
- request_id — string — مفتاح التكرار المرسل
- chain / symbol — string — السلسلة / رمز العملة
- amount / expected_fee / fee_mode — string — المبلغ / رسم مُثبّت / وضع in_amount, out_amount
- to_address — string — عنوان الوجهة
- memo — string — مذكرة TAG/Memo
- status / status_label — int / string — رمز ونص الحالة؛ راجع قسمها
- tx_hash — string — بصمة السلسلة بعد البث
- fail_reason — string — السبب عند الفشل
- delayed_until / broadcast_at / confirmed_at / paused_at / cancelled_at — string | null — أوقات الخطة/البث/التأكيد/الإيقاف/الإلغاء؛ null إن لم تصل
- callback_url / callback_retry — string / int — عنوان الاستدعاء / عدد الإعادات
- callback_state — string — حالة callback: pending = لم يُستدعَ بعد أو قيد إعادة المحاولة، success = تم استلام 2xx، giveup = استُنفدت المحاولات، no_url = لم يُضبط callback
- created_at — string — وقت الإنشاء
استعلام الرصيد المتاح
GET /api/v1/balance/withdrawable
تعيد رصيد «المجمّع بانتظار الصرف» لهذا الحساب لكل سلسلة × لكل أصل. هذا الجزء وحده يمكن استخدامه للصرف عبر API.
بنية من مستويين: السلسلة ← رمز العملة ← الرصيد القابل للسحب (سلسلة نصية)؛ لا تُعاد إلا الإدخالات التي رصيدها أكبر من 0.
تقدير الرسوم
رسم ثابت مسبق يضبطه المسؤول لكل سلسلة ورمز، بأسلوب OKX.
حقول الرد
- chain / symbol / amount — string — المعاملات كما أُرسلت: chain / symbol / amount
- fee_amount — string — مبلغ الرسم
- fee_asset — string — أصل تسوية الرسم
مثال cURL كامل
مسار توقيع وطلب كامل، انسخه للطرفية للتجربة.
حالة الطلب · الصرف
آلة حالات pending → broadcasted → completed / failed_onchain، وبينها paused / cancelled / failed.
- 0 — pending — خُصم الرصيد؛ بانتظار المهلة ولم يُبث
- 1 — completed — تأكيد ناجح على السلسلة، مؤهّل للاستدعاء
- 2 — failed — فشل قبل البث، الرصيد مستردّ
- 3 — broadcasted — بُثّ وينتظر التأكيد
- 4 — failed_onchain — فشل بالسلسلة، عكس/تأخر تعدين طويل، استرداد الرصيد
- 5 — paused — أوقفه المستخدم يدويًا، قابل للاستئناف/الإلغاء
- 6 — cancelled — ألغاه المستخدم يدويًا، استرداد الرصيد
- 7 — broadcasting — جارٍ البث، مؤقت لمنع التكرار
رموز الأخطاء · API الصرف
- 400 — معامل خاطئ / نقص رصيد / مبلغ خارج حدود السلسلة والرمز / عنوان خاطئ
- 401 — مفتاح خاطئ / فرق وقت / nonce مستخدم / توقيع فاشل
- 403 — الصرف عبر API غير مفعّل للحساب / عنوان IP غير مدرج في قائمة الحساب المسموحة؛ أو أن مفتاح API لا يملك صلاحية withdraw (الرمز 4032) أو أن IP المصدر غير مدرج في القائمة البيضاء لذلك المفتاح (الرمز 4033)
- 404 — الطلب غير موجود
- 429 — طلبات كثيرة جدًا (حتى 10 في الثانية لكل حساب). يحمل الرد Retry-After: 1؛ انتظر ثانية واحدة وأعد المحاولة بقيمة request_id نفسها
- 5xx — خطأ منصة قابل للإعادة؛ استخدم request_id نفسه لمنع التكرار
ملاحظات أمان الصرف
- احمِ الخاص محليًا؛ يتيح تسرّبه الصرف باسمك
- يجب ضبط قائمة IP مسموحة قبل تفعيل الصرف عبر API (إلزامي)؛ ويُرفض أي IP غير مدرج فيها حتى مع توقيع صحيح
- يوصى بقائمة عناوين وتسجيل الوجهات المعروفة مسبقًا
- بعد تفعيل 2FA يمكن استخدامها للتعجيل/الإلغاء خلال المهلة
- للمبالغ الكبيرة، فكّر بتأخير ساعات لإتاحة الاعتراض اليدوي عبر الإشعارات
صفحات ذات صلة: مدفوعات مشفّرة متعددة السلاسل · واجهة API موحّدة لخدمات SMTP · خدمات الذكاء الاصطناعي
جارٍ التحميل…