Webhook الأحداث وتحذيرات التصفية

هذه الصفحة تتبع Agent Java SDK WEBHOOKS.md عند الالتزام fa6c7b6. هذا تحديث للوثائق فقط؛ لم يتم إصدار أي قطعة أثرية جديدة SDK تحتوي على أساليب مساعدة للتحذير.

تستخدم جميع أنواع الأحداث الأربعة رد الاتصال الفردي الذي تم تكوينه للتاجر URL (agents.webhook_url). إرسال على الجسم event؛ لا يلزم وجود تحذير منفصل URL. توضح الأمثلة بنية الحمولة ويجب عدم استخدامها لإدخال البيانات في بيئة اختبار.

الأحداث والعجز

حدث تحذير التاجر هو liquidation.warning؛ المستخدم WebSocket data.event يبقى LIQUIDATION_WARNING. أبقِ القناتين منفصلتين.

تم استخدام إشعارات التجار التاريخية LIQUIDATION_WARNING. تحتفظ الحمولات المجمدة بجسمها الأصلي عند إعادة المحاولة، لذلك يجب على أجهزة الاستقبال التعرف على كلا الاسمين. إذا كانت سجلات الأعمال الحالية تستخدم بادئة مفتاح تحذير بأحرف كبيرة، فاحتفظ بالمفتاح الأصلي أو تحقق من كلا المفتاحين أثناء الترحيل لتجنب معالجة الإشعار مرة أخرى.

WebhookVerifier.idempotencyKey الحالي يستخرج فقط orderType:orderId:targetStatus لأحداث الأموال ويعيد سلسلة فارغة لحمولات التحذير. لم يتم إصدار أي قطعة أثرية جديدة SDK تحتوي على أساليب مساعد تحذير مع تحديث الوثائق هذا. استمر في استخدام طريقة verify الحالية للتحقق من نص التحذير الأولي. بعد التحقق من التوقيع والملكية، يجب أن يتعرف رمز العمل التجاري على اسمي الحدثين، ويتحقق من أن notificationId عبارة عن سلسلة عدد صحيح عشري موجب، وينشئ liquidation.warning:<notificationId>. لا تستخدم مطلقًا مفتاح إلغاء البيانات المكررة الفارغ أو تطلب تحذيرات تحتوي على حقول أوامر الأموال.

استمر في إلغاء البيانات المكررة داخل نطاق التاجر وenvironment والتزم بها تلقائيًا في معالجة الأعمال. FIRST / UPGRADE / REMINDER مع قيم notificationId مختلفة تكون مستقلة؛ لا تتخلص منها عن طريق التجميع حسب المستخدم أو الحلقة أو eventType. المفتاح الفارغ يعني أنه لا يمكن استخراج هوية صالحة. يقوم SDK بإرجاع مفتاح مساعد فقط؛ ولا يحتفظ بالسجلات أو يقوم بمعالجة الأعمال. تسجيل نفس الهوية مع هيئة مختلفة كالصراع؛ لا تكتب فوق الجسم المعالج.

حقول التحذير من التصفية والأمثلة

{
  "event": "liquidation.warning",
  "notificationId": "68460336",
  "eventType": "FIRST",
  "severity": "NORMAL",
  "occurredAt": 1791875870804,
  "object": {
    "type": "CROSS",
    "symbol": "",
    "side": "",
    "positionId": ""
  },
  "episode": "3",
  "stateVersion": "9",
  "riskRatio": "0.29133109",
  "minLargePositionValue": "0.20000000",
  "liquidationHighRiskThreshold": "0.40000000",
  "configVersion": "8",
  "environment": "PRODUCTION",
  "agentId": "16",
  "agentCode": "DEMO",
  "agentUserId": "merchant-user-001",
  "platformUserId": "6054354872"
}

مثال نتيجة النقل

تحتفظ عمليات رد الاتصال بالأموال بأنواعها الحالية: orderId وagentId هي أرقام JSON؛ amount و platformUserId عبارة عن سلاسل. لا تقم بتطبيق اصطلاح سلسلة التحذير agentId على عمليات الاسترجاعات المالية. قراءة الأعداد الصحيحة الكبيرة دون فقدان الدقة باستخدام أنواع الأعداد الصحيحة/العشرية. completedAt هو UTC RFC3339؛ ts هي ثانية يونكس.

{
  "environment": "PRODUCTION",
  "event": "transfer.completed",
  "orderType": "transfer",
  "orderId": 10001,
  "orderNo": "merchant-order-001",
  "targetStatus": "SUCCESS",
  "agentId": 16,
  "agentCode": "DEMO",
  "currency": "USDT",
  "amount": "10.00",
  "direction": "IN",
  "transferMode": "FIXED_AMOUNT",
  "agentUserId": "merchant-user-001",
  "platformUserId": "6054354872",
  "rejectCode": 0,
  "rejectMessage": "",
  "failReason": "",
  "completedAt": "2026-10-13T07:17:50Z",
  "ts": 1791875870
}

مثال على نتيجة الانعكاس

{
  "environment": "PRODUCTION",
  "event": "reverse.completed",
  "orderType": "transfer",
  "orderId": 10002,
  "orderNo": "merchant-reverse-001",
  "targetStatus": "SUCCESS",
  "agentId": 16,
  "agentCode": "DEMO",
  "currency": "USDT",
  "amount": "10.00",
  "direction": "IN",
  "transferMode": "FIXED_AMOUNT",
  "agentUserId": "merchant-user-001",
  "platformUserId": "6054354872",
  "rejectCode": 0,
  "rejectMessage": "",
  "failReason": "",
  "completedAt": "2026-10-13T07:17:50Z",
  "ts": 1791875870
}

طلب الصناديق مثال على الحالة الميتة

{
  "environment": "PRODUCTION",
  "event": "transfer.dead",
  "orderType": "transfer",
  "orderId": 10003,
  "orderNo": "merchant-order-002",
  "targetStatus": "DEAD",
  "agentId": 16,
  "agentCode": "DEMO",
  "currency": "USDT",
  "amount": "10.00",
  "direction": "IN",
  "transferMode": "FIXED_AMOUNT",
  "agentUserId": "merchant-user-001",
  "platformUserId": "6054354872",
  "rejectCode": 0,
  "rejectMessage": "",
  "failReason": "order dead",
  "completedAt": "2026-10-13T07:17:50Z",
  "ts": 1791875870
}

تظهر هذه الأمثلة البروتوكول فقط. بالنسبة إلى FAILED، وrejectCode، وrejectMessage، وfailReason تعكس الرفض الفعلي. اسم الحدث وحده لا يثبت أنه تم إضافة الأموال.

التحقق من التوقيع والاستجابات وإعادة المحاولة