أعد إرسال الطلب باستخدام request_id الأصلي والمعلمات نفسها دون تغيير. لا تنشئ مفتاحًا جديدًا لمجرد انتهاء مهلة الاتصال. في NotPanel تعيد المحاولة الطلب الأصلي مع replayed: true، أو تنشئه إذا لم تصل المحاولة الأولى أصلًا.
أجرى العميل عملية شراء واحدة. إذا ضاع الرد بعد إرسالها إلى اللوحة، فالخطوة التالية هي استعادة نتيجتها، دون تحويل عدم اليقين إلى شراء جديد.
تترك المهلة ثلاث احتمالات
- لم يصل الطلب ولم تُقبل أي عملية شراء.
- قُبل الطلب لكن الرد ضاع.
- وصل الطلب أثناء انقطاع الاتصال؛ وتوضح إعادة المحاولة بـ request_id نفسه أي الحالتين السابقتين حدثت.
لا تميّز المهلة بين هذه الحالات. لا يجعل 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 محاولة الإنشاء ولا يحل محل معرّف الطلب في استعلام الحالة. للبحث عن طلب باستخدام request_id استخدم order_details.
اقرأ الاستجابة كاملة
- مهلة أو استجابة غير مؤكدة
- احتفظ بالمفتاح والمعلمات. حدّد عدد المحاولات، وافصل بينها، والتزم بـ Retry-After. عند نفاد المحاولات احتفظ بالسجل دون اعتباره محسومًا.
- INTERNAL_ERROR أو API_DISABLED أو ORDER_PLACEMENT_PAUSED (retryable: true)
- انتظر، والتزم بـ Retry-After إن وُجد، ثم أرسل add نفسه بـ request_id نفسه. ستحصل على الطلب الأصلي أو على طلب جديد واحد فقط. لا تنشئ بديلًا بمفتاح آخر.
- REQUEST_ID_CONFLICT
- قارن المعلمات المحفوظة. استعد الطلب بالتفاصيل الأصلية؛ المفتاح الجديد مخصص لشراء منفصل مقصود.
- خطأ تحقق أو مصادقة أو حد طلبات
- اقرأ error_code وretryable. صحّح البيانات أو بيانات الاعتماد واحترم أوقات الانتظار. لا تكرّر كل خطأ آليًا.
اختبر الاستعادة قبل قبول مشتريات العملاء
ابدأ بـ API محاكاة في بيئة الاختبار الخاصة بك. لا تحتاج شراءً حقيقيًا أو مفتاح اختبار خاصًا من NotPanel.
- حاكِ قبول الطلب ثم فقدان الرد؛ تأكد من إعادة المفتاح والمعلمات نفسها.
- أعد تشغيل العميل واستعد الهوية المحفوظة.
- حاكِ استجابة 500 أو 503 قابلة لإعادة المحاولة ثم إعادة تشغيل بـ replayed: true؛ ينبغي حفظ معرّف طلب واحد.
- حاكِ تعارضًا أو خطأ لا يُعاد؛ تأكد من توقف المحاولات الآلية.
- أنشئ عمليتي شراء جديدتين متطابقتين بمفتاحين مختلفين. لاختبار حقيقي لاحقًا، استخدم طلبًا تريده وتحقق من الطلب وسجل المحفظة.
أسئلة شائعة
هل تعني المهلة الخصم مرتين؟
لا. تعني أن التطبيق لم يتلق ردًا صالحًا للاستخدام. راجع الطلب المستعاد وسجل المحفظة قبل استنتاج وجود خصم مكرر.
هل request_id إلزامي؟
لا. request_id وidempotency_key اختياريان. بدونهما تُحمى طلبات add المتطابقة للحساب نفسه لمدة 60 ثانية. يحدّد المفتاح الصريح هوية كل شراء.
هل أنشئ مفتاحًا جديدًا لكل محاولة؟
لا. احفظ مفتاحًا قبل المحاولة الأولى وأعد استخدامه مع الطلب دون تغيير. الشراء الجديد يحصل على مفتاح جديد.
هل يمكن البحث عن طلب باستخدام request_id؟
نعم، عبر order_details: أرسل action=order_details مع request_id نفسه لتحصل على الطلب ورقمه دون إعادة add. إذا لم يُنشأ أي طلب، يكون الرد ORDER_NOT_FOUND. أما إجراء status فما زال يحتاج إلى رقم الطلب.
تابع القراءة: دليل التكامل · Webhooks واستعلام الحالة · مرجع الأخطاء.
