Webhook التحقق من التوقيع والصلاحية

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

تستخدم جميع أنواع الأحداث الأربعة رد اتصال تاجر واحد URL ويتم إرسالها بواسطة النص الأساسي event. يرى Webhook الأحداث وتحذيرات التصفية لحقول الأحداث وأمثلة الحمولة.

Webhook رؤوس

timestamp + nonce + rawBody

عجز الحدث

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

التحقق من التوقيع والاستلام

استخدم سر التاجر API لحساب التوقيع الست عشري HMAC-SHA256 لـ timestamp + nonce + rawBody. التحقق من البايتات الأصلية المستلمة؛ لا تقم بتنسيق JSON، أو إعادة تسمية الحقول، أو إعادة تسلسل النص أولاً.

تحقق من التوقيع أولاً، ثم تحقق من نافذة الوقت (يوصى بـ ±300 ثانية)، والتاجر، والبيئة. قم بعد ذلك باستخراج هوية العجز والتعامل مع الإشعار بشكل موثوق. الحفاظ على قيم الأحداث غير المعروفة للتشخيص؛ لا تفسرها أبدًا على أنها نجاح للأموال. لا يقوم مساعد التحقق بإجراء فحوصات الإطار الزمني أو الملكية أو إلغاء البيانات المكررة المستمرة.

قم بإرجاع HTTP 2xx بعد إكمال المعالجة أو تأكيد نسخة متطابقة؛ إرجاع غير 2xx عند الفشل. لدى مرسل التحذير مهلة مدتها 5 ثوانٍ HTTP و8 محاولات على الأكثر. إعادة المحاولة تحتفظ بالجسم المجمد؛ فقط الطابع الزمني للتوقيع وتغيير nonce. الرد بسرعة بعد القبول الموثوق به؛ يمكن للعمل التجاري طويل الأمد استخدام المهام المستمرة الخاصة بالتاجر.

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

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

تستخدم عمليات رد الاتصال بالأموال وتحذيرات التصفية رمز الحالة HTTP فقط لتحديد نجاح التسليم. لا يفسر المرسل نص الاستجابة code، أو success، أو result، أو message، ولا يتطلب استجابة ثابتة OK / success.

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

أمثلة على الاستجابة الناجحة

بعد اكتمال معالجة الأعمال، أو حفظ الإشعار بشكل موثوق في قائمة الانتظار المعلقة الخاصة بالتاجر:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"RECEIVED"}

عندما لا تكون هناك حاجة إلى هيئة الاستجابة:

HTTP/1.1 204 No Content

بالنسبة للإشعار الذي تمت معالجته بالفعل بنص مماثل، تخطي معالجة الأعمال المكررة واستمر في إرجاع 2xx:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"DUPLICATE"}

أمثلة على الاستجابة للفشل

إذا كانت قاعدة البيانات غير متاحة مؤقتًا ولم يكمل التاجر معالجة الإشعار ولم يحفظه بشكل موثوق، فقم بإرجاع غير 2xx حتى يتمكن النظام الأساسي من إعادة المحاولة:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{"result":"FAILED","message":"temporary storage failure"}

رفض التوقيع غير الصالح دون تحديث بيانات العمل أو سجلات إلغاء البيانات المكررة الناجحة:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"result":"INVALID_SIGNATURE"}

لا تغير هيئات الاستجابة هذه قرارات إعادة المحاولة. لا تتوقع أن يقوم 401 أو 409 بإيقاف إعادة المحاولة بشكل دائم؛ التحقق من التوقيع أو محتوى الإشعار أو تكوين التاجر.

مثال غير صحيح: لا تزال الاستجابة التالية تعتبر بمثابة تسليم ناجح. لن يقوم النظام الأساسي بإعادة المحاولة بسبب success:false.

HTTP/1.1 200 OK
Content-Type: application/json
{"success":false,"code":500,"message":"processing failed"}

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

إقرار موثوق به وتسليم مكرر

الأمر الموصى به: التحقق من التوقيع والتحقق من الوقت / التاجر / البيئة ← استخراج هوية القصور ← معالجة بيانات العمل وسجلات إلغاء البيانات المكررة الناجحة في معاملة ما، أو حفظ مهمة معلقة بشكل موثوق ← إرجاع 200/204 بعد نجاح الالتزام. لا تقم بإرجاع 2xx أو وضع علامة على الإعلام الذي تمت معالجته قبل كتابة قاعدة بيانات ناجحة.

لا يزال من الممكن حدوث تسليم مكرر بعد نجاح معالجة التاجر: قد يتم فقدان الاستجابة، أو قد تتلقى المنصة 2xx ولكنها تفشل في الاستمرار SUCCESS. HTTP لا تضمن عمليات الاسترجاعات التسليم لمرة واحدة. استمرار إلغاء البيانات المكررة داخل نطاق التاجر وenvironment. استخدام الأموال orderType:orderId:targetStatus؛ تستخدم التحذيرات liquidation.warning:notificationId. بالنسبة لهيئة متطابقة تمت معالجتها بالفعل، قم بإرجاع 2xx دون إضافة أموال أو إصدار تذكير مرة أخرى. لنفس الهوية مع هيئة مختلفة، قم بتسجيل تعارض وإرجاع غير 2xx؛ لا تقم بالكتابة فوق السجل الأصلي.

نجاح الإقرار يعني أن التاجر قد تلقى/عالج الإشعار، وليس نجاح عملية الأموال. بعد تسجيل إشعار أموال صالح باستخدام targetStatus=FAILED، قم أيضًا بإرجاع 2xx؛ لا يعد فشل الطلب سببًا لرفض إقرار الإشعار.

حدود التمويل والبيئة

لا يتم تطبيق تدفق نقل العقد الأصلي webhook وqueryOrder تلقائيًا على التمويل. قم بتأكيد عمليات التمويل باستخدام queryWalletTransfer وبيئة الطلب الأصلية. استخدامات التمويل status؛ تستخدم ردود نقل العقد الأصلية orderStatus. إن الاستجابة الناجحة HTTP أو code=0 لا تثبت في حد ذاتها نقل الأموال.

تتضمن إخطارات نقل العقد المحاكاة الصريحة environment=SIMULATED. تحقق من النص الخام أولاً، ثم تحقق من المستخدم والمبلغ وهوية الطلب والبيئة مقابل أمر العمل المحلي المحفوظ.

دليل استرداد التمويل · دليل البيئة