محفظة التمويل

يستهدف هذا الدليل Agent Java SDK v0.3.0، Java 8+، والعقد العام الموسوم. يتم تشغيل الأمثلة في الواجهة الخلفية للشريك بعد تهيئة client في بداية سريعة.

مثال المتطلبات الأساسية

تشترك مقتطفات Java في هذه الواردات. قم بتهيئة client باستخدام البدء السريع واحصل على platformUserId من الرابط المحفوظ. يجب استبدال معرفات المستخدم/الطلب بالقيم الثابتة الخاصة بك.

import com.sixmm.agent.*;
import com.sixmm.agent.model.*;
import java.util.*;

استعلامات المحفظة والتحويلات

التمييز بين المحافظ الثلاث

محفظة	مصدر الرصيد	يستخدم
محفظة المستخدم الخاصة بالتاجر	النظام المحاسبي الخاص بالتاجر	الرصيد المتاح للمستخدم على جانب التاجر
تمويل المنصة	`queryUserAssets` من `funding`	أموال تداول الثواني والتحويل المتبادل للتمويل/العقد
عقد المنصة	حقل أصول العقد `queryUserAssets`	هامش العقد الدائم والرصيد القابل للتحويل

queryAccount الاستعلام عن حساب هامش منصة التاجر، وليس محفظة مستخدم التاجر. لا تحتوي هذه الواجهة على معلمات environment ولا يمكن الاستعلام عنها كأصل مستخدم تمت محاكاته.

الاستعلام عن محفظتي النظام الأساسي للمستخدمين المحاكيين:

QueryUserAssetsResponse assets = client.queryUserAssets(
        QueryUserAssetsRequest.of(platformUserId)
                .withFunding()
                .withEnvironment(ExecutionEnvironment.SIMULATED));

الواجهة: POST /v1/agent/query-user-assets. يتم طلب التمويل فقط عندما includeFunding=true; يتم استخدام دلالات الاستعلام عن أصول العقد الأصلي بشكل افتراضي.

مجالات الاستجابة	معنى
`walletBalance`، `availableBalance`، `frozenMargin`، `usedMargin`، `isolatedMargin`	المبالغ المتعلقة بمحفظة العقد
`funding.assetCode`	حاليا USDT
`funding.availableAmount`، `heldAmount`، `totalAmount`	التمويل المتاح والمشغول والمبلغ الإجمالي
`funding.materialized`	هل تم تحقيق حساب التمويل؟
`environment`	يتم تكرار هذا الحقل عندما يتم تمرير البيئة بشكل صريح؛ الطلبات القديمة التي تحذف البيئة لا تُرجع هذا الحقل.
`isSimulatedUser`	تصنيف الحساب؛ لا يمكن أن يحل محل اختيار بيئة التداول

يتم التعامل مع المبالغ كسلاسل أو BigDecimal، وليس float/double.

اتجاهات تحويل التمويل

إنشاء: POST /v1/agent/wallet-transfer، SDK walletTransfer.

`direction`	تدفق الصندوق	`transferAll`
`PARTNER_TO_FUNDING`	التاجر → تمويل المنصة	مبلغ ثابت فقط
`FUNDING_TO_PARTNER`	تمويل المنصة → التاجر	مبلغ ثابت فقط
`FUNDING_TO_CONTRACT`	نفس منصة البيئة التمويل → العقد	يدعم المبلغ الثابت أو جميع الأموال القابلة للسحب
`CONTRACT_TO_FUNDING`	عقد منصة البيئة نفسها → التمويل	يدعم المبلغ الثابت أو جميع الأموال القابلة للسحب

العملة الحالية تدعم فقط USDT. يجب أن يكون المبلغ الثابت عبارة عن سلسلة موجبة تحتوي على ما يصل إلى 8 منازل عشرية ولا يمكن استخدام التدوين العلمي. عندما transferAll=true، احذف amount وسجله كرد نهائي amount؛ “الكل” يشمل فقط الأموال القابلة للسحب.

مثال: يقوم التاجر بتحويل 10 USDT إلى التمويل المحاكى. قم أولاً بحفظ أمر العمل والبيئة في نظام التاجر، ثم أرسل الطلب:

String fundingOrderNo = "SIM-FUNDING-20261010-000001";
WalletTransferResponse transfer = client.walletTransfer(
        WalletTransferRequest.of(fundingOrderNo, "merchant-user-001",
                "PARTNER_TO_FUNDING", "10.00000000", false)
                .withEnvironment(ExecutionEnvironment.SIMULATED));

التمويل تحويل جميع الأموال التي يمكن تحويلها إلى العقد المحاكى:

WalletTransferResponse move = client.walletTransfer(
        WalletTransferRequest.of("SIM-F2C-20261010-000001", "merchant-user-001",
                "FUNDING_TO_CONTRACT", null, true)
                .withEnvironment(ExecutionEnvironment.SIMULATED));

يجب أن تستمر نفس العملية في استخدام agentOrderNo الأصلي؛ تستخدم العمليات المختلفة والبيئات المختلفة أرقام طلبات مختلفة. سيتم رفض تغيير المبلغ أو المستخدم أو الاتجاه أو البيئة بنفس رقم الطلب. لا يمكن إجراء تحويلات التمويل/العقود إلا في نفس البيئة، ولا يمكن تحويل الأموال المحاكاة إلى أموال حقيقية.

