الفوترة والاسترداد

فوترة الوقت الفعلي لكل منتج ولكل معرّف. ويحجز الطلب المبلغ مقدمًا، ثم يسوّي بمجرد أن يحصل كل منتج مختار على نتيجة.

احجز، ثم سوِّ

عند قبول الطلب، تحجز المنصة مجموع أسعار الفحص للمنتجات المختارة. ولا يُحتسب شيء بعد. ومع عودة النتائج، تُسوّى كل مدخل على حدة:

• المدخل المحتسب يحتفظ بحجزه
• المدخل المسترد يعيده إلى رصيدك

تصف المجاميع الثلاثة في الاستجابة تلك التسوية:

الحقل	المعنى
total_reserved	محجوز عند قبول الطلب
total_charged	المحتجز فعليًا
total_refunded	المُعاد إلى رصيدك

وهي تتوازن دائمًا: total_reserved = total_charged + total_refunded.

ما يُحتسب وما يُسترد

النتيجة	billing_status	المعنى
valid — المعرّف مسجّل	charged	أُنتجت إجابة حقيقية
invalid — المعرّف غير مسجّل	charged	أُنتجت إجابة حقيقية
unknown — لم يُرجع المورّد شيئًا حاسمًا	refunded	لا إجابة؛ والنتيجة غير الحاسمة لا تُفاتر أبدًا
مهلة المزوّد	refunded	error_code: provider_timeout
القناة أو خانة المستخدم غير متاحة	refunded	error_code: channel_busy / user_busy
حماية التزامن على واقعة مشتركة	refunded	error_code: fact_refresh_busy
فشل المورّد في الفحص	refunded	error_code: realtime_failed
ذاكرة النتائج المؤقتة غير متاحة	refunded	error_code: fact_cache_unavailable

إصابة الذاكرة المؤقتة تُحتسب أيضًا. المدخل ذو cached: true إجابة حقيقية أُنتجت في فحص سابق وخُزّنت؛ والاحتساب يعكس الإجابة لا رحلة الذهاب والإياب. ولا تُسترد إلا نتائج unknown والنتائج الفاشلة.

قراءة طلب ناجح جزئيًا

بما أن كل مدخل يُسوّى على حدة، يمكن أن يحمل الطلب الواحد النتيجتين معًا. ويُبلّغ عن ذلك بالحالة status: partial_succeeded — وحالة HTTP لا تزال 200. لا تعامل 200 أبدًا على أنها “كل شيء نجح”:

1. اقرأ status
2. لكل مدخل، اقرأ billing_status وerror_code

قيم status: succeeded (كل مدخل محتسب)، وpartial_succeeded (مزيج)، وfailed (لا مدخل أنتج إجابة قابلة للاحتساب).

الرصيد

تتطلب الطلبات رصيدًا يكفي للحجز الكامل. وإذا كان ناقصًا، يفشل الطلب بـ 402 insufficient_balance قبل التواصل مع أي منتج — فلا يُحجز شيء ولا يُحتسب شيء.

الرصيد نفسه متاح من GET /v1/balance. راجع رصيد الحساب.

الاسترداد تلقائي

لا توجد خطوة لطلب استرداد. فالمدخل المسترد يُسوّى عائدًا إلى رصيدك ضمن الطلب نفسه، والاستجابة التي تتلقاها تعكس الأرقام النهائية بالفعل.