أفضل الممارسات
اجمع بين الويب هوك ومزامنات واجهة السحب المجدولة، ونفّذ upsert بمعرّف المعاملة، وأعد الاستعلام عن النطاقات الحديثة لاكتشاف المعاملات الملغاة.
يستخدم التكامل الأكثر موثوقية الويب هوك للسرعة ومزامنة مجدولة عبر واجهة السحب للاكتمال، مع اعتماد كل شيء على معرّف المعاملة id. تغطي الأقسام التالية التفاصيل التي تُربك كثيرين.
اجمع بين الويب هوك وواجهة السحب
استخدم الويب هوك للتحديثات شبه الفورية وواجهة السحب للتسوية. لا تغطي أي قناة وحدها كل الحالات:
| الحاجة | القناة |
|---|---|
| معرفة معاملة جديدة خلال ثوانٍ | الويب هوك |
| جلب السجل، أو الفترة السابقة لضبط عنوان الويب هوك | واجهة السحب |
| التعافي بعد تعطل نقطة النهاية أو تعطيل الويب هوك | واجهة السحب |
| اكتشاف المعاملات الملغاة بعد التسليم | واجهة السحب |
| تسوية كشف الحساب الشهري | واجهة السحب |
تصميم شائع: عالج الويب هوك فور وصوله، وشغّل مزامنة سحب مجدولة (مثلًا كل 15 دقيقة لآخر ساعتين، وليليًا لآخر 7 أيام) تنفذ upsert بمعرّف المعاملة id.
كيف أكتشف المعاملات الملغاة؟
لا تبلّغ واجهة السحب ولا الويب هوك عن معاملات VOID أو CANCELED. المعاملة التي تُلغى بعد استلامها تختفي من نتائج واجهة السحب لنطاق تاريخها.
لاكتشاف ذلك، أعد الاستعلام دوريًا عن النطاقات الحديثة وقارن بما لديك:
- اجلب كل المعاملات لآخر N يوم (7 قيمة افتراضية معقولة؛ وسّعها إذا استغرقت نزاعاتك وقتًا أطول).
- أي معاملة لديك بتاريخ
created_atضمن ذلك النطاق وغائبة عن الاستجابة قد أُلغيت. علّمها وفق ذلك. - تصل الاستردادات للتكرار والفروق والنزاعات كمعاملات
CONFIRMEDجديدة معcorrection_reference_idمضبوط. اربطها بالأصل.
نفّذ upsert بمعرّف المعاملة
عامل id كمفتاح أساسي للمعاملة لديك. تعيد القناتان السجل نفسه للمعرّف نفسه، فيتيح لك upsert استقبال حدث أولًا ونتيجة السحب لاحقًا (أو العكس) دون تعارض.
خزّن المبالغ بدقة
- خزّن
fees.total_amountبست منازل عشرية. يطابق خصم رصيدك تمامًا وهو الرقم الذي تسوّي به كشوف أوكتين. - خزّن المبالغ الأخرى بمنزلتين عشريتين على الأقل. استخدم نوعًا عشريًا لا نوع فاصلة عائمة.
تعامل مع الصور فورًا
تنتهي روابط الصور بعد ساعة (السحب) أو 24 ساعة (الويب هوك). إن احتجت إلى الصور، نزّلها عند استلام السجل وخزّنها بنفسك. لا تحفظ الرابط أبدًا.
تسامح مع الحقول الجديدة
قد تُضاف حقول جديدة إلى كائن المعاملة ومغلف الويب هوك في أي وقت. تجاهل الحقول التي لا تعرفها ولا تفشل بسببها.
احترم حد المعدل
- رقّم الصفحات بـ
limit=100. - تراجع عند
429باستخدامRetry-After. - شغّل عامل مزامنة واحدًا لكل مفتاح.
أمّن بيانات اعتمادك
- احتفظ بمفتاح API وسر الويب هوك في مدير أسرار. لا تُدرجهما في المستودع أبدًا.
- أرسل الطلبات فقط من عناوين IP في قائمتك؛ وأخبر أوكتين قبل تغيير عناوينك الصادرة.
- تحقق من توقيع كل ويب هوك وارفض الطوابع الزمنية القديمة.
- إذا اشتبهت في تسرب مفتاح أو سر، تواصل مع أوكتين فورًا. سيُعطَّل المفتاح ويُصدر مفتاح جديد.
خطط لانتهاء الوصول
راقب ترويسة الاستجابة X-Access-Expires-At. جدّد ملف التسعير لدى أوكتين قبل ذلك التاريخ لتجنب 403 NO_ACTIVE_CHARGING_PROFILE وتوقف تسليمات الويب هوك.
الدعم
عند التواصل مع دعم أوكتين، أرفق:
- بادئة مفتاحك (لا المفتاح الكامل أبدًا)
request_idمن استجابة الخطأ، إن وُجد- معرّف التسليم
idلمشكلات الويب هوك - الطوابع الزمنية بالتوقيت العالمي