في أحداث الحجز، تمثل Data.Price إجمالي بند الحجز بعد الخصم وشامل الضريبة. وهي تقابل Data.Order.Item.TotalAmount، وليست سعر الوحدة قبل الضريبة أو المبلغ الذي حُصّل من العميل أو صافي التحويل البنكي. أما Data.Order.TotalAmount فهو إجمالي الطلب كله، وقد يختلف إذا احتوى الطلب بنودًا أو رسومًا أخرى.

المثال المصوّر يوضح حجزًا قيمته 50 ريالًا: يعرض بند الطلب سعرًا قبل الضريبة 43.48 وضريبة 6.52 وإجماليًا شاملًا للضريبة 50. المبلغ المدفوع صفر والمتبقي 50. هذه أرقام مختلفة لأغراض مختلفة؛ لا يعني ظهور 43.48 في عمود «سعر» أن قيمة Webhook Price يجب أن تستبعد الضريبة.

قبل البدء

جهّز رقم الحجز ورقم الطلب من بيانات الحدث، ثم افتح «الطلبات» في لوحة ركاز.

• استخدم حدثًا من عائلة الحجز، مثل ReservationConfirmedEvent. قد تختلف حقول الأحداث الخاصة بالاشتراكات أو المدفوعات أو الهدايا؛ لا تعمم تعريف Price عليها.

• استخدم Data.Number لمطابقة رقم الحجز، وData.Order.SequentialNumber لمطابقة رقم الطلب. Id الخارجي يخص الحدث المرسل، وليس رقم الطلب المعروض في اللوحة.

• قارن نفس الطلب والحجز، وانتبه إلى وقت الحدث وأي تعديل حدث بعده. احتفظ ببيانات التكامل الحساسة في نظامك المخصص لها.

1. افتح الطلب المطابق

من «الطلبات»، ابحث برقم الطلب الموجود في Data.Order.SequentialNumber، ثم افتح الرقم المطابق. راجع «رقم الطلب» ولا تخلطه برقم فاتورة أو رقم حجز.

2. طابق الحجز مع بند الطلب

في «تفاصيل الطلب»، افتح تفاصيل الخدمة من صفها. قارن رقم الحجز الظاهر مع Data.Number، وراجع الخدمة والوقت، ثم اضغط «إغلاق» للعودة إلى تفاصيل الطلب.

3. اقرأ إجمالي البند شامل الضريبة

راجع الكمية و«سعر» و«الخصم» وقيمة الضريبة و«السعر الكلي شامل الضريبة». حرّك الجدول أفقيًا إذا لم تظهر كل الأعمدة. المبلغ الأخير هو ما تقابله Data.Price وData.Order.Item.TotalAmount؛ لا تضف الضريبة أو تخصم الخصم منه مجددًا.

4. افصل مجموع الطلب عن التحصيل

انزل إلى «ملخص مبالغ الطلب» وقسم «الدفع». قارن إجمالي الطلب مع Data.Order.TotalAmount، والمدفوع والمتبقي مع حقليهما في Order. في المثال: الإجمالي 50 والمدفوع صفر والمتبقي 50؛ لا يلزم دفع الطلب أو تعديل الحجز لمجرد المقارنة.

النتيجة

تحدد مبلغ بند الحجز شامل الضريبة، وتفصله عن إجمالي الطلب وحالة التحصيل قبل استخدامه في التكامل.

Data.Price هو إجمالي بند الحجز بعد الخصم وشامل الضريبة. لا تضف الضريبة إليه مرة أخرى، ولا تخصم Data.Discount منه مرة ثانية. اختلاف هذا المبلغ عن سعر الخدمة الحالي لا يكفي وحده لإثبات وجود خصم جديد؛ قارن البند المحفوظ في الطلب.

Data.Items[].Price يعرض قيمة بند الحجز كذلك. لا تجمع هذا الحقل مع Data.Price باعتبارهما مبلغين مستقلين، ولا تضرب الإجمالي في الكمية مرة أخرى.

Data.Order.Item هو تفصيل البند المرتبط بالحجز: Quantity للكمية، وUnitPrice لسعر الوحدة، وSubtotal للمجموع الفرعي، وDiscountAmount للخصم، وTaxAmount للضريبة، وTotalAmount للإجمالي. كلمة Item هنا مفردة، وتختلف عن مصفوفة Items في بيانات الحجز.

Data.Order.TotalAmount يخص الطلب الكامل. إذا كان فيه أكثر من خدمة أو رسوم على الطلب، فلا تتوقع مساواته لسعر حجز واحد. استخدم بيانات البند للحجز، وبيانات Order لمجموع الطلب.

Data.Order.PaidAmount يخص المبلغ المدفوع، وData.Order.RemainingAmount يخص المتبقي، وData.Order.Currency يحدد العملة. Price لا يثبت تحصيل المال، ولا يعبر عن عمولة بوابة الدفع أو صافي المبلغ المحول إلى حسابك البنكي.

المثال المعروض: إجمالي البند والطلب 50، والمدفوع 0، والمتبقي 50. تأكيد الحجز أو وصول حدث ReservationConfirmedEvent ليس بديلًا عن قراءة PaymentStatus ومبالغ الدفع عندما تكون مهمتك التحقق من السداد.

عمود «سعر» في تفاصيل الطلب يعرض السعر قبل الضريبة في هذا المثال. قارن Data.Price بعمود «السعر الكلي شامل الضريبة»، ثم استخدم عمود الخصم والضريبة لفهم الفروق. لا تساوِ بين حقلين لمجرد تشابه اسميهما.

قد تعرض اللوحة منزلتين عشريتين، بينما تحتوي مبالغ Webhook على دقة تصل إلى أربع منازل. استخدم حسابات مالية عشرية وتقريب العرض المتسق؛ لا تعتبر فرق التقريب الصغير عمولة أو خصمًا تلقائيًا.

إذا كانت لديك عينة قديمة فيها 43.4783 بدل 50، فلا تعالج جميع الرسائل بإضافة نسبة ضريبة ثابتة. راجع رسالة حديثة وحقول Order.Item، وقارنها بالطلب نفسه. إذا استمر الاختلاف، جهّز رقم الحجز والطلب ووقت الحدث والقيم المعنية لشرح الحالة للدعم دون مشاركة أسرار التكامل.

أسماء حقول Webhook حساسة لطريقة كتابتها: يستخدم الغلاف Id وEventName وCreatedAt وData، والحقول الداخلية مثل Price وOrder بحروفها الظاهرة. لا تنقل أسماء حقول استجابة REST آليًا إلى قارئ Webhook؛ قد تختلف البنية وطريقة الكتابة.

يمكن أن يصل أكثر من حدث للحجز نفسه، أو تتكرر محاولة تسليم حدث. لا تجمع إجمالي الطلب كلما وصلك حدث حجز مرتبط به. ميّز معرف الحدث عن معرف الحجز والطلب عند منع التكرار وتحديث حالة التكامل.

إذا اختلفت حالة الحجز عن حالة الدفع، احتفظ بالتمييز بينهما في تكاملك. راجع البيانات الحالية عند الحاجة إلى إجراء يعتمد على الوضع الحالي، لأن الرسالة ليست ضمانًا لبقاء الطلب دون تعديل لاحق.