أفضل الممارسات

تكامل الشحن يعمل في العالم الحقيقي: شبكات تتقطع، وحدود طلبات تُلامَس، وناقلون ينشغلون. هذه الممارسات تجعل تكاملك يصمد.

المهلات

حدد مهلة صريحة لكل طلب تجاه منفذ — 15 ثانية حد معقول لمعظم النقاط. الطلب المعلق بلا مهلة يجمّد خيوط معالجة متجرك في ساعة الذروة، وهي أسوأ لحظة ممكنة. افشل بسرعة، وسجّل الفشل، وقرر بوعي: أتعيد المحاولة أم تعرض للعميل خيارًا بديلًا؟

افصل مهلة الاتصال عن مهلة القراءة إن كانت مكتبتك تسمح بذلك: اتصال لا يُفتح خلال ثوانٍ قليلة لن يُفتح غالبًا، بينما استجابة بطيئة قد تكتمل.

إعادة المحاولة بذكاء

ليست كل الأخطاء سواء. استجابة 429 تعني أنك تجاوزت حد الطلبات، و503 تعني أن الناقل غير متاح مؤقتًا — كلاهما عابر وكلاهما يستحق إعادة محاولة. احترم ترويسة Retry-After عندما تصلك، فهي تخبرك بالضبط متى تعاود. وعند غيابها طبّق تراجعًا أسّيًا مع عشوائية: ثانية، ثم ثانيتين، ثم أربعًا، بحد أقصى للمحاولات. أما أخطاء 4xx الأخرى مثل فشل التحقق فلا تُعاد محاولتها — أصلح الطلب نفسه أولًا.

الانقطاع الأخطر هو الذي يقع بعد وصول طلبك وقبل وصول الاستجابة إليك: نجحت العملية على الخادم وأنت لا تدري. صمّم منطق الإعادة على افتراض أن الطلب السابق ربما نُفّذ. عند إعادة إرسال طلب إنشاء شحنة بعد انقطاع، أرفق ترويسة Idempotency-Key بقيمة ثابتة لتجنب إنشاء شحنة مكررة. وقبل إعادة أي عملية إنشاء يمكنك أيضًا الاستعلام عن شحناتك الأخيرة للتأكد مما وصل فعلًا، فالوقاية من التكرار أرخص دائمًا من معالجته في الفواتير لاحقًا.

خزّن المراجع فور وصولها

كل شحنة ناجحة تعيد manfath_reference وtracking_number. خزّن الاثنين في سجل الطلب لديك ضمن نفس المعاملة التي تحدّث حالة الطلب — لا في خطوة لاحقة قد تفشل. المرجع هو مفتاحك الدائم في التتبع والفواتير والتسوية والدعم، والطلب الذي بلا مرجع محفوظ يصبح بحثًا يدويًا مؤلمًا في نهاية الشهر.

اعتبر المرجعين قيمتين ثابتتين لا تتغيران: خزّنهما كما وصلا واربطهما بمعرف الطلب الداخلي عندك.

تحقق من الويبهوكس

قبل معالجة أي إشعار وارد تحقق من توقيعه كما تشرح صفحة الويبهوكس وتجاهل ما لا يجتاز التحقق. أكّد الاستلام بـ 200 فورًا وأجّل المعالجة إلى صف مهام خلفي، واجعل معالجتك تتحمل وصول الإشعار نفسه مرتين — إعادة المحاولة قد تسلّم الإشعار الواحد أكثر من مرة.

سجّل معرفات الطلبات

تحمل كل استجابة من منفذ ترويسة X-Manfath-Request-Id بمعرف فريد للطلب. سجّله مع كل استدعاء — نجح أم فشل — واربطه بمعرف الطلب الداخلي لديك. عندما تراسل الدعم عن سلوك غريب، هذا المعرف يختصر التشخيص من ساعات إلى دقائق لأنه يقود مباشرة إلى سجل الطلب عند منفذ.

راقب أيضًا نسبة أخطاء 4xx في استدعاءاتك: ارتفاعها المفاجئ يعني غالبًا خللًا في بياناتك المرسلة لا في الواجهة.

قائمة مراجعة سريعة