وثائق المطورين

إعادة إرسال إشعار الدفع المؤكد

أعد الإرسال لـ CONFIRMED / COMPLETED بعد إصلاح المستقبِل. الإدراج في الطابور لا يعني التسليم.

POST /api/v1/webhooks/resend

طلب المصادقة

تضمين X-Bolt-Key وX-Bolt-Timestamp وX-Bolt-Signature. استخدم المللي ثانية الحالية timestamp وقم بتوقيعها مع نص الطلب الدقيق.

متى يتم إعادة الإرسال

استخدم نقطة النهاية هذه عندما يحتاج نظامك إلى إشعار آخر بدفعة مؤكدة. لا تؤدي إعادة الإرسال إلى تحصيل المدفوعات أو تسوية التحويل أو إنشاء طلب.

يمكن إعادة إرسال طلبات CONFIRMED أو COMPLETED فقط. PENDING وPAID والولايات الأخرى غير مؤهلة.

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

01. معلمات الطلب

application/json
externalOrderIdمطلوب
String

أرسل إلى التاجر externalOrderId الذي تم توفيره عند إنشاء الطلب، وليس orderToken. يمكنك فقط إعادة إرسال الإشعارات للطلبات التي تنتمي إلى مفتاح API الحالي.

قيمة المثال

{"externalOrderId": "INV-20260209-99281"}

السلسلة المطلوبة، من 6 إلى 64 حرفًا. يُسمح باستخدام الأحرف والأرقام والشرطات السفلية (_) والواصلات (-).

Body

02. حقول الاستجابة (data)

application/json
notifyUrlString
عنوان رد الاتصال المسجل في الطلب؛ قد يكون null. يفضل التسليم هذا العنوان ويعود إلى تكوين Webhook المرتبط للطلبات الأقدم التي لا تحتوي على عنوان.
externalOrderIdString
طلب التاجر ID المرتبط بإعادة الإرسال هذا، مطابق للطلب externalOrderId.
triggerTypeEnum
دائمًا MANUAL في استجابة نقطة النهاية هذه، للإشارة إلى إعادة الإرسال التي طلبها التاجر. هذا ليس نوع تسوية الدفع.
statusEnum
إعادة إرسال حالة الطلب. QUEUED يعني أن المهمة استمرت؛ إنها ليست حالة الدفع ولا إثبات التسليم.

تعني QUEUED حفظ مهمة الإرسال لإرسالها لاحقًا، ولا تعني وصول الإشعار. تحقق من سجلات الإرسال في لوحة التاجر ومن استجابة المستلم HTTP 2xx.

🚀
التعامل مع المستلمين

تحقق من X-Bolt-Webhook-Timestamp وX-Bolt-Webhook-Signature، ثم قم بإلغاء التكرار بواسطة eventId أو طلب التاجر ID قبل التنفيذ. قم بإرجاع HTTP 2xx للإشعارات المكررة التي تمت معالجتها بالفعل بنجاح.

  • triggerType: يظهر MANUAL في سجلات استجابة إعادة الإرسال وتسليم لوحة المعلومات. لا يحتوي نص طلب Webhook الحالي على triggerType؛ لا تعتمد عليه لتحديد إعادة الإرسال.
  • تنشئ كل مكالمة ناجحة مهمة تسليم مستقلة. قد تؤدي الطلبات المتكررة إلى إرسال إشعارات متعددة. تحقق من سجلات التسليم قبل إعادة الإرسال مرة أخرى. تحتفظ عمليات الإعادة بالرمز eventId المنطقي.
  • تعيد نقطة النهاية هذه استخدام وجهة رد الاتصال الخاصة بالأمر ولا تقبل URL جديد. لا يؤدي تغيير الإعداد الافتراضي للوحة التحكم إلى استبدال العنوان المحفوظ بالفعل في الطلب.
Safe

الأخطاء الشائعة

هذه حالات شائعة. استخدم حالة HTTP الفعلية ورمز/رسالة الاستجابة لتشخيص حالات الفشل. الاستجابة الخاطئة ليست نتيجة دفع.

  • 401: تحقق من مفتاح API وتوقيع الجسم الخام والميلي ثانية الحالية timestamp (خلال 5 دقائق من ساعة الخادم).
  • 404: الطلب مفقود، أو ينتمي إلى تاجر آخر، أو خارج السجل الذي تسمح به خطتك.
  • 400: الطلب ليس CONFIRMED / COMPLETED، أو تكوين Webhook متاح ومهمة تسليم مخزنة بنجاح مفقودة.
resend / cURL
# Run against your account only when ready; this sends an API request.
: "${BOLTUTIL_API_KEY:?Set your complete API Key}"
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')

curl --request POST "https://api.boltutil.com/api/v1/webhooks/resend" \
  --header 'Content-Type: application/json' \
  --header "X-Bolt-Key: $BOLTUTIL_API_KEY" \
  --header "X-Bolt-Timestamp: $timestamp" \
  --header "X-Bolt-Signature: $signature" \
  --data-binary "$body"

العناوين وتجزئة المعاملات والأوامر هي أمثلة. استبدلها بالاختبار الخاص بك data.

Base URL

PROD
https://api.boltutil.com