أعد إرسال الطلب باستخدام request_id الأصلي والمعلمات نفسها دون تغيير. لا تنشئ مفتاحًا جديدًا لمجرد انتهاء مهلة الاتصال. قد يعيد NotPanel الطلب المقبول، أو يطلب الانتظار إذا كانت معالجته مستمرة.
أجرى العميل عملية شراء واحدة. إذا ضاع الرد بعد إرسالها إلى اللوحة، فالخطوة التالية هي استعادة نتيجتها، دون تحويل عدم اليقين إلى شراء جديد.
تترك المهلة ثلاث احتمالات
- لم يصل الطلب ولم تُقبل أي عملية شراء.
- قُبل الطلب لكن الرد ضاع.
- ما زالت المعالجة جارية والنتيجة غير معروفة.
لا تميّز المهلة بين هذه الحالات. لا يجعل HTTP وحده تكرار POST الذي ينشئ شراءً آمنًا؛ تأتي الحماية من عقد API. راجع RFC 9110, §9.2.2.
كيف يتعرّف NotPanel على إعادة المحاولة؟
request_id اختياري، ولا يجوز أن يكون فارغًا، وطوله الأقصى 128 حرفًا. idempotency_key اسم بديل للتوافق؛ وعند إرسال الاثنين تكون الأولوية لـ request_id. احتفظ بالحساب والمفتاح وجميع المعلمات نفسها. يعيد الطلب المقبول معرّفه الأصلي، ويُرفض استخدام المفتاح نفسه بمعلمات مختلفة.
عند حذف الحقلين، يحمي NotPanel طلبات add المتطابقة للحساب نفسه لمدة 60 ثانية. لا تعتمد على هذه النافذة القصيرة للمحاولات المتأخرة. تبقى الطلبات ذات النتيجة غير المؤكدة محمية أثناء التحقق منها.
تُعامل عمليتا شراء متطابقتان مقصودتان أيضًا كطلب واحد داخل هذه النافذة. امنح كل شراء جديد request_id مختلفًا لإنشاء طلبين منفصلين فورًا. لا تغيّر المفتاح لتجاوز نتيجة غير مؤكدة.
احتفظ بقيمة request_id الأصلية بعد انتهاء المهلة.
أعد المحاولة بالمفتاح نفسه وتفاصيل الطلب دون تغيير.
احفظ معرّف الطلب المستعاد، أو انتظر إذا بقيت النتيجة غير مؤكدة.
احفظ هوية الشراء قبل الإرسال
لسطر الشراء 8427، احفظ request_id وجميع المعلمات قبل المحاولة الأولى. يستخدم المخطط قيمًا بديلة وأسطرًا للتوضيح؛ رمّز النموذج الفعلي بالطريقة المعتادة. لا ترسل قيمًا حقيقية إلا إذا كنت تريد طلبًا مدفوعًا.
POST https://notpanel.com/api/v3
Content-Type: application/x-www-form-urlencoded
key=YOUR_API_KEY
&action=add
&service=YOUR_SERVICE_ID
&link=YOUR_TARGET_URL
&quantity=YOUR_VALID_QUANTITY
&request_id=checkout-8427-line-1بعد المهلة، أعد checkout-8427-line-1 بالخدمة والهدف والكمية والحقول الاختيارية نفسها، حتى بعد إعادة تشغيل التطبيق. احفظ معرّف الطلب الوارد واستخدمه في status. يعرّف request_id محاولة الإنشاء ولا يحل محل معرّف الطلب في استعلام الحالة.
اقرأ الاستجابة كاملة
- مهلة أو استجابة غير مؤكدة
- احتفظ بالمفتاح والمعلمات. حدّد عدد المحاولات، وافصل بينها، والتزم بـ Retry-After. عند نفاد المحاولات احتفظ بالسجل دون اعتباره محسومًا.
- REQUEST_PROCESSING أو REQUEST_UNCONFIRMED
- انتظر وكرّر الطلب الأصلي فقط. لا تنشئ بديلًا بمفتاح آخر.
- REQUEST_ID_CONFLICT
- قارن المعلمات المحفوظة. استعد الطلب بالتفاصيل الأصلية؛ المفتاح الجديد مخصص لشراء منفصل مقصود.
- خطأ تحقق أو مصادقة أو حد طلبات
- اقرأ error_code وretryable. صحّح البيانات أو بيانات الاعتماد واحترم أوقات الانتظار. لا تكرّر كل خطأ آليًا.
اختبر الاستعادة قبل قبول مشتريات العملاء
ابدأ بـ API محاكاة في بيئة الاختبار الخاصة بك. لا تحتاج شراءً حقيقيًا أو مفتاح اختبار خاصًا من NotPanel.
- حاكِ قبول الطلب ثم فقدان الرد؛ تأكد من إعادة المفتاح والمعلمات نفسها.
- أعد تشغيل العميل واستعد الهوية المحفوظة.
- حاكِ استجابة معالجة ثم نجاحًا؛ ينبغي حفظ معرّف طلب واحد.
- حاكِ تعارضًا أو خطأ لا يُعاد؛ تأكد من توقف المحاولات الآلية.
- أنشئ عمليتي شراء جديدتين متطابقتين بمفتاحين مختلفين. لاختبار حقيقي لاحقًا، استخدم طلبًا تريده وتحقق من الطلب وسجل المحفظة.
أسئلة شائعة
هل تعني المهلة الخصم مرتين؟
لا. تعني أن التطبيق لم يتلق ردًا صالحًا للاستخدام. راجع الطلب المستعاد وسجل المحفظة قبل استنتاج وجود خصم مكرر.
هل request_id إلزامي؟
لا. request_id وidempotency_key اختياريان. بدونهما تُحمى طلبات add المتطابقة للحساب نفسه لمدة 60 ثانية. يحدّد المفتاح الصريح هوية كل شراء.
هل أنشئ مفتاحًا جديدًا لكل محاولة؟
لا. احفظ مفتاحًا قبل المحاولة الأولى وأعد استخدامه مع الطلب دون تغيير. الشراء الجديد يحصل على مفتاح جديد.
هل يمكن استعلام status باستخدام request_id؟
تحتاج status إلى معرّف الطلب. استعده بإعادة add الأصلي بالمفتاح والمعلمات نفسها. إذا بقيت النتيجة غير مؤكدة، احفظ التفاصيل للدعم دون إنشاء طلب آخر.
تابع القراءة: دليل التكامل · Webhooks واستعلام الحالة · مرجع الأخطاء.