تأكيد النتيجة واسترداد نتيجة غير معروفة

يتم تمثيل استجابات التمويل بواسطة status أو SUCCESS أو PROCESSING أو FAILED، ويتم إرجاعها orderNo، direction، currency، amount، resultCode، وما إلى ذلك. code=0 يعني فقط أن الطلب تمت معالجته بنجاح وتحتاج إلى الاستمرار في الحكم على status.

نتيجة	معالجة التاجر
`SUCCESS`	استكمال المعالجة المحاسبية المحلية على أساس المبلغ الفعلي
`PROCESSING`	احتفظ بها محليًا للتأكيد وتحقق من الطلب الأصلي
HTTP انتهت المهلة، خطأ في الشبكة، لا يمكن تحليل النتيجة	تعتبر النتيجة مجهولة ويتم الاستعلام عن الأمر الأصلي؛ لا يمكن تحديده بشكل مباشر على أنه فاشل أو إنشاء أمر جديد والمحاولة مرة أخرى.
تم تحديد `FAILED`	تحرير الحجز المحلي حسب نتيجة الفشل الواضحة؛ إنشاء أمر عمل جديد عندما يلزم بدء العمل مرة أخرى

يستخدم استعلام التمويل الواجهة المخصصة POST /v1/agent/wallet-transfer-status:

WalletTransferResponse recovered = client.queryWalletTransfer(
        WalletTransferQueryRequest.of(fundingOrderNo)
                .withEnvironment(ExecutionEnvironment.SIMULATED));

استخدم نقطة النهاية المخصصة هذه لاستعادة عملية التمويل الأصلية؛ queryOrder لا يمكن استبداله. احفظ البيئة الأصلية وقم بتمريرها بشكل صريح أثناء عملية الاسترداد. إذا تم حذف environment من wallet-transfer-status، فسيستخدم الخادم البيئة المحفوظة في الطلب الأصلي، بما في ذلك الطلبات التي تمت محاكاتها. ترجع البيئة المتعارضة بشكل صريح 102002 (order environment mismatch). عندما يحذف المتصل البيئة، فإن الاستجابة تحذف environment أيضًا؛ وهذا لا يعني أن الأمر الأصلي هو أمر إنتاج.

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

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

يستمر transfer، transferAllOut، reverse، queryOrder، listOrders، في معالجة عملية نقل العقد الأصلي. queryOrder يستعلم عن أوامر تحويل الأموال، listOrders عبارة عن قائمة تسوية التحويلات؛ بدلاً من، الاستعلامات الدائمة تستخدم لأوامر التداول الدائمة.

تستخدم استجابة التمويل الأصلية orderStatus؛ تستخدم استجابة التمويل status، فلا تخلط بينهما. تم التحقق من النقل الأصلي Webhook باستخدام X-Agent-Timestamp، X-Agent-Nonce، X-Agent-Signature، ونص التوقيع الأصلي هو timestamp + nonce + rawBody؛ يتم التحقق أولاً من نص الطلب الأصلي، ثم يتم إلغاء تسلسله ويصبح غير فعال. تحتوي إشعارات البيئة المحاكاة الصريحة على environment=SIMULATED، وتظل إشعارات الإنتاج متوافقة مع الحقول القديمة. يجب التحقق من المبلغ ورقم الطلب والحالة والبيئة من خلال أمر العمل المحلي.

المصدر والأدلة ذات الصلة

حقول طلب التمويل

مجال	مطلوب	معنى
`agentOrderNo`	نعم	رقم طلب الشريك الفريد عالميًا؛ تستمر قبل الإرسال.
`agentUserId / platformUserId`	واحد	تحديد المستخدم المقيد؛ إذا تم توفير كلاهما فيجب أن يتطابقا.
`direction`	نعم	أحد الاتجاهات الأربعة الموثقة أعلاه.
`currency`	الافتراضي USDT	يتم دعم USDT فقط.
`transferAll`	الافتراضي كاذبة	فقط التحويلات الداخلية للتمويل/العقد تدعم صحيح.
`amount`	شرطي	سلسلة عشرية موجبة لنقل ثابت؛ احذف لـ transferAll=صحيح.
`environment`	خياري	الإنتاج عند حذفه لنقل جديد؛ SIMULATED يختار الأموال المحاكاة.

مجالات استجابة التمويل

مجال	معنى
`orderNo`	معرف العملية التي تم إرجاعها؛ الاحتفاظ بها بجانب رقم طلب الشريك الأصلي.
`status`	SUCCESS / PROCESSING / FAILED; يحدد اكتمال الأعمال.
`direction / currency`	تأكيد اتجاه النقل والأصول.
`amount`	المبلغ الفعلي المحول كسلسلة.
`transferAll`	ما إذا كانت هذه العملية طلبت جميع الأموال القابلة للسحب.
`agentUserId / platformUserId`	هوية المستخدم التي تم إرجاعها؛ مقارنة مع الطلب المحفوظ.
`resultCode`	تفاصيل نتيجة العملية؛ الاحتفاظ بالمصالحة والدعم.
`environment`	ردد عندما زوده المتصل صراحة؛ الغياب ليس دليلاً على الإنتاج للاستعلام عن حالة الطلب الأصلي.