> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# الفوترة المتكررة Recurring Billing: من التجربة إلى التجديد
- URL: https://arabroot.io/articles/الفوترة-المتكررة-recurring-billing-من-التجربة-الى-التجديد/
- Published: 2026-11-16T15:51:45.000Z
- Updated: 2026-11-16T16:49:28.000Z
- Description: كيف تبني اشتراكات تتعامل مع التجربة المجانية والترقية وفشل الدفع والضريبة دون خصم مكرر، مع مختبر حقيقي على Kill Bill.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, التقنية المالية والمدفوعات

إذا كنت تبني منتجاً يبيع اشتراكاً شهرياً، تطبيقاً لاشتراكات الأندية الرياضية مثلاً أو برنامجاً سحابياً SaaS، فأغلب الظن أن أول نسخة من الفوترة عندك مهمة مجدولة Cron Job تعمل كل ليلة، وتبحث عن الاشتراكات التي يجددها اليوم، وتخصم ثمنها من البطاقة المحفوظة. وهذه النسخة تعمل فعلاً في الشهر الأول، ثم يبدأ العملاء بطلب أشياء عادية جداً: عميل يريد الترقية في منتصف الشهر، وآخر يريد التخفيض، وبطاقة ثالث انتهت صلاحيتها ليلة التجديد، ورابع يسأل لماذا خصم منه مرتين، والمحاسب يسأل أين ضريبة القيمة المضافة في الفاتورة.

عند هذه النقطة تكتشف أن الفوترة المتكررة Recurring Billing ليست عملية خصم كل شهر، وإنما نظام كامل له حالات وقواعد وتواريخ، وأن كل حالة لم تفكر فيها تتحول إلى خطأ في مال عميل أو في إيرادك. وفي هذا المقال سوف نبني هذا النظام خطوة بخطوة، ثم نشغله فعلاً على محرك فوترة مفتوح المصدر.

سوف نناقش في هذا المقال:

- لماذا تفشل المهمة المجدولة البسيطة، وما المكونات التي يحتاجها نظام الفوترة الحقيقي.
- دورة حياة الاشتراك: التجربة المجانية Free Trial، والتجديد، والترقية والتخفيض Upgrade/Downgrade، والإلغاء.
- التناسب Proration: كيف تحسب الفاتورة عندما يغير العميل خطته في منتصف الفترة.
- فشل الدفع وإعادة المحاولة Retries ومراحل التحصيل Dunning.
- الفواتير وضريبة القيمة المضافة VAT، ومنع الخصم المكرر Idempotency، والأحداث Webhooks.
- مختبر كامل على Kill Bill في Docker، نحرك فيه ساعة النظام لنعيش ثلاثة أشهر من حياة اشتراك في دقائق.

وهذا المقال من مرحلة «قبول الدفع في منتجك» في قسم التقنية المالية. فإذا لم تكن قرأت كيف يعمل الدفع بالبطاقة نفسه، فابدأ من [مقال الدفع بالبطاقة](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D8%AA%D8%B9%D9%85%D9%84-%D8%B9%D9%85%D9%84%D9%8A%D8%A9-%D8%A7%D9%84%D8%AF%D9%81%D8%B9-%D8%A8%D8%A7%D9%84%D8%A8%D8%B7%D8%A7%D9%82%D8%A9-%D8%A7%D9%84%D8%AA%D9%81%D9%88%D9%8A%D8%B6-%D9%88%D8%A7%D9%84%D8%AA%D8%B3%D9%88%D9%8A%D8%A9-%D9%88%D8%A7%D9%84%D8%A7%D8%B9%D8%AA%D8%B1%D8%A7%D8%B6/)، لأننا هنا نتحدث عما فوقه: متى نطلب المال، وكم، وماذا نفعل إذا لم يأت.

## لماذا لا تكفي مهمة مجدولة Cron Job؟

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

والمشكلة الأولى في كلمة «شهراً». فالاشتراك الذي بدأ في 31 يناير متى يتجدد في فبراير؟ والذي بدأ في 15 مارس كم يوماً في فترته الأولى، 31 أم 30؟ وهذه ليست أسئلة نظرية، لأنها تحدد كم تعيد للعميل إذا ألغى، وكم تطلب منه إذا رقى خطته.

والمشكلة الثانية في التغيير. فإذا رقى العميل من خطة 99 ريالاً إلى خطة 199 ريالاً بعد عشرة أيام من بداية فترته، فهل تخصم 199 كاملة؟ وماذا عن 99 التي دفعها قبل عشرة أيام ولم يستهلك أغلبها؟ المهمة المجدولة لا تعرف شيئاً عن ذلك، فتكتب الفرق كوداً خاصاً لكل حالة، ثم كوداً آخر للتخفيض، ثم ثالثاً للإلغاء.

والمشكلة الثالثة في الفشل. فإذا رفض البنك الخصم، هل تعيد المحاولة غداً؟ وكم مرة؟ وهل تبقى الخدمة تعمل أثناء ذلك؟ ومتى توقفها؟ ومن يرسل رسالة للعميل؟ وإذا نجحت المحاولة الثالثة بعد أن أوقفت الخدمة، هل تعيدها تلقائياً؟

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

لذلك يتكون نظام الفوترة الحقيقي من أجزاء منفصلة، لكل منها مسؤولية واضحة:

| الجزء                     | مسؤوليته                                              | السؤال الذي يجيب عنه         |
| ------------------------- | ----------------------------------------------------- | ---------------------------- |
| الكتالوج Catalog          | المنتجات والخطط والأسعار والمراحل وقواعد التغيير      | ماذا نبيع، وبكم، وكيف يتغير؟ |
| الاشتراك Subscription     | من اشترك في أي خطة، ومنذ متى، وفي أي مرحلة            | ما حق هذا العميل اليوم؟      |
| الفوترة Invoicing         | تحويل الاشتراكات والتغييرات إلى بنود فاتورة بالتواريخ | كم يدين العميل، وعن أي فترة؟ |
| الدفع Payment             | طلب المال من بوابة الدفع وإعادة المحاولة              | هل وصل المال؟                |
| التحصيل Dunning / Overdue | ما يحدث عندما لا يصل المال: تحذير ثم إيقاف            | هل يستمر العميل في الخدمة؟   |
| الأحداث Events / Webhooks | إبلاغ بقية أنظمتك بكل تغيير                           | من يحتاج أن يعرف؟            |

وهذه الأجزاء هي ما تقدمه محركات الفوترة الجاهزة، سواءً كانت خدمة مدفوعة أو مشروعاً مفتوح المصدر، وهي ما سوف نراه يعمل في المختبر.

## المصطلحات الأساسية في الفوترة Billing Terms

قبل الدخول في الحالات، هذه الكلمات التي ستتكرر في المقال وفي أي محرك فوترة:

| المصطلح                     | المعنى                                            | مثال من المختبر                     |
| --------------------------- | ------------------------------------------------- | ----------------------------------- |
| المنتج Product              | ما تبيعه بغض النظر عن السعر والمدة                | Basic وPro                          |
| الخطة Plan                  | منتج بسعر وفترة فوترة محددة                       | basic-monthly بسعر 99 ريالاً شهرياً |
| المرحلة Phase               | جزء من عمر الخطة له سعر مختلف                     | TRIAL لمدة 14 يوماً ثم EVERGREEN    |
| فترة الفوترة Billing Period | المدة التي تغطيها كل فاتورة                       | شهر من 15 إلى 15                    |
| يوم الفوترة Bill Cycle Day  | اليوم من الشهر الذي تصدر فيه فواتير الحساب        | 15                                  |
| الدفع مقدماً In Advance     | العميل يدفع في بداية الفترة عن الفترة القادمة     | كل خطط المختبر                      |
| الاستحقاق Entitlement       | حق العميل في استخدام الخدمة، وهو منفصل عن الفوترة | يتوقف عند الإيقاف ويعود بعد الدفع   |
| الرصيد Account Balance      | ما على العميل من فواتير غير مدفوعة                | 99 ريالاً بعد فشل التجديد           |

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

## دورة حياة الاشتراك Subscription Lifecycle

الصورة التالية تبين الحالات التي يمر بها اشتراك واحد في المختبر، من التجربة المجانية حتى الإلغاء:

![خمس بطاقات متصلة بأسهم: 1 تجربة مجانية TRIAL لمدة 14 يوماً بفاتورة صفر، 2 نشط ACTIVE فاتورة كل شهر ودفع تلقائي، 3 تحذير WARNING بعد 7 أيام دون دفع والخدمة مستمرة، 4 موقوف SUSPENDED أو BLOCKED بعد 14 يوماً دون دفع والخدمة متوقفة، 5 ملغي CANCELLED في نهاية الفترة المدفوعة، وتحتها أن دفع الفاتورة المتأخرة يعيد الحساب إلى نشط فوراً والإلغاء لا ينهي الخدمة قبل نهاية ما دفعه العميل](https://arabroot.io/content/images/2026/11/recurring-billing-01-lifecycle.webp)

كل سهم في الصورة قاعدة تكتبها مرة في الإعداد، لا كود تكرره في كل مكان

وفي الأقسام التالية نأخذ كل انتقال على حدة: ما القرار الذي عليك أن تتخذه فيه، وما الخيارات، وما الذي يحدث إذا لم تتخذه.

## التجربة المجانية Free Trial

التجربة المجانية مرحلة أولى في الخطة سعرها صفر. وأول قرار فيها: هل تطلب البطاقة عند بداية التجربة أم لا؟

| الخيار                         | ما يحدث في نهاية التجربة                      | متى يناسب                         |
| ------------------------------ | --------------------------------------------- | --------------------------------- |
| التجربة مع بطاقة Card Required | يتحول الاشتراك إلى مدفوع ويخصم السعر تلقائياً | عندما تريد أن يستمر من لم يلغ     |
| التجربة دون بطاقة No Card      | تنتهي التجربة ويطلب من العميل أن يدفع ليستمر  | عندما تريد عدداً أكبر من المجربين |

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

📘

في 25 سبتمبر 2025 أعلنت هيئة التجارة الفيدرالية الأمريكية FTC تسوية مع Amazon بقيمة 2.5 مليار دولار، منها مليار دولار غرامة مدنية و1.5 مليار تعويضات، في قضية اشتراك Prime. وقالت الهيئة إن نحو 35 مليون مستهلك تأثروا بالاشتراك دون رغبتهم أو بتعقيد الإلغاء عليهم. والدرس لأي منتج اشتراكات: مسار الإلغاء جزء من الفوترة، وليس صفحة تخفيها في الإعدادات. المصدر: [بيان هيئة التجارة الفيدرالية](https://www.ftc.gov/news-events/news/press-releases/2025/09/ftc-secures-historic-25-billion-settlement-against-amazon?ref=arabroot.io).

والقرار الثاني: ماذا تحتسب فترة الفوترة بعد التجربة؟ في المختبر بدأت التجربة في 1 مارس، وانتهت في 15 مارس، فصار يوم الفوترة 15 من كل شهر. وهذا يعني أن الفاتورة المدفوعة الأولى تغطي من 15 مارس إلى 15 أبريل، لا من 1 مارس. وبعض المنتجات تفضل أن تكون كل الفواتير في الأول من الشهر لتسهيل الحسابات، فتصدر فاتورة أولى جزئية بالتناسب حتى أول الشهر التالي. وكلا الخيارين صحيح، ولكن اختر واحداً واكتبه في الكتالوج، لا في كود متفرق.

## الترقية والتخفيض Upgrade / Downgrade والتناسب Proration

عندما يغير العميل خطته في منتصف الفترة، فأمامك سؤالان: متى يسري التغيير؟ وكيف تحاسب على الأيام الباقية؟

### متى يسري التغيير؟ Change Policy

| السياسة                    | ماذا يحدث                                                     | الاستخدام الشائع                                                     |
| -------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------- |
| فوراً IMMEDIATE            | الخطة الجديدة تبدأ اليوم، مع تسوية الأيام الباقية             | الترقية: العميل يريد الميزات الآن، وأنت تريد المال الإضافي الآن      |
| نهاية الفترة END\_OF\_TERM | تبقى الخطة الحالية حتى نهاية الفترة المدفوعة، ثم تبدأ الجديدة | التخفيض: دفع العميل ثمن الشهر كاملاً فيأخذه كاملاً، ولا ترد له شيئاً |

والسبب في جعل التخفيض في نهاية الفترة ليس البخل، وإنما البساطة. فالتخفيض الفوري يعني رصيداً دائناً للعميل Credit، وهذا الرصيد إما أن تعيده نقداً، وفي ذلك رسوم استرداد، وإما أن تخصمه من الفواتير القادمة، وفي ذلك سؤال إضافي في المحاسبة ودعم العملاء. والتخفيض في نهاية الفترة يتجنب الاثنين، والعميل يفهمه بسهولة.

### حساب التناسب Proration

في المختبر رقى العميل من Basic بسعر 99 ريالاً إلى Pro بسعر 199 ريالاً في 25 مارس، وفترته الحالية من 15 مارس إلى 15 أبريل. والصورة التالية تبين الفاتورة التي أصدرها المحرك بالضبط:

![جدول من ثلاثة صفوف: Pro من يوم الترقية للفترة من 2026-03-25 إلى 2026-04-15 بحساب 199 ضرب 21 على 31 يساوي 134.81، ورصيد Basic غير المستخدم للفترة نفسها بحساب 99 ضرب 21 على 31 يساوي سالب 67.06، وصافي الفاتورة رقم 3 تدفع فوراً 134.81 ناقص 67.06 يساوي 67.75، وتحته أن Kill Bill يسمي سطر الخصم REPAIR_ADJ والشهر 31 يوماً](https://arabroot.io/content/images/2026/11/recurring-billing-02-proration.webp)

الأيام الباقية 21 من 31، فيدفع العميل الفرق عنها فقط

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

وهناك أسئلة صغيرة يجب أن تقرر فيها وتكتبها:

- **التقريب Rounding:** إلى أقرب هللة، وفي كل بند على حدة أم في الإجمالي؟ لأن 134.81 ناقص 67.06 قد لا يساوي حساب الفرق مباشرة ثم تقريبه.
- **الترقية المتكررة:** عميل رقى ثم خفض ثم رقى في نفس الأسبوع. كل تغيير فوري يولد بنوداً جديدة، فتأكد أن المحرك يعكس البنود السابقة بدقة ولا يضاعفها.
- **الترقية أثناء التجربة:** في المختبر جعلنا أي تغيير أثناء التجربة فورياً، لأنه لا يوجد مال مدفوع ليسوى.

## مقدماً أم مؤخراً؟ In Advance وIn Arrear والفوترة حسب الاستخدام

كل ما سبق افترض أن العميل يدفع في بداية الفترة عن الفترة القادمة، وهذا هو الدفع مقدماً In Advance، وهو الشائع في الاشتراكات الثابتة مثل اشتراك النادي. ولكن بعض المنتجات لا تعرف المبلغ إلا في نهاية الفترة، مثل منصة رسائل تحاسب على عدد الرسائل المرسلة، أو خدمة سحابية تحاسب على ساعات التشغيل. وهنا تكون الفوترة مؤخراً In Arrear: تجمع الاستخدام Usage طوال الشهر، ثم تصدر الفاتورة بعد انتهائه.

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

ويضيف الاستخدام سؤالاً جديداً هو سؤال البيانات: من أين يأتي رقم الاستخدام؟ ومن يضمن أن الحدث نفسه لم يحسب مرتين؟ والجواب هو نفس جواب الدفع: كل سجل استخدام يحمل معرفاً فريداً من نظامك، والمحرك يرفض المكرر. وفي هذا المقال نبقى مع الاشتراك الثابت، لأنه الأساس الذي تبنى عليه الحالات الأخرى.

## فشل الدفع وإعادة المحاولة Retries والتحصيل Dunning

في أي منتج اشتراكات سوف تفشل نسبة من عمليات التجديد كل شهر، لأسباب أغلبها لا علاقة لها برغبة العميل: بطاقة انتهت صلاحيتها، أو رصيد غير كاف يوم التجديد، أو حد شهري للبطاقة، أو رفض احترازي من البنك. ولهذا التسرب اسم في مقاييس الشركات: التسرب غير الطوعي Involuntary Churn، أي عميل خرج دون أن يقرر الخروج. وفي [مقال مقاييس شركات SaaS](https://arabroot.io/articles/%D9%85%D9%82%D8%A7%D9%8A%D9%8A%D8%B3-%D8%B4%D8%B1%D9%83%D8%A7%D8%AA-saas-%D8%A7%D9%84%D8%A7%D9%8A%D8%B1%D8%A7%D8%AF-%D8%A7%D9%84%D9%85%D8%AA%D9%83%D8%B1%D8%B1-mrr-%D9%88%D8%A7%D9%84%D8%AA%D8%B3%D8%B1%D8%A8-churn/) شرحنا كيف يظهر في أرقام التسرب Churn والإيراد المتكرر MRR.

والتحصيل Dunning هو مجموع ما تفعله لاستعادة هذا المال قبل أن تفقد العميل، وله طبقتان:

1. **إعادة المحاولة التلقائية Retries:** النظام يعيد طلب الدفع من البطاقة نفسها بعد أيام، لأن كثيراً من حالات الرفض مؤقتة.
2. **مراحل الحساب Overdue States:** كلما طالت مدة الفاتورة دون دفع، انتقل الحساب إلى مرحلة أشد: تذكير، ثم تحذير، ثم إيقاف للخدمة.

والصورة التالية تبين الجدول الذي طبقناه في المختبر، وكل تاريخ فيها من مخرجات حقيقية سوف نراها في قسم المختبر:

![ست بطاقات زمنية: 15 أبريل التجديد Renewal فاتورة 99 ريالاً والدفع يفشل، 17 أبريل Retry 1 بعد يومين تفشل، 21 أبريل Retry 2 بعد 4 أيام تفشل، 22 أبريل WARNING بعد 7 أيام دون دفع ورسالة تذكير، 28 أبريل Retry 3 بعد 7 أيام آخر محاولة، 29 أبريل SUSPENDED بعد 14 يوماً دون دفع وإيقاف الخدمة، وتحتها أن جدول المحاولات من الإعداد org.killbill.payment.retry.days=2,4,7 ومراحل التحصيل من ملف overdue.xml](https://arabroot.io/content/images/2026/11/recurring-billing-03-dunning.webp)

أسبوعان من التجديد الفاشل حتى الإيقاف، وثلاث محاولات بينهما

وفي تصميم هذا الجدول قرارات يجب أن تتخذها أنت لا المحرك:

- **عدد المحاولات وتباعدها:** محاولات كثيرة متقاربة على بطاقة مرفوضة قد يراها البنك سلوكاً مريباً، ومحاولات قليلة متباعدة تضيع فرصة يوم وصول الراتب. لذلك اجعلها قليلة ومتباعدة بشكل متزايد.
- **متى تتوقف الخدمة:** إيقاف الخدمة في يوم الفشل الأول يعاقب عميلاً لم يعرف بالمشكلة بعد، وتركها تعمل شهراً كاملاً يعطي خدمة مجانية. والمختبر يوقفها بعد 14 يوماً.
- **من يخبر العميل وكيف:** رسالة واضحة فيها المبلغ وسبب الفشل إن عرف ورابط مباشر لتحديث البطاقة. وهذه الرسالة تخرج من حدث يصلك من المحرك، كما سنرى في قسم الأحداث.
- **ماذا يحدث عند الدفع:** هل تعود الخدمة فوراً؟ وهل تحاسب العميل عن أيام الإيقاف؟ في المختبر عادت الخدمة في نفس اللحظة.

⚠️

لا تقم بحذف بيانات العميل أو اشتراكه عند الإيقاف بسبب عدم الدفع. والسبب أن أغلب هؤلاء يدفعون بعد تحديث البطاقة، وإذا وجدوا حسابهم فارغاً فقدتهم مرتين. الإيقاف حالة مؤقتة، والإلغاء قرار منفصل.

## الفواتير وضريبة القيمة المضافة Invoices and VAT

كل حركة مال في الاشتراك يجب أن تخرج من فاتورة، وكل فاتورة تتكون من بنود Items بتواريخ: بند متكرر للفترة، وبند تسوية للترقية، وبند ضريبة. وهذا ما يجعل الفاتورة قابلة للتدقيق بعد سنة: تعرف بالضبط لماذا دفع العميل 67.75 في 25 مارس.

وفي المملكة نسبة ضريبة القيمة المضافة 15%، والمنشأة المسجلة تضيفها على فواتيرها وترفع إقراراتها، كما شرحنا في [مقال الزكاة وضريبة القيمة المضافة للشركة الناشئة](https://arabroot.io/articles/%D8%A7%D9%84%D8%B2%D9%83%D8%A7%D8%A9-%D9%88%D8%B6%D8%B1%D9%8A%D8%A8%D8%A9-%D8%A7%D9%84%D9%82%D9%8A%D9%85%D8%A9-%D8%A7%D9%84%D9%85%D8%B6%D8%A7%D9%81%D8%A9-vat-%D9%84%D9%84%D8%B4%D8%B1%D9%83%D8%A9-%D8%A7%D9%84%D9%86%D8%A7%D8%B4%D8%A6%D8%A9/). ويضاف إلى ذلك الفوترة الإلكترونية فاتورة، وهي في [مقال الفوترة الإلكترونية](https://arabroot.io/articles/%D8%A7%D9%84%D9%81%D9%88%D8%AA%D8%B1%D8%A9-%D8%A7%D9%84%D8%A7%D9%84%D9%83%D8%AA%D8%B1%D9%88%D9%86%D9%8A%D8%A9-%D9%81%D8%A7%D8%AA%D9%88%D8%B1%D8%A9-zatca-%D9%83%D9%8A%D9%81-%D8%AA%D8%B1%D8%A8%D8%B7-%D9%86%D8%B8%D8%A7%D9%85%D9%83/). ما يهمنا هنا هو أثر الضريبة على تصميم الفوترة المتكررة:

- **السعر شامل الضريبة أم قبلها؟** قرر هذا مرة واحدة واكتبه في الكتالوج. في المختبر السعر 99 ريالاً قبل الضريبة، فتصبح الفاتورة 113.85.
- **الضريبة على صافي الفاتورة:** إذا كان في الفاتورة بند خصم أو رصيد من ترقية، فالضريبة على الصافي بعده، لا على السعر الكامل.
- **الضريبة قبل الدفع:** يجب أن تكتمل الفاتورة ببند الضريبة قبل أن يطلب النظام المال. فإذا خصمت 99 ثم أضفت الضريبة لاحقاً، فقد صنعت فاتورة ثانية ومحاولة دفع ثانية لا يفهمها العميل.
- **الاسترداد والإشعار الدائن:** عندما ترد مالاً لعميل، فالضريبة المرتبطة به تعود أيضاً، والمستند الصحيح لذلك إشعار دائن Credit Note لا تعديل الفاتورة الأصلية.

والنقطة الثالثة هي التي تجعل الضريبة مشكلة تصميم لا مشكلة حساب. فمحركات الفوترة تحسب الضريبة بإحدى طريقتين: إضافة Plugin تحسبها أثناء توليد الفاتورة، أو فاتورة مسودة Draft تضيف إليها الضريبة ثم تعتمدها. وفي المختبر استخدمنا الطريقة الثانية لأنها تعمل في النسخة المفتوحة دون إضافة مدفوعة، والصورة التالية تلخصها:

![أربع بطاقات متصلة: 1 مسودة DRAFT invoice اشتراك Basic بمبلغ 99.00، 2 بند الضريبة TAX item 15% من الصافي بمبلغ 14.85، 3 اعتماد COMMITTED الإجمالي 113.85، 4 دفع تلقائي PAYMENT SUCCESS الرصيد 0.00، وتحتها أن الضريبة تحسب على صافي الفاتورة بعد أي خصم أو رصيد قبل أن يدفع العميل](https://arabroot.io/content/images/2026/11/recurring-billing-04-vat.webp)

الفاتورة لا تخرج للدفع إلا وهي مكتملة ببند الضريبة

## منع الخصم المكرر Idempotency

الخصم المكرر هو الخطأ الذي لا يغفره العميل. ومصادره في الفوترة المتكررة كثيرة:

- المهمة الليلية تعمل مرتين لأن نسختين من التطبيق تعملان معاً.
- انقطع الاتصال مع بوابة الدفع بعد إرسال الطلب، فأعاد الكود المحاولة.
- العميل ضغط زر «ادفع الآن» مرتين بعد تحديث بطاقته.
- وصل نفس الحدث Webhook مرتين، فعالجه النظام مرتين.

والحل في كل الحالات واحد: مفتاح فريد لكل عملية Idempotency Key تولده أنت قبل الطلب، وترسله معه، فإذا وصل الطلب نفسه مرة ثانية بالمفتاح نفسه رفضه الطرف الآخر أو أعاد النتيجة الأولى دون تنفيذ جديد. وفي [مقال Idempotency](https://arabroot.io/articles/idempotency-%D9%83%D9%8A%D9%81-%D8%AA%D8%AC%D8%B9%D9%84-%D8%A7%D9%84%D8%B9%D9%85%D9%84%D9%8A%D8%A9-%D8%A7%D9%85%D9%86%D8%A9-%D8%B9%D9%86%D8%AF-%D8%AA%D9%83%D8%B1%D8%A7%D8%B1%D9%87%D8%A7/) شرحنا الفكرة وطرق تطبيقها في أي نظام.

وفي محرك الفوترة يظهر هذا المفتاح في مكانين سوف نراهما في المختبر: المفتاح الخارجي للحساب External Key، فلا يمكن إنشاء حسابين لنفس العضو، والمفتاح الخارجي لعملية الدفع Transaction External Key، فلا يمكن تنفيذ نفس الدفعة الناجحة مرتين. واجعل هذه المفاتيح من بيانات نظامك أنت، مثل رقم العضو ورقم الطلب، لا أرقاماً عشوائية تولد عند كل محاولة، لأن المفتاح العشوائي الجديد في كل محاولة لا يمنع شيئاً.

## الأحداث Webhooks: كيف يعرف نظامك ما حدث؟

محرك الفوترة يعمل في الخلفية: يجدد ويخصم ويعيد المحاولة ويوقف، وكل هذا دون طلب من تطبيقك. فكيف يعرف تطبيقك أن الاشتراك توقف ليمنع العضو من حجز الحصص؟ يرسل له المحرك حدثاً Webhook، أي طلب HTTP إلى عنوان تحدده، فيه نوع الحدث ومعرف الكائن الذي تغير.

وهنا ثلاث حقائق يجب أن يبنى عليها مستقبل الأحداث، وكلها ظهرت في المختبر:

1. **الأحداث لا تصل بالترتيب:** في سجل المختبر وصل حدث ENTITLEMENT\_CREATION قبل SUBSCRIPTION\_CREATION، ووصلت أحداث إعدادات المستأجر بينهما. فلا تبن منطقك على أن الحدث السابق وصل قبل اللاحق.
2. **الحدث قد يتكرر:** وصل حدث SUBSCRIPTION\_CREATION مرتين لنفس الاشتراك، وتكرر INVOICE\_PAYMENT\_FAILED مع كل محاولة. لذلك سجل ما عالجته، واجعل المعالجة آمنة عند التكرار.
3. **الحدث رقيق Thin Event:** فيه نوع الحدث ومعرف الكائن وبعض البيانات الوصفية، لا الفاتورة كاملة. والطريقة الصحيحة أن تقرأ الحالة الحالية من الواجهة البرمجية API، ثم تتصرف بناءً عليها، لا على ما في الحدث.

والصورة التالية تجمع الخطوات التي يجب أن يمر بها كل حدث في نظامك:

![خمس بطاقات متصلة: 1 الحدث يصل POST /hooks فيه نوع الحدث ومعرف الكائن فقط، 2 تحقق من المصدر Verify source بشبكة خاصة أو توقيع أو رمز سري، 3 منع التكرار Dedupe سجل ما عالجته وتجاهل المكرر، 4 رد 200 بسرعة Ack fast وضع الحدث في طابور ثم المعالجة، 5 اقرأ الحالة من API قبل التصرف ولا تثق بترتيب الأحداث، وتحتها أن Kill Bill يعيد الإرسال إذا لم يرد المستقبل بنجاح](https://arabroot.io/content/images/2026/11/recurring-billing-05-webhooks.webp)

المستقبل الجيد سريع في الرد، بطيء في الثقة

ولاحظ الخطوة الثانية. فبعض الخدمات توقع كل حدث بتوقيع HMAC في ترويسة الطلب، وتتحقق أنت منه بمفتاح سري. أما Kill Bill فلا يرسل توقيعاً: الترويسات التي وصلت مستقبل المختبر كانت Content-Type وUser-Agent وأمثالها فقط، كما سنرى. لذلك اجعل عنوان الاستقبال داخل شبكتك الخاصة لا على الإنترنت، أو ضع في العنوان رمزاً سرياً طويلاً، وفي كل الأحوال اقرأ الحالة من الواجهة البرمجية قبل أن تتصرف.

## بعد الإطلاق: المطابقة Reconciliation ونقل المشتركين Migration

محرك الفوترة يعرف ما طلبه من العملاء وما قالت بوابة الدفع إنه نجح، ولكنه لا يعرف ما وصل حسابك البنكي فعلاً. فبين نجاح الدفع ووصول المال إلى حسابك توجد التسوية Settlement، ورسوم مزود الدفع، والاستردادات، والاعتراضات التي تصل بعد أسابيع. لذلك يجب أن تطابق كل يوم ثلاثة مصادر: فواتير المحرك ودفعاته، وتقرير التسوية من مزود الدفع، وكشف حسابك البنكي. وفي [مقال المطابقة Reconciliation](https://arabroot.io/articles/%D8%A7%D9%84%D9%85%D8%B7%D8%A7%D8%A8%D9%82%D8%A9-reconciliation-%D9%83%D8%B4%D9%81-%D8%A7%D9%84%D8%A8%D9%86%D9%83-%D9%85%D9%82%D8%A7%D8%A8%D9%84-%D9%86%D8%B8%D8%A7%D9%85%D9%83/) شرحنا هذه العملية خطوة بخطوة، وفيه ستجد أن أغلب الفروقات تأتي من الحالات التي مررنا بها هنا: دفعة مكررة، أو استرداد لم يسجل، أو فاتورة دفعت بعد الإيقاف.

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

## تبني أم تستخدم محركاً جاهزاً؟ Build or Buy

بعد كل ما سبق يظهر السؤال الطبيعي: هل تكتب كل هذا بنفسك؟ والخيارات ثلاثة:

| الخيار                              | نقاط القوة                                          | نقاط الضعف                                                              |
| ----------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------- |
| تكتبه بنفسك                         | تحكم كامل، ولا اعتماد على أحد                       | كل حالة في هذا المقال كود تكتبه وتختبره وتصونه، والأخطاء في مال العملاء |
| فوترة مزود الدفع Billing من البوابة | أسرع بداية، والبطاقة والتجديد في مكان واحد          | مرتبط بمزود واحد، وقد لا يدعم كل وسائل الدفع المحلية التي تريدها        |
| محرك مفتوح المصدر                   | منطق فوترة مكتمل على سيرفرك، ويعمل مع أكثر من بوابة | تشغله وتحدثه وتراقبه بنفسك، وبعض الميزات في نسخ مدفوعة                  |

ومن المحركات المفتوحة المعروفة [Kill Bill](https://github.com/killbill/killbill?ref=arabroot.io) بترخيص Apache-2.0، وهو مشروع Java قديم ناضج، و[Lago](https://github.com/getlago/lago?ref=arabroot.io) بترخيص AGPL-3.0\. واخترنا Kill Bill للمختبر لسبب واحد مهم: فيه وضع اختبار Test Mode يسمح بتحريك ساعة النظام، فنرى نهاية التجربة والتجديد وإعادة المحاولة والإيقاف في دقائق، بدل أن ننتظر شهراً. وهذه الميزة نفسها هي ما يجب أن تطلبه من أي محرك قبل أن تعتمده: كيف أختبر ما يحدث بعد ثلاثين يوماً دون أن أنتظر ثلاثين يوماً؟

وأي خيار اخترته، فالبطاقة نفسها لا تحفظ عندك، وإنما تحفظ عند مزود الدفع، ويحفظ نظامك رمزاً Token يمثلها، كما شرحنا في [مقال PCI DSS والترميز Tokenization](https://arabroot.io/articles/%D8%A7%D9%85%D9%86-%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA-%D8%A7%D9%84%D8%A8%D8%B7%D8%A7%D9%82%D8%A7%D8%AA-pci-dss-%D9%88%D8%A7%D9%84%D8%AA%D8%B1%D9%85%D9%8A%D8%B2-tokenization/). ومحرك الفوترة يطلب الخصم بهذا الرمز عبر إضافة الدفع Payment Plugin الخاصة بمزودك.

## المختبر: ثلاثة أشهر من حياة اشتراك على Kill Bill

سوف نشغل الآن Kill Bill في Docker، ونعرف فيه خطتين، ونمر بالقصة كاملة: تجربة مجانية، ثم تجديد، ثم ترقية في منتصف الشهر، ثم تخفيض، ثم بطاقة تفشل وإعادة محاولة وتحذير وإيقاف، ثم دفع وعودة، ثم ضريبة القيمة المضافة، ثم دفعة مكررة، ثم إلغاء. والصورة التالية تبين مكونات المختبر:

![أربع بطاقات: السكربت fin4-cli على alpine مع curl وjq يرسل طلبات API إلى Kill Bill، ومحرك الفوترة fin4-killbill بإصدار Kill Bill 0.24.22 للكتالوج والفواتير والدفع والتحصيل، وقاعدة البيانات fin4-db بإصدار MariaDB 11.8 للحسابات والاشتراكات والفواتير، ومستقبل الأحداث fin4-hooks على Python 3.13 يستقبل الأحداث من Kill Bill، وتحتها أن إضافة payment-test تحاكي بوابة الدفع فتنجح أو تفشل بأمر منا ولا بطاقات حقيقية في المختبر](https://arabroot.io/content/images/2026/11/recurring-billing-06-lab.webp)

أربع حاويات صغيرة، ولا بطاقة حقيقية ولا مفتاح لمزود دفع

ولاحظ أن المختبر لا يتصل بأي بوابة دفع حقيقية. فبدلها نستخدم إضافة payment-test من مشروع Kill Bill نفسه، وهي إضافة دفع وهمية نأمرها أن تنجح أو تفشل، فنرى سلوك المحرك عند الفشل دون بطاقة ولا مفتاح سري.

### ملف التشغيل docker-compose.yml

الملف التالي يشغل قاعدة البيانات ومحرك الفوترة ومستقبل الأحداث:

```yaml
# Kill Bill billing engine + MariaDB + a tiny webhook receiver.
# Test mode is on so the lab can move Kill Bill's clock forward (trial end, renewals, dunning).
name: fin4
services:
  db:
    image: killbill/mariadb:0.24
    container_name: fin4-db
    environment:
      MYSQL_ROOT_PASSWORD: killbill
  killbill:
    image: killbill/killbill:0.24.22
    container_name: fin4-killbill
    depends_on: [db]
    ports: ["9580:8080"]
    environment:
      KILLBILL_DAO_URL: jdbc:mysql://db:3306/killbill
      KILLBILL_DAO_USER: root
      KILLBILL_DAO_PASSWORD: killbill
      KB_org_killbill_server_test_mode: "true"
      KB_org_killbill_payment_retry_days: "2,4,7"
  hooks:
    image: python:3.13-slim
    container_name: fin4-hooks
    volumes: ["./hooks.py:/hooks.py:ro"]
    command: ["python", "-u", "/hooks.py"]
```

في الإعداد أعلاه لاحظ التالي:

- الصورة `killbill/mariadb:0.24` قاعدة MariaDB فيها جداول Kill Bill جاهزة، فلا نحتاج إنشاء الجداول بأنفسنا.
- المتغير `KB_org_killbill_server_test_mode` يفعل وضع الاختبار، ومنه واجهة `/1.0/kb/test/clock` لتحريك الساعة. ولا تفعله في الإنتاج إطلاقاً، لأن من يصل إلى هذه الواجهة يستطيع أن يقدم الزمن فيجدد كل الاشتراكات.
- المتغير `KB_org_killbill_payment_retry_days` يحدد جدول إعادة المحاولة: بعد يومين، ثم أربعة، ثم سبعة. وأي خاصية من خصائص Kill Bill تكتب بهذا الشكل: `KB_` ثم اسمها مع استبدال النقاط بشرطة سفلية.
- المنفذ 9580 على جهازك يقابل 8080 داخل الحاوية، حتى لا يتعارض مع خدمة أخرى تستخدم 8080.

ومستقبل الأحداث سكربت Python صغير يطبع سطراً لكل حدث، ويطبع أول حدث فشل دفع كاملاً مع ترويساته:

```python
# Receives Kill Bill push notifications and prints one line per event.
# The first INVOICE_PAYMENT_FAILED event is printed in full, with its headers.
import json
from http.server import BaseHTTPRequestHandler, HTTPServer

shown = False

class Hook(BaseHTTPRequestHandler):
    def do_POST(self):
        global shown
        body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        e = json.loads(body or b"{}")
        print(e.get("eventType"), e.get("objectType"), e.get("objectId"), sep=" | ")
        if e.get("eventType") == "INVOICE_PAYMENT_FAILED" and not shown:
            shown = True
            print(dict(self.headers))
            print(json.dumps(e, indent=2))
        self.send_response(200)
        self.end_headers()

    def log_message(self, *args):
        pass

HTTPServer(("0.0.0.0", 8000), Hook).serve_forever()
```

### التشغيل وإضافة الدفع التجريبية payment-test

يحتاج Kill Bill بعد تشغيله إلى تثبيت إضافة payment-test وجداولها، وهذا ما يفعله السكربت التالي:

```bash
#!/bin/sh
# Starts the stack, installs the payment-test plugin and its tables, then restarts Kill Bill.
set -e
docker compose up -d
until curl -sf http://localhost:9580/1.0/healthcheck >/dev/null; do sleep 5; done
docker exec fin4-killbill /opt/kpm-latest/kpm install_java_plugin payment-test --destination=/var/lib/killbill/bundles
docker exec fin4-killbill sh -c 'cd /tmp && unzip -o -q $(ls /var/lib/killbill/bundles/plugins/java/payment-test-plugin/[0-9]*/*.jar) ddl.sql'
docker exec fin4-killbill cat /tmp/ddl.sql | docker exec -i fin4-db mariadb -uroot -pkillbill killbill
docker restart fin4-killbill
until curl -sf http://localhost:9580/1.0/healthcheck >/dev/null; do sleep 5; done
echo ready
```

والأداة `kpm` هي مدير إضافات Kill Bill، وهي موجودة داخل الصورة. وعند التشغيل سوف تجد أنها اختارت الإصدار المناسب لنسخة المحرك تلقائياً:

```text
Cannot read termcap database;
using dumb terminal settings.
I, [2026-11-16T16:16:21.839439 #122]  INFO -- :       Starting download of org.kill-bill.billing.plugin.java:payment-test-plugin:jar:8.0.1 to /tmp/d20261116-122-t4ydch
I, [2026-11-16T16:16:24.503027 #122]  INFO -- : Successful installation of org.kill-bill.billing.plugin.java:payment-test-plugin:jar:8.0.1 to /var/lib/killbill/bundles/plugins/java/payment-test-plugin/8.0.1
Artifact has been retrieved and can be found at path: /var/lib/killbill/bundles/plugins/java/payment-test-plugin/8.0.1/payment-test-plugin-8.0.1.jar
fin4-killbill
ready
```

ولاحظ سطري استخراج ملف `ddl.sql` من داخل ملف الإضافة وتنفيذه على قاعدة البيانات. فهذه الخطوة لا يذكرها أمر التثبيت، وإذا نسيتها فسوف تنجح كل الخطوات حتى تضيف أول وسيلة دفع، ثم يرد المحرك بالخطأ 500 ومعه الرسالة التالية:

```text
"code":7019,"message":"Internal payment error : org.jooq.exception.DataAccessException:
... Table 'killbill.testpayment_payment_methods' doesn't exist"
```

والسبب أن الإضافات في Kill Bill تحمل جداولها الخاصة في ملف `ddl.sql` داخلها، والمحرك لا ينشئها تلقائياً. وهذه القاعدة تنطبق على إضافات الدفع الحقيقية أيضاً، فإذا رأيت خطأ «Table doesn't exist» بعد تثبيت أي إضافة فابحث عن هذا الملف أولاً.

⚠️

إذا شغلت السكربت من Git Bash على Windows، فسوف يحول المسار `/opt/kpm-latest/kpm` إلى مسار Windows ويفشل الأمر برسالة «no such file or directory». شغله بعد `export MSYS_NO_PATHCONV=1`، أو من WSL أو Linux.

### الكتالوج Catalog: الخطط والأسعار وقواعد التغيير

الكتالوج ملف XML يصف كل ما نبيعه، ونرفعه للمحرك مرة واحدة. وهذا هو الملف كاملاً:

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<catalog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="CatalogSchema.xsd">
  <effectiveDate>2026-01-01T00:00:00+00:00</effectiveDate>
  <catalogName>GymApp</catalogName>
  <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
  <currencies>
    <currency>SAR</currency>
  </currencies>
  <products>
    <product name="Basic"><category>BASE</category></product>
    <product name="Pro"><category>BASE</category></product>
  </products>
  <rules>
    <changePolicy>
      <changePolicyCase><phaseType>TRIAL</phaseType><policy>IMMEDIATE</policy></changePolicyCase>
      <changePolicyCase><fromProduct>Pro</fromProduct><toProduct>Basic</toProduct><policy>END_OF_TERM</policy></changePolicyCase>
      <changePolicyCase><policy>IMMEDIATE</policy></changePolicyCase>
    </changePolicy>
    <changeAlignment>
      <changeAlignmentCase><alignment>START_OF_BUNDLE</alignment></changeAlignmentCase>
    </changeAlignment>
    <cancelPolicy>
      <cancelPolicyCase><policy>END_OF_TERM</policy></cancelPolicyCase>
    </cancelPolicy>
    <createAlignment>
      <createAlignmentCase><alignment>START_OF_BUNDLE</alignment></createAlignmentCase>
    </createAlignment>
    <billingAlignment>
      <billingAlignmentCase><alignment>ACCOUNT</alignment></billingAlignmentCase>
    </billingAlignment>
    <priceList>
      <priceListCase><toPriceList>DEFAULT</toPriceList></priceListCase>
    </priceList>
  </rules>
  <plans>
    <plan name="basic-monthly">
      <product>Basic</product>
      <initialPhases>
        <phase type="TRIAL">
          <duration><unit>DAYS</unit><number>14</number></duration>
          <fixed><fixedPrice/></fixed>
        </phase>
      </initialPhases>
      <finalPhase type="EVERGREEN">
        <duration><unit>UNLIMITED</unit></duration>
        <recurring>
          <billingPeriod>MONTHLY</billingPeriod>
          <recurringPrice><price><currency>SAR</currency><value>99.00</value></price></recurringPrice>
        </recurring>
      </finalPhase>
    </plan>
    <plan name="pro-monthly">
      <product>Pro</product>
      <finalPhase type="EVERGREEN">
        <duration><unit>UNLIMITED</unit></duration>
        <recurring>
          <billingPeriod>MONTHLY</billingPeriod>
          <recurringPrice><price><currency>SAR</currency><value>199.00</value></price></recurringPrice>
        </recurring>
      </finalPhase>
    </plan>
  </plans>
  <priceLists>
    <defaultPriceList name="DEFAULT">
      <plans>
        <plan>basic-monthly</plan>
        <plan>pro-monthly</plan>
      </plans>
    </defaultPriceList>
  </priceLists>
</catalog>
```

في الإعداد أعلاه لاحظ التالي:

- الخطة `basic-monthly` لها مرحلتان: `TRIAL` لمدة 14 يوماً بسعر ثابت فارغ أي صفر، ثم `EVERGREEN` بلا نهاية بسعر 99 ريالاً شهرياً. أما `pro-monthly` فلا تجربة فيها.
- العملة `SAR`، والفوترة `IN_ADVANCE` أي مقدماً في بداية كل فترة.
- قواعد التغيير `changePolicy` تقرأ من الأعلى: أي تغيير أثناء التجربة فوري، والانتقال من Pro إلى Basic في نهاية الفترة، وأي تغيير آخر، ومنه الترقية، فوري.
- الإلغاء `cancelPolicy` في نهاية الفترة، فلا يخسر العميل أياماً دفع ثمنها.
- `billingAlignment` بقيمة `ACCOUNT` يعني أن كل اشتراكات الحساب تفوتر في يوم واحد، فإذا أضاف العميل اشتراكاً ثانياً جاءت فاتورته مع الأول.

وشرح كل عناصر الكتالوج وقواعد المحاذاة في [دليل الاشتراكات في Kill Bill](https://docs.killbill.io/latest/userguide%5Fsubscription.html?ref=arabroot.io).

### مراحل التحصيل overdue.xml

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<overdueConfig>
  <accountOverdueStates>
    <initialReevaluationInterval><unit>DAYS</unit><number>1</number></initialReevaluationInterval>
    <state name="SUSPENDED">
      <condition>
        <timeSinceEarliestUnpaidInvoiceEqualsOrExceeds><unit>DAYS</unit><number>14</number></timeSinceEarliestUnpaidInvoiceEqualsOrExceeds>
      </condition>
      <externalMessage>Service suspended until the invoice is paid</externalMessage>
      <blockChanges>true</blockChanges>
      <disableEntitlementAndChangesBlocked>true</disableEntitlementAndChangesBlocked>
    </state>
    <state name="WARNING">
      <condition>
        <timeSinceEarliestUnpaidInvoiceEqualsOrExceeds><unit>DAYS</unit><number>7</number></timeSinceEarliestUnpaidInvoiceEqualsOrExceeds>
      </condition>
      <externalMessage>Payment overdue</externalMessage>
      <blockChanges>false</blockChanges>
      <disableEntitlementAndChangesBlocked>false</disableEntitlementAndChangesBlocked>
      <autoReevaluationInterval><unit>DAYS</unit><number>7</number></autoReevaluationInterval>
    </state>
  </accountOverdueStates>
</overdueConfig>
```

المراحل تكتب من الأشد إلى الأخف: `SUSPENDED` بعد 14 يوماً من أقدم فاتورة غير مدفوعة، وفيها `disableEntitlementAndChangesBlocked` أي إيقاف الخدمة ومنع تغيير الخطة، ثم `WARNING` بعد 7 أيام دون أي إيقاف. والسطر `autoReevaluationInterval` يجعل المحرك يعيد تقييم الحساب بعد 7 أيام من دخوله مرحلة التحذير، فينقله إلى الإيقاف إذا بقي دون دفع. وبقية خيارات هذا الملف، مثل الرسائل وشروط أخرى غير عمر الفاتورة، في [توثيق نظام التحصيل Overdue في Kill Bill](https://docs.killbill.io/latest/overdue.html?ref=arabroot.io).

### السكربت الكامل run.sh

بقية المختبر سكربت واحد يتحدث مع واجهة Kill Bill بالأداة curl ويقرأ الردود بالأداة jq. ونشغله من حاوية alpine على شبكة المختبر نفسها، فيصل إلى المحرك باسم `killbill`:

```bash
docker run --rm --name fin4-cli --network fin4_default -v "$PWD:/lab" -w /lab alpine:3.22 \
  sh -c "apk add -q curl jq && sh run.sh" | tee run.out
```

وأول جزء في السكربت دوال صغيرة يستخدمها في كل خطوة:

```bash
KB=http://killbill:8080/1.0/kb
AUTH="-u admin:password -H X-Killbill-CreatedBy:lab"
T="-H X-Killbill-ApiKey:gym -H X-Killbill-ApiSecret:gym-secret"
J="-H Content-Type:application/json"
kb() { curl -s $AUTH $T "$@"; }
# move the test clock N days (+1 hour, so jobs due "N days later" have surely run)
clock() {
  NOW=$(kb "$KB/test/clock" | jq -r '.currentUtcTime[0:19] + "Z" | fromdate')
  TO=$(jq -rn --argjson now "$NOW" --argjson d "$1" '$now + $d * 86400 + 3600 | todate')
  kb -X POST "$KB/test/clock?requestedDate=$TO&timeoutSec=20" | jq -r '"clock -> " + .localDate'
}
invoices() {
  for id in $(kb "$KB/accounts/$ACC/invoices" | jq -r '.[].invoiceId'); do
    kb "$KB/invoices/$id" | jq -r '"#\(.invoiceNumber) \(.invoiceDate) \(.status) amount=\(.amount) balance=\(.balance)",
      (.items[] | "    \(.itemType) \(.planName // "-") \(.startDate)..\(.endDate // "") \(.amount)")'
  done
}
settled() { for i in $(seq 1 20); do b=$(kb "$KB/accounts/$ACC?accountWithBalance=true" | jq -r .accountBalance); [ "$b" = "0" ] || [ "$b" = "0.00" ] || [ "$b" = "0.0" ] && break; sleep 1; done; echo "account balance=$b"; }
waitinv() { until [ "$(kb "$KB/accounts/$ACC/invoices" | jq length)" -ge "$1" ]; do sleep 1; done; }
overdue() { kb "$KB/accounts/$ACC/overdue" | jq -r '"overdue=\(.name) blockChanges=\(.isBlockChanges)"'; }
```

لاحظ الدالة `clock`: تقرأ ساعة المحرك، وتضيف إليها عدد الأيام المطلوب وساعة إضافية، ثم تضبط الساعة على الناتج. والساعة الإضافية ليست تفصيلاً، وسوف نشرح سببها في قسم المشكلات بعد قليل.

### الخطوة 1: المستأجر Tenant والكتالوج والأحداث

```bash
echo "== 1. tenant, catalog, dunning rules, webhook"
curl -s -o /dev/null -w "tenant %{http_code}\n" $AUTH $J -X POST $KB/tenants -d '{"apiKey":"gym","apiSecret":"gym-secret"}'
kb -o /dev/null -w "catalog %{http_code}\n" -H Content-Type:text/xml -X POST $KB/catalog/xml --data-binary @catalog.xml
kb -o /dev/null -w "overdue %{http_code}\n" -H Content-Type:text/xml -X POST $KB/overdue/xml --data-binary @overdue.xml
kb -o /dev/null -w "webhook %{http_code}\n" -X POST "$KB/tenants/registerNotificationCallback?cb=http://fin4-hooks:8000/"
kb -X POST "$KB/test/clock?requestedDate=2026-03-01T08:00:00.000Z" | jq -r '"clock -> " + .localDate'
```

والمخرج سوف يكون كما يلي:

```text
== 1. tenant, catalog, dunning rules, webhook
tenant 201
catalog 201
overdue 201
webhook 201
clock -> 2026-03-01
```

المستأجر Tenant في Kill Bill هو مساحة منفصلة لكل شركة أو منتج، بمفتاح وسر خاصين، ولكل مستأجر كتالوجه ومراحل تحصيله وعنوان أحداثه. ولاحظ أننا نضبط الساعة على 1 مارس 2026 قبل إنشاء أي حساب، فكل التواريخ بعدها تبدأ من هذا اليوم.

### الخطوة 2: الحساب Account، مرتين

```bash
echo "== 2. account (sent twice with the same externalKey)"
for n in 1 2; do
  kb -o /tmp/out -w "HTTP %{http_code} " $J -X POST $KB/accounts \
    -d '{"externalKey":"member-1001","name":"Member 1001","currency":"SAR","timeZone":"Asia/Riyadh"}'
  jq -r '.message // ""' /tmp/out 2>/dev/null || echo
done
ACC=$(kb "$KB/accounts?externalKey=member-1001" | jq -r .accountId); echo "accountId=$ACC"
kb -o /dev/null -w "payment method %{http_code}\n" $J -X POST "$KB/accounts/$ACC/paymentMethods?isDefault=true" \
  -d '{"pluginName":"killbill-payment-test","pluginInfo":{"properties":[]}}'
```

```text
== 2. account (sent twice with the same externalKey)
HTTP 201 HTTP 409 Account already exists for key member-1001
accountId=3ec48dc8-4b99-4693-abb1-9aa45487a5f7
payment method 201
```

أرسلنا طلب إنشاء الحساب نفسه مرتين بالمفتاح الخارجي `member-1001`، وهو رقم العضو في نظامنا. فنجح الأول بالرمز 201، ورفض الثاني بالرمز 409 والرسالة «Account already exists for key member-1001». وهذا هو منع التكرار على مستوى الحساب: لو أعاد تطبيقك إرسال طلب التسجيل بسبب انقطاع، فلن يولد عضواً ثانياً بفوترة ثانية.

### الخطوة 3 و4: الاشتراك ونهاية التجربة Trial

```bash
echo "== 3. subscribe to basic-monthly (14-day trial)"
kb -o /dev/null -w "subscription %{http_code}\n" $J -X POST $KB/subscriptions \
  -d "{\"accountId\":\"$ACC\",\"externalKey\":\"sub-1001\",\"planName\":\"basic-monthly\"}"
SUB=$(kb "$KB/subscriptions?externalKey=sub-1001" | jq -r .subscriptionId)
sleep 3; invoices

echo "== 4. trial ends"
clock 14; sleep 2; invoices
```

```text
== 3. subscribe to basic-monthly (14-day trial)
subscription 201
#1 2026-03-01 COMMITTED amount=0.00 balance=0.00
    FIXED basic-monthly 2026-03-01..2026-03-15 0.00
== 4. trial ends
clock -> 2026-03-15
#1 2026-03-01 COMMITTED amount=0.00 balance=0.00
    FIXED basic-monthly 2026-03-01..2026-03-15 0.00
#2 2026-03-15 COMMITTED amount=99.00 balance=0.00
    RECURRING basic-monthly 2026-03-15..2026-04-15 99.00
```

والمخرج يحكي ما حدث:

- الفاتورة رقم 1 في يوم الاشتراك بمبلغ صفر، فيها بند `FIXED` للتجربة من 1 إلى 15 مارس. وقد يبدو إصدار فاتورة صفرية غريباً، ولكنه يترك أثراً واضحاً: العميل كان في تجربة في هذه الفترة.
- بعد تحريك الساعة 14 يوماً صدرت الفاتورة رقم 2 بمبلغ 99 ريالاً للفترة من 15 مارس إلى 15 أبريل، ورصيدها صفر، أي أن إضافة الدفع خصمتها فوراً.
- لم نكتب أي كود لنهاية التجربة. فالانتقال من `TRIAL` إلى `EVERGREEN` مكتوب في الكتالوج، والمحرك نفذه عندما وصلت الساعة إلى موعده.

### الخطوة 5: الترقية Upgrade في اليوم العاشر

```bash
echo "== 5. upgrade to pro on day 10 of the period"
clock 10
kb -o /dev/null -w "change %{http_code}\n" $J -X PUT "$KB/subscriptions/$SUB" -d '{"planName":"pro-monthly"}'
waitinv 3; settled; invoices | tail -3
```

```text
== 5. upgrade to pro on day 10 of the period
clock -> 2026-03-25
change 204
account balance=0.00
#3 2026-03-25 COMMITTED amount=67.75 balance=0.00
    RECURRING pro-monthly 2026-03-25..2026-04-15 134.81
    REPAIR_ADJ - 2026-03-25..2026-04-15 -67.06
```

هذه هي الفاتورة التي رأيناها في قسم التناسب. بند `RECURRING` للخطة Pro من 25 مارس إلى 15 أبريل بمبلغ 134.81، وبند `REPAIR_ADJ` بسالب 67.06 يعيد للعميل نصيب نفس الأيام من خطة Basic التي دفعها مقدماً، والصافي 67.75 دفع فوراً. ولاحظ أن الفترة لم تتغير: ما زال التجديد في 15 أبريل، لأن الترقية لا تحرك يوم الفوترة.

### الخطوة 6: التخفيض Downgrade في نهاية الفترة

```bash
echo "== 6. downgrade back to basic (end of term)"
kb -o /dev/null -w "change %{http_code}\n" $J -X PUT "$KB/subscriptions/$SUB" -d '{"planName":"basic-monthly"}'
kb "$KB/subscriptions/$SUB" | jq -r '.events[] | select(.eventType=="CHANGE") | "\(.effectiveDate[0:10]) CHANGE -> \(.plan)"'
```

```text
== 6. downgrade back to basic (end of term)
change 204
2026-03-25 CHANGE -> pro-monthly
2026-04-15 CHANGE -> basic-monthly
```

طلبنا التخفيض في نفس اليوم، 25 مارس، ولكن المحرك سجله حدثاً مستقبلياً بتاريخ 15 أبريل، لأن قاعدة الكتالوج تقول إن الانتقال من Pro إلى Basic في نهاية الفترة. فيبقى العميل على Pro حتى نهاية ما دفعه، ولا تصدر أي فاتورة اليوم، ولا يوجد رصيد دائن نعيده.

### الخطوة 7: البطاقة تفشل، وإعادة المحاولة Retry

```bash
echo "== 7. the card starts failing; renewal, retries and dunning"
kb -o /dev/null -w "payment-test fail %{http_code}\n" $J -X POST http://killbill:8080/plugins/killbill-payment-test/configure \
  -d '{"CONFIGURE_ACTION":"ACTION_RETURN_PLUGIN_STATUS_ERROR"}'
for d in 21 2 4 1 6 1; do clock $d; overdue; done
kb "$KB/accounts/$ACC/payments?withAttempts=true" | jq -r '.[] | select(any(.transactions[]; .status=="PAYMENT_FAILURE")) | .paymentAttempts[] | "attempt \(.effectiveDate[0:10]) \(.stateName)"'
kb "$KB/subscriptions/$SUB" | jq -r '"subscription state=" + .state'
```

```text
== 7. the card starts failing; renewal, retries and dunning
payment-test fail 200
clock -> 2026-04-15
overdue=__KILLBILL__CLEAR__OVERDUE_STATE__ blockChanges=false
clock -> 2026-04-17
overdue=__KILLBILL__CLEAR__OVERDUE_STATE__ blockChanges=false
clock -> 2026-04-21
overdue=__KILLBILL__CLEAR__OVERDUE_STATE__ blockChanges=false
clock -> 2026-04-22
overdue=WARNING blockChanges=false
clock -> 2026-04-28
overdue=WARNING blockChanges=false
clock -> 2026-04-29
overdue=SUSPENDED blockChanges=true
attempt 2026-04-15 RETRIED
attempt 2026-04-17 RETRIED
attempt 2026-04-21 RETRIED
attempt 2026-04-28 ABORTED
subscription state=BLOCKED
```

أمرنا إضافة الدفع التجريبية أن تفشل كل عملية، ثم حركنا الساعة إلى يوم التجديد وما بعده. وفي المخرج لاحظ التالي:

- في 15 أبريل صدرت فاتورة التجديد بخطة Basic، أي أن التخفيض سرى في موعده، وفشل دفعها، والحساب ما زال سليماً.
- المحاولات في 17 و21 و28 أبريل، أي بعد 2 ثم 4 ثم 7 أيام من المحاولة السابقة، كما في الإعداد بالضبط. والمحاولة الأخيرة حالتها `ABORTED` لأن جدول المحاولات انتهى.
- في 22 أبريل، بعد 7 أيام من الفاتورة، دخل الحساب مرحلة `WARNING` والخدمة مستمرة.
- في 29 أبريل، بعد 14 يوماً، دخل مرحلة `SUSPENDED` بقيمة `blockChanges=true`، وأصبحت حالة الاشتراك `BLOCKED`، أي توقف الاستحقاق.

### الخطوة 8: العميل يدفع فيعود الاشتراك Active

```bash
echo "== 8. customer updates the card and pays"
kb -o /dev/null -w "payment-test ok %{http_code}\n" $J -X POST http://killbill:8080/plugins/killbill-payment-test/configure \
  -d '{"CONFIGURE_ACTION":"ACTION_CLEAR"}'
kb -o /dev/null -w "pay %{http_code}\n" -X POST "$KB/accounts/$ACC/invoicePayments"
settled
for i in $(seq 1 30); do kb "$KB/accounts/$ACC/overdue" | jq -e .isClearState >/dev/null && break; sleep 1; done
overdue; kb "$KB/subscriptions/$SUB" | jq -r '"subscription state=" + .state'
```

```text
== 8. customer updates the card and pays
payment-test ok 200
pay 201
account balance=0.00
overdue=__KILLBILL__CLEAR__OVERDUE_STATE__ blockChanges=false
subscription state=ACTIVE
```

عادت إضافة الدفع للنجاح، كأن العميل حدث بطاقته، ثم طلبنا دفع كل الفواتير المستحقة. فأصبح الرصيد صفراً، وعادت المرحلة إلى الحالة النظيفة `__KILLBILL__CLEAR__OVERDUE_STATE__`، وعاد الاشتراك `ACTIVE` في نفس اللحظة دون أي تدخل يدوي. وهذا ما تريده في الإنتاج: أن يكون طريق العودة آلياً بالكامل، لأن العميل الذي دفع لا يجب أن ينتظر موظفاً ليعيد تشغيل خدمته.

### الخطوة 9: ضريبة القيمة المضافة VAT على التجديد

```bash
echo "== 9. VAT 15% on the next renewal (draft invoice, tax item, commit)"
kb -o /dev/null -w "tags %{http_code}\n" $J -X POST "$KB/accounts/$ACC/tags" \
  -d '["00000000-0000-0000-0000-000000000008","00000000-0000-0000-0000-000000000009"]'
clock 16
INV=$(kb "$KB/accounts/$ACC/invoices" | jq -r '.[-1].invoiceId')
kb "$KB/invoices/$INV" | jq -r '"#\(.invoiceNumber) status=\(.status) amount=\(.amount)"'
NET=$(kb "$KB/invoices/$INV" | jq -r '[.items[] | select(.itemType!="TAX") | .amount] | add')
VAT=$(echo "$NET" | awk '{printf "%.2f", $1 * 0.15}')
kb -o /dev/null -w "tax %{http_code}\n" $J -X POST "$KB/invoices/taxes/$ACC?autoCommit=false" \
  -d "[{\"invoiceId\":\"$INV\",\"accountId\":\"$ACC\",\"itemType\":\"TAX\",\"amount\":$VAT,\"currency\":\"SAR\",\"description\":\"VAT 15%\"}]"
kb -o /dev/null -w "commit %{http_code}\n" -X PUT "$KB/invoices/$INV/commitInvoice"
sleep 3; kb "$KB/invoices/$INV" | jq -r '"#\(.invoiceNumber) \(.status) amount=\(.amount) balance=\(.balance)", (.items[] | "    \(.itemType) \(.description) \(.amount)")'
```

```text
== 9. VAT 15% on the next renewal (draft invoice, tax item, commit)
tags 201
clock -> 2026-05-15
#5 status=DRAFT amount=99.00
tax 200
commit 204
#5 COMMITTED amount=113.85 balance=0.00
    RECURRING basic-monthly-evergreen 99.00
    TAX VAT 15% 14.85
```

الوسمان `AUTO_INVOICING_DRAFT` و`AUTO_INVOICING_REUSE_DRAFT`، وهما المعرفان المنتهيان بالرقمين 8 و9، يجعلان المحرك يصدر فواتير الحساب مسودات بحالة `DRAFT` لا تدفع تلقائياً. فلما وصلت الساعة إلى 15 مايو صدرت الفاتورة رقم 5 مسودة بمبلغ 99\. ثم حسبنا الضريبة على صافي بنودها، وأضفناها بندا من نوع `TAX` في المسودة نفسها، ثم اعتمدناها، فدفعت تلقائياً بمبلغ 113.85.

وفي الإنتاج لا يكتب هذا الحساب في سكربت، وإنما في خدمة صغيرة تستقبل حدث إنشاء الفاتورة، أو في [إضافة فوترة Invoice Plugin](https://docs.killbill.io/latest/invoice%5Fplugin.html?ref=arabroot.io) تعمل داخل المحرك نفسه. والمهم هو الترتيب الذي رأيته: الضريبة قبل الاعتماد، والاعتماد قبل الدفع.

⚠️

إذا أرسلت بند الضريبة دون الحقل `invoiceId`، فلن يضيفه Kill Bill إلى المسودة الموجودة، وإنما ينشئ فاتورة مسودة ثانية فيها بند الضريبة وحده. فتصبح لدى العميل فاتورتان لشهر واحد. حدد رقم الفاتورة دائماً، وإذا وقعت في هذا الخطأ فألغ الفاتورة الزائدة بالأمر `PUT /1.0/kb/invoices/{id}/voidInvoice` قبل اعتمادها.

### الخطوة 10: الدفعة المكررة Idempotency

```bash
echo "== 10. a one-off payment sent twice with the same transactionExternalKey"
for n in 1 2; do
  kb -o /tmp/out -w "HTTP %{http_code} " $J -X POST "$KB/accounts/$ACC/payments" \
    -d '{"transactionType":"PURCHASE","amount":50,"currency":"SAR","paymentExternalKey":"pt-pack-77","transactionExternalKey":"pt-pack-77-tx"}'
  jq -r '.message // ""' /tmp/out 2>/dev/null || echo
done
```

```text
== 10. a one-off payment sent twice with the same transactionExternalKey
HTTP 201 HTTP 400 Successful transaction with external key pt-pack-77-tx already exists
```

دفعة لمرة واحدة بقيمة 50 ريالاً، كأن العضو اشترى باقة حصص تدريب، أرسلناها مرتين بنفس `transactionExternalKey`. فنجحت الأولى، ورفضت الثانية بالرمز 400 والرسالة «Successful transaction with external key pt-pack-77-tx already exists». ولاحظ كلمة Successful في الرسالة. فهل يعني ذلك أن العملية الفاشلة يمكن إعادتها بنفس المفتاح؟ السكربت التالي يجيب: يجعل البوابة التجريبية ترفض، ثم يرسل دفعة، ثم يعيد البوابة للنجاح ويرسل الدفعة نفسها مرتين:

```bash
BODY='{"transactionType":"PURCHASE","amount":20,"currency":"SAR","paymentExternalKey":"towel-10","transactionExternalKey":"towel-10-tx"}'
mode() { curl -s $H $J -o /dev/null -X POST http://localhost:9580/plugins/killbill-payment-test/configure -d "{\"CONFIGURE_ACTION\":\"$1\"}"; echo "gateway: $1"; }
pay() { curl -s $H $J -o pay.out -w "HTTP %{http_code} " -X POST "$KB/accounts/$ACC/payments" -d "$BODY"; sed 's/.*"message":"\([^"]*\)".*/\1/' pay.out; echo; }
mode ACTION_RETURN_PLUGIN_STATUS_ERROR; pay
mode ACTION_CLEAR; pay
pay
curl -s $H "$KB/payments?externalKey=towel-10" | grep -o '"transactionExternalKey":"[^"]*"\|"status":"[A-Z_]*"' | paste - -
```

```text
gateway: ACTION_RETURN_PLUGIN_STATUS_ERROR
HTTP 402 Payment decline by gateway. Error message: null
gateway: ACTION_CLEAR
HTTP 201 
HTTP 400 Successful transaction with external key towel-10-tx already exists
"transactionExternalKey":"towel-10-tx"	"status":"PAYMENT_FAILURE"
"transactionExternalKey":"towel-10-tx"	"status":"SUCCESS"
```

رفضت البوابة الأولى بالرمز 402، فنجحت الثانية بنفس المفتاح وأضيفت إلى نفس الدفعة كعملية ثانية، ثم رفض المحرك الثالثة لأن في المفتاح عملية ناجحة. وهذا هو السلوك الذي تريده لزر «أعد المحاولة» في صفحة تحديث البطاقة: يسمح بالمحاولة بعد الفشل، ولا يسمح بخصم ثان بعد النجاح.

### الخطوة 11: الإلغاء Cancel في نهاية الفترة

```bash
echo "== 11. cancel at end of term"
kb -o /dev/null -w "cancel %{http_code}\n" -X DELETE "$KB/subscriptions/$SUB?entitlementPolicy=END_OF_TERM&billingPolicy=END_OF_TERM"
kb "$KB/subscriptions/$SUB" | jq -r '"state=\(.state) cancelledDate=\(.cancelledDate) billingEndDate=\(.billingEndDate)"'
clock 31; kb "$KB/subscriptions/$SUB" | jq -r '"state=" + .state'
kb "$KB/accounts/$ACC?accountWithBalance=true" | jq -r '"account balance=\(.accountBalance)"'
```

```text
== 11. cancel at end of term
cancel 204
state=ACTIVE cancelledDate=2026-06-15T08:00:00.000Z billingEndDate=2026-06-15T08:00:00.000Z
clock -> 2026-06-15
state=CANCELLED
account balance=0.00
```

ألغى العضو في 15 مايو بعد دفع فاتورة مايو، فبقي الاشتراك `ACTIVE` وتاريخ الإلغاء الفعلي 15 يونيو، أي نهاية الفترة المدفوعة. وبعد تحريك الساعة شهراً أصبح `CANCELLED` دون فاتورة جديدة، والرصيد صفر.

### ما وصل مستقبل الأحداث Webhook Receiver

هذه أول أسطر سجل المستقبل، بالترتيب الذي وصلت به:

```text
ACCOUNT_CREATION | ACCOUNT | 3ec48dc8-4b99-4693-abb1-9aa45487a5f7
TENANT_CONFIG_CHANGE | TENANT_KVS | 5bddfe71-cbfa-41b6-8f58-844f3f0ad772
ENTITLEMENT_CREATION | SUBSCRIPTION | 3ea18765-8b9f-418d-a705-c3024dc6c898
TENANT_CONFIG_CHANGE | TENANT_KVS | c9941273-6eb0-4672-ad00-f02092bf2281
TENANT_CONFIG_CHANGE | TENANT_KVS | 7cf249d6-8aff-489b-b205-03507ec33d43
TENANT_CONFIG_CHANGE | TENANT_KVS | cdecc719-411e-42b5-a9c5-477370817d45
ACCOUNT_CHANGE | ACCOUNT | 3ec48dc8-4b99-4693-abb1-9aa45487a5f7
ACCOUNT_CHANGE | ACCOUNT | 3ec48dc8-4b99-4693-abb1-9aa45487a5f7
SUBSCRIPTION_CREATION | SUBSCRIPTION | 3ea18765-8b9f-418d-a705-c3024dc6c898
SUBSCRIPTION_CREATION | SUBSCRIPTION | 3ea18765-8b9f-418d-a705-c3024dc6c898
INVOICE_CREATION | INVOICE | 69eed584-fff9-4dbc-965b-eddb16e16592
SUBSCRIPTION_PHASE | SUBSCRIPTION | 3ea18765-8b9f-418d-a705-c3024dc6c898
INVOICE_CREATION | INVOICE | 47d19a3e-e52b-4269-b781-8b5adc5e7525
```

لاحظ أن `ENTITLEMENT_CREATION` وصل قبل `SUBSCRIPTION_CREATION`، وأن `SUBSCRIPTION_CREATION` وصل مرتين، وأن أحداث `TENANT_CONFIG_CHANGE` الخاصة برفع الكتالوج جاءت بعد إنشاء الحساب مع أننا رفعنا الكتالوج قبله. وهذه هي الحقائق الثلاث التي بنينا عليها قسم الأحداث.

وهذا أول حدث فشل دفع كما وصل، بترويساته:

```text
INVOICE_PAYMENT_FAILED | INVOICE | 4ffcfb9a-9c35-4242-aae1-a79416a0cb53
{'Connection': 'Upgrade, HTTP2-Settings', 'Content-Length': '531', 'Host': 'fin4-hooks:8000', 'HTTP2-Settings': 'AAEAAEAAAAIAAAAAAAMAAAAAAAQBAAAAAAUAAEAAAAYABgAA', 'Upgrade': 'h2c', 'Content-Type': 'application/json; charset=UTF-8', 'User-Agent': 'KillBill/1.0'}
{
  "eventType": "INVOICE_PAYMENT_FAILED",
  "accountId": "3ec48dc8-4b99-4693-abb1-9aa45487a5f7",
  "objectType": "INVOICE",
  "objectId": "4ffcfb9a-9c35-4242-aae1-a79416a0cb53",
  "metaData": "{\"paymentId\":\"2c5cd286-ea31-4159-9b16-16a4254c063b\",\"paymentAttemptId\":\"a1e5ea92-07b6-4446-9e6d-fc6b0d599418\",\"invoicePaymentType\":\"ATTEMPT\",\"paymentDate\":\"2026-04-15T11:00:28.000Z\",\"amount\":0,\"currency\":\"SAR\",\"linkedInvoicePaymentId\":null,\"paymentCookieId\":\"5f9e3b34-275d-4549-a3be-a1618b34fd98\",\"processedCurrency\":\"SAR\"}"
}
```

الحدث فيه نوعه ومعرف الفاتورة ومعرف الحساب، وفي `metaData` معرف الدفعة والمحاولة. ولا يوجد فيه مبلغ الفاتورة ولا سبب الفشل، ولا يوجد في الترويسات أي توقيع. فالمستقبل الصحيح يأخذ `objectId` ويقرأ الفاتورة من الواجهة البرمجية، ثم يقرر هل يرسل للعميل رسالة تحديث البطاقة.

### ماذا يحدث إذا كان مستقبل الأحداث Webhook متوقفاً؟

في هذه التجربة نوقف شيئاً عن قصد: نوقف حاوية المستقبل، ثم نولد حدثاً بإضافة وسم على الحساب، ثم نعيد تشغيل المستقبل ونحرك الساعة:

```bash
#!/bin/sh
# What happens when the webhook receiver is down? Stop it, trigger an event, start it again, move the clock.
KB=http://localhost:9580/1.0/kb
H="-u admin:password -H X-Killbill-ApiKey:gym -H X-Killbill-ApiSecret:gym-secret -H X-Killbill-CreatedBy:lab"
ACC=$(curl -s $H "$KB/accounts?externalKey=member-1001" | sed 's/.*"accountId":"\([^"]*\)".*/\1/')
docker stop fin4-hooks
curl -s $H -o /dev/null -w "tag %{http_code}\n" -H Content-Type:application/json -X POST "$KB/accounts/$ACC/tags" \
  -d '["00000000-0000-0000-0000-000000000006"]'
sleep 10
docker logs fin4-killbill 2>&1 | grep -o 'Failed to push notification[^,]*\|eventType=.TAG_CREATION[^}]*attemptNumber=[0-9]*\|re-scheduled to be sent at [^,]*' | tail -3
docker start fin4-hooks
sleep 10
curl -s $H -X POST "$KB/test/clock?requestedDate=2026-06-17T00:00:00.000Z&timeoutSec=20"; echo
sleep 10
docker logs fin4-hooks 2>&1 | tail -1
```

```text
fin4-hooks
tag 201
Failed to push notification url='http://fin4-hooks:8000/'
re-scheduled to be sent at 2026-06-15T18:16:35.000Z
fin4-hooks
{"currentUtcTime":"2026-06-17T00:00:02.000Z","timeZone":"UTC","localDate":"2026-06-17"}
TAG_CREATION | TAG | 76c7ecc7-e057-41fc-9c76-354621ae2a63
```

فشل الإرسال الأول لأن المستقبل متوقف، فسجل Kill Bill الحدث وجدول إعادة إرساله بعد ربع ساعة من زمن المحرك. فلما عاد المستقبل وتقدمت الساعة، وصل الحدث `TAG_CREATION`. وهذا يعني أمرين: لن تضيع الأحداث إذا توقف تطبيقك قليلاً، وسوف تصلك أحداث قديمة متأخرة بعد العودة، فلا تفترض أن الحدث الذي يصلك الآن يصف الحالة الآن. وجدول إعادة الإرسال خاصية لكل مستأجر اسمها `org.killbill.billing.server.notifications.retries`، كما في [توثيق الأحداث في Kill Bill](https://docs.killbill.io/latest/push%5Fnotifications.html?ref=arabroot.io).

### مشكلة ظهرت: ساعة الاختبار Test Clock تصل قبل موعدها بثوان

في نسخة سابقة من السكربت كانت الدالة `clock` تضبط الساعة على تاريخ محدد، مثل الساعة 12:00:00 من 22 أبريل، ثم 12:00:00 من 29 أبريل. فظهرت نتيجة غريبة: بقي الحساب في مرحلة `WARNING` يوم 29 أبريل ولم يدخل مرحلة الإيقاف، مع أن الفاتورة مر عليها 14 يوماً.

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

والدرس أكبر من المختبر. فكل نظام فوترة يجدول أعمالاً بعد مدة من حدث سابق، وأي اختبار يفترض أن «بعد سبعة أيام» تعني لحظة محددة سيمر أحياناً ويفشل أحياناً. لذلك اختبر دائماً بعد الموعد بهامش واضح، لا عند الموعد بالضبط.

### حذف المختبر Cleanup

```bash
docker compose down
docker image rm killbill/killbill:0.24.22 killbill/mariadb:0.24
```

البيانات كلها داخل حاوية قاعدة البيانات دون Volume، فتختفي مع حذف الحاويات. وإذا أردت أن تحتفظ بها لتجارب لاحقة، فأضف Volume لمجلد `/var/lib/mysql` في خدمة `db`.

## جدول القرارات Decision Table قبل أن تطلق الاشتراكات

هذه القرارات التي مررنا بها، في جدول واحد، مع ما اخترناه في المختبر:

| القرار           | الخيارات                                    | اختيار المختبر                          |
| ---------------- | ------------------------------------------- | --------------------------------------- |
| التجربة المجانية | مع بطاقة، أو دون بطاقة                      | 14 يوماً مع وسيلة دفع                   |
| يوم الفوترة      | يوم بداية الاشتراك، أو يوم ثابت لكل العملاء | يوم نهاية التجربة، ولكل الحساب يوم واحد |
| الترقية          | فوراً مع التناسب، أو في نهاية الفترة        | فوراً مع التناسب بالأيام الفعلية        |
| التخفيض          | فوراً مع رصيد دائن، أو في نهاية الفترة      | نهاية الفترة                            |
| إعادة المحاولة   | عدد المحاولات وتباعدها                      | 3 محاولات بعد 2 ثم 4 ثم 7 أيام          |
| مراحل التحصيل    | متى التحذير، ومتى الإيقاف                   | تحذير بعد 7 أيام، وإيقاف بعد 14         |
| السعر والضريبة   | السعر شامل الضريبة أو قبلها                 | قبلها، والضريبة بند في الفاتورة         |
| الإلغاء          | فوراً مع استرداد، أو في نهاية الفترة        | نهاية الفترة                            |
| منع التكرار      | مفاتيح عشوائية، أو مفاتيح من بيانات نظامك   | رقم العضو ورقم الطلب                    |

## أخطاء شائعة

| الخطأ                                   | لماذا يضر                                               | البديل                                                 |
| --------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------ |
| حالة واحدة للاشتراك تخلط الدفع بالخدمة  | لا تستطيع تمثيل «مستحق وغير مدفوع» أثناء إعادة المحاولة | استحقاق منفصل عن الفوترة                               |
| القسمة على 30 يوماً دائماً              | فروقات صغيرة تظهر في المطابقة                           | الأيام الفعلية للفترة                                  |
| إيقاف الخدمة عند أول فشل                | تخسر عملاء لم يعرفوا أن بطاقتهم انتهت                   | محاولات ومهلة ورسائل قبل الإيقاف                       |
| حذف الحساب عند الإيقاف                  | العميل الذي يعود يجد حسابه فارغاً                       | الإيقاف حالة مؤقتة، والحذف قرار منفصل                  |
| إضافة الضريبة بعد الخصم                 | فاتورتان ودفعتان لشهر واحد                              | مسودة، ثم ضريبة، ثم اعتماد، ثم دفع                     |
| مفتاح منع تكرار عشوائي في كل محاولة     | لا يمنع التكرار أصلاً                                   | مفتاح من رقم الطلب أو الفاتورة                         |
| الثقة بمحتوى الحدث وترتيبه              | قرارات على حالة قديمة                                   | اقرأ الحالة من الواجهة البرمجية قبل التصرف             |
| عنوان أحداث مفتوح على الإنترنت دون تحقق | أي شخص يستطيع إرسال «تم الدفع»                          | شبكة خاصة أو توقيع أو رمز سري، وقراءة الحالة من المصدر |
| وضع الاختبار مفعل في الإنتاج            | من يصل إلى واجهة الساعة يقدم الزمن ويجدد كل الاشتراكات  | عطله، واحجب مسار /test في الـ Reverse Proxy            |

## قائمة تحقق Checklist

- الكتالوج مكتوب: الخطط والمراحل والأسعار وقواعد الترقية والتخفيض والإلغاء.
- تعرف كيف يحسب التناسب، بالأيام الفعلية، وكيف يقرب.
- جدول إعادة المحاولة ومراحل التحصيل مكتوبان، ولكل مرحلة رسالة للعميل.
- الإيقاف والعودة آليان بالكامل، والعودة تحدث لحظة الدفع.
- الضريبة تضاف قبل اعتماد الفاتورة، وعلى الصافي بعد أي رصيد.
- كل عملية دفع لها مفتاح خارجي من بياناتك، وكل حساب له مفتاح خارجي برقم العميل.
- مستقبل الأحداث يتحقق من المصدر، ويمنع التكرار، ويرد بسرعة، ويقرأ الحالة من الواجهة البرمجية.
- مسار الإلغاء بنفس سهولة الاشتراك، وتذكير قبل نهاية التجربة.
- اختبرت الأشهر الثلاثة الأولى بتحريك الساعة، لا بالانتظار.
- المطابقة اليومية بين فواتير المحرك وما وصل حسابك البنكي تعمل.

## الخلاصة

- الفوترة المتكررة ليست خصماً كل شهر، وإنما كتالوج واشتراكات وفواتير ودفع وتحصيل وأحداث، لكل منها مسؤوليته.
- افصل الاستحقاق عن الفوترة، لأن الاشتراك قد يكون مستحقاً وغير مدفوع لأيام.
- الترقية فوراً بالتناسب على الأيام الفعلية، والتخفيض والإلغاء في نهاية الفترة، وفي المختبر كانت الترقية 134.81 ناقص 67.06 يساوي 67.75.
- الفشل في الدفع متوقع، فخطط له: محاولات متباعدة، ثم تحذير، ثم إيقاف، ثم عودة آلية لحظة الدفع.
- الضريبة جزء من الفاتورة قبل الدفع، لا تعديل بعده.
- منع التكرار بمفاتيح من بياناتك، والأحداث تصل متأخرة ومكررة وبغير ترتيب، فاقرأ الحالة من المصدر.
- اختر محركاً يسمح لك بتحريك الزمن في الاختبار، لأن أخطاء الفوترة لا تظهر إلا بعد أسابيع.

وفي مقالات قريبة: كيف تقيس أثر الاشتراكات على شركتك في [مقاييس SaaS](https://arabroot.io/articles/%D9%85%D9%82%D8%A7%D9%8A%D9%8A%D8%B3-%D8%B4%D8%B1%D9%83%D8%A7%D8%AA-saas-%D8%A7%D9%84%D8%A7%D9%8A%D8%B1%D8%A7%D8%AF-%D8%A7%D9%84%D9%85%D8%AA%D9%83%D8%B1%D8%B1-mrr-%D9%88%D8%A7%D9%84%D8%AA%D8%B3%D8%B1%D8%A8-churn/) و[اقتصاديات الوحدة Unit Economics](https://arabroot.io/articles/%D8%A7%D9%82%D8%AA%D8%B5%D8%A7%D8%AF%D9%8A%D8%A7%D8%AA-%D8%A7%D9%84%D9%88%D8%AD%D8%AF%D8%A9-unit-economics-cac-%D9%88-ltv/)، وكيف تطابق ما يصلك من مزود الدفع في [مقال المطابقة](https://arabroot.io/articles/%D8%A7%D9%84%D9%85%D8%B7%D8%A7%D8%A8%D9%82%D8%A9-reconciliation-%D9%83%D8%B4%D9%81-%D8%A7%D9%84%D8%A8%D9%86%D9%83-%D9%85%D9%82%D8%A7%D8%A8%D9%84-%D9%86%D8%B8%D8%A7%D9%85%D9%83/).

[![](https://arabroot.io/content/images/2026/11/card-payment-flow-cover-cover.webp)دليلكيف يعمل الدفع بالبطاقة؟ التفويض Authorization والتسويةماذا يحدث بعد ضغطة «ادفع»: التفويض والتحصيل والتسوية والاسترداد والاعتراض، وما يحفظه التاجر ليحمي إيراده.](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D8%AA%D8%B9%D9%85%D9%84-%D8%B9%D9%85%D9%84%D9%8A%D8%A9-%D8%A7%D9%84%D8%AF%D9%81%D8%B9-%D8%A8%D8%A7%D9%84%D8%A8%D8%B7%D8%A7%D9%82%D8%A9-%D8%A7%D9%84%D8%AA%D9%81%D9%88%D9%8A%D8%B6-%D9%88%D8%A7%D9%84%D8%AA%D8%B3%D9%88%D9%8A%D8%A9-%D9%88%D8%A7%D9%84%D8%A7%D8%B9%D8%AA%D8%B1%D8%A7%D8%B6/)[![](https://arabroot.io/content/images/2026/11/payment-gateways-cover-cover.webp)دليلبوابات الدفع Payment Gateways في السعودية: كيف تختار مزودككيف تختار مزود الدفع في المملكة: الترخيص، وما ينشره المزودون المحليون، ومدد التسوية، وأين يقف Stripe والحلول المفتوحة.](https://arabroot.io/articles/%D8%A8%D9%88%D8%A7%D8%A8%D8%A7%D8%AA-%D8%A7%D9%84%D8%AF%D9%81%D8%B9-payment-gateways-%D9%81%D9%8A-%D8%A7%D9%84%D8%B3%D8%B9%D9%88%D8%AF%D9%8A%D8%A9-%D9%88%D8%A7%D9%84%D8%A8%D8%AF%D8%A7%D8%A6%D9%84-%D9%85%D9%81%D8%AA%D9%88%D8%AD%D8%A9-%D8%A7%D9%84%D9%85%D8%B5%D8%AF%D8%B1/)[![](https://arabroot.io/content/images/2026/10/pci-tokenization-cover-cover.webp)دليلأمن بيانات البطاقات PCI DSS والترميز Tokenizationنطاق PCI DSS v4.0.1 وما يمنع حفظه من بيانات البطاقة، وكيف يعمل الترميز، مع مختبر لفحص السجلات وخطر التجزئة دون مفتاح.](https://arabroot.io/articles/%D8%A7%D9%85%D9%86-%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA-%D8%A7%D9%84%D8%A8%D8%B7%D8%A7%D9%82%D8%A7%D8%AA-pci-dss-%D9%88%D8%A7%D9%84%D8%AA%D8%B1%D9%85%D9%8A%D8%B2-tokenization/)[![](https://arabroot.io/content/images/2026/10/reconciliation-cover-cover.webp)دليلالمطابقة Reconciliation: كشف البنك مقابل نظامككيف تقابل كل حركة في كشف البنك بقيد في دفترك على مراحل، ولماذا قد يتساوى الرصيدان وتحتهما دفع مكرر لا يكشفه إلا المرجع.](https://arabroot.io/articles/%D8%A7%D9%84%D9%85%D8%B7%D8%A7%D8%A8%D9%82%D8%A9-reconciliation-%D9%83%D8%B4%D9%81-%D8%A7%D9%84%D8%A8%D9%86%D9%83-%D9%85%D9%82%D8%A7%D8%A8%D9%84-%D9%86%D8%B8%D8%A7%D9%85%D9%83/)[![](https://arabroot.io/content/images/2026/11/saas-metrics-cover-cover.webp)دليلمقاييس شركات SaaS: الإيراد المتكرر MRR والتسرب Churnكيف تحسب المقاييس التي يسأل عنها المستثمر في شركة الاشتراكات، وتقرؤها معاً بأمثلة بالريال وأرقام مرجعية منشورة.](https://arabroot.io/articles/%D9%85%D9%82%D8%A7%D9%8A%D9%8A%D8%B3-%D8%B4%D8%B1%D9%83%D8%A7%D8%AA-saas-%D8%A7%D9%84%D8%A7%D9%8A%D8%B1%D8%A7%D8%AF-%D8%A7%D9%84%D9%85%D8%AA%D9%83%D8%B1%D8%B1-mrr-%D9%88%D8%A7%D9%84%D8%AA%D8%B3%D8%B1%D8%A8-churn/)[![](https://arabroot.io/content/images/2026/11/startup-taxes-cover-cover.webp)دليلالزكاة وضريبة القيمة المضافة VAT للشركة الناشئةما يلزم شركتك الناشئة في السعودية من الزكاة والقيمة المضافة والاستقطاع والفوترة الإلكترونية، ومتى يبدأ كل منها بالأرقام الرسمية.](https://arabroot.io/articles/%D8%A7%D9%84%D8%B2%D9%83%D8%A7%D8%A9-%D9%88%D8%B6%D8%B1%D9%8A%D8%A8%D8%A9-%D8%A7%D9%84%D9%82%D9%8A%D9%85%D8%A9-%D8%A7%D9%84%D9%85%D8%B6%D8%A7%D9%81%D8%A9-vat-%D9%84%D9%84%D8%B4%D8%B1%D9%83%D8%A9-%D8%A7%D9%84%D9%86%D8%A7%D8%B4%D8%A6%D8%A9/)[![](https://arabroot.io/content/images/2026/10/zatca-einvoicing-cover-cover.webp)دليلالفوترة الإلكترونية فاتورة ZATCA: كيف تربط نظامكبنينا فاتورة مبسطة بصيغة XML ورمز QR بلغة Python، وتحققنا منهما بأداة الهيئة، وحسبنا الهاش بأنفسنا وجربنا الأخطاء الشائعة.](https://arabroot.io/articles/%D8%A7%D9%84%D9%81%D9%88%D8%AA%D8%B1%D8%A9-%D8%A7%D9%84%D8%A7%D9%84%D9%83%D8%AA%D8%B1%D9%88%D9%86%D9%8A%D8%A9-%D9%81%D8%A7%D8%AA%D9%88%D8%B1%D8%A9-zatca-%D9%83%D9%8A%D9%81-%D8%AA%D8%B1%D8%A8%D8%B7-%D9%86%D8%B8%D8%A7%D9%85%D9%83/)

## سجل التحديثات

- 2026-11-16: كتابة المقال، وتشغيل المختبر على Kill Bill 0.24.22 مع MariaDB 11.8 وإضافة payment-test 8.0.1 في Docker، والتحقق من توثيق Kill Bill وبيان هيئة التجارة الفيدرالية.