Kill Bill: نظام فوترة مفتوح المصدر تستضيفه بنفسك

كل منتج يتقاضى المال ينتهي به الأمر إلى بناء الشيء نفسه: خطط أسعار، وفترات تجريبية، وترقيات، وفواتير، وإعادة محاولة البطاقات المرفوضة، واسترداد الأموال. معظم الفرق تستأجر هذه الطبقة من Stripe Billing أو Chargebee أو Recurly وتدفع نسبة من الإيرادات مقابلها. أما Kill Bill فيسلك الطريق الآخر: إنه منصة فوترة ومدفوعات مفتوحة المصدر تنشرها على بنيتك التحتية الخاصة، وتصدر بترخيص Apache 2.0.

تشرح هذه الملاحظة ما هو Kill Bill، وكيف يعمل من الداخل، وكيف تشغّله محليًا وتنشئ أول اشتراك، ومتى يكون الخيار الصحيح ومتى لا يكون.

#المشكلة التي يحلّها

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

• رسوم تكبر مع الإيرادات. نسبة من كل فاتورة لا تُذكر عند 10 آلاف شهريًا، وتصبح مؤلمة عند 10 ملايين.
• الارتهان للمزوّد. اشتراكاتك وفواتيرك ورموز الدفع تعيش داخل نظام غيرك، وفق نموذج بياناته.
• منطق محدود. إذا احتجت بوابة دفع محلية، أو مزوّدًا آخر لمكافحة الاحتيال، أو قواعد خاصة لإعادة المحاولة، أو تعديل الفواتير لحظة إنشائها، فعليك انتظار خطة المزوّد.

يجيب Kill Bill عن الثلاث بكونه بنية تحتية تملكها. تدفع ثمن الخوادم لا نسبة من الإيرادات، والبيانات في قاعدة بياناتك، ويمكنك تغيير السلوك عبر الإضافات.

والمقابل واضح: أصبحت تدير خادم فوترة. هذا يعني قاعدة بيانات، وتحديثات، ومراقبة، ومطوّرين يفهمون النموذج.

#الصورة الكاملة

Kill Bill ليس صفحة دفع ولا بوابة للعملاء. إنه محرّك الفوترة خلف منتجك. يستدعي تطبيقك واجهته البرمجية REST عند حدوث شيء ما (تسجيل عميل، ترقية، إلغاء)، ويتولّى Kill Bill كل ما يأتي بعد ذلك.

• خادم Kill Bill. تطبيق Java يوفّر الواجهة البرمجية REST وينفّذ منطق الفوترة. تثبيت واحد يمكنه استضافة عدة مستأجرين (tenants)، لكل منهم بياناته وكتالوجه وإعداداته.
• قاعدة البيانات. كل حساب واشتراك وفاتورة ودفعة وسجل تدقيق يُحفظ في قاعدة بياناتك. لا شيء يبقى في الذاكرة فقط.
• Kaui. واجهة الإدارة، حتى تتمكن فرق المالية والدعم من البحث عن العملاء، وتعديل الفواتير، وإصدار المبالغ المستردة دون لمس الـ API.
• الإضافات. نقاط توسعة تُحمَّل أثناء التشغيل (حزم OSGi) تربط بوابات الدفع ومحرّكات الضرائب، أو تغيّر سلوك الفواتير والمدفوعات والكتالوج.
• الأحداث. يُبلغ Kill Bill تطبيقك عند حدوث تغيير، مثل إنشاء فاتورة أو فشل دفعة، لتتمكن من فتح الوصول أو إرسال بريد.
• مكتبات العملاء. توجد مكتبات رسمية لـ Java وRuby وPHP وNode.js وPython وGo.

#المفاهيم الأساسية

الكتالوج يستحق توضيحًا. هو غالبًا ملف XML (يُتحقق منه وفق مخطط منشور)، وفيه تكمن أكبر قوة لـ Kill Bill: الفترات التجريبية، ومراحل الخصم، والإضافات، وقواعد الترقية والتخفيض، والعملات المتعددة، وقوائم الأسعار. للتجربة يمكنك تجاوز XML وإنشاء خطط بسيطة عبر الـ API أو من Kaui.

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

لنأخذ عميلًا يشترك في خطة «Pro» مع تجربة مجانية لمدة 14 يومًا، بسعر 29 دولارًا شهريًا.

1. التسجيل. ينشئ تطبيقك حسابًا، ويربط به وسيلة دفع، وينشئ اشتراكًا في pro-monthly.
2. التجربة. يبدأ Kill Bill مرحلة TRIAL وينشئ فاتورة بقيمة صفر. لا يُخصم شيء.
3. تغيير المرحلة. في اليوم الخامس عشر ينتقل الاشتراك تلقائيًا إلى مرحلة EVERGREEN. لا حاجة إلى مهمة cron من جهتك.
4. الفاتورة. في كل دورة فوترة يبني Kill Bill الفاتورة، مع احتساب التناسب إذا رقّى العميل خطته في منتصف الدورة، والأرصدة، ورسوم الاستهلاك.
5. الدفع. تُطلق الفاتورة عملية دفع على وسيلة الدفع الافتراضية عبر إضافة بوابة الدفع.
6. معالجة الفشل. إذا رُفضت البطاقة تتولّى إعادة المحاولة وقواعد التأخر الأمر، ويمكنها نقل الحساب إلى حالة تحذير أو إيقاف يقرؤها تطبيقك لتقييد الوصول.
7. الأحداث. في كل خطوة يتلقى تطبيقك إشعارات يمكنه التصرّف بناءً عليها.

#تشغيله محليًا باستخدام Docker

أسرع طريقة تستخدم Docker Compose بثلاث حاويات: Kill Bill، وKaui، وقاعدة بيانات MariaDB مشتركة بينهما. احفظ ما يلي باسم docker-compose.yml (هذه إصدارات الصور الواردة في دليل البدء الرسمي؛ تحقّق من Docker Hub لإصدارات أحدث):

version: '3.2'
volumes:
  db:
services:
  killbill:
    image: killbill/killbill:0.24.16
    ports:
      - "8080:8080"
    environment:
      - KILLBILL_DAO_URL=jdbc:mysql://db:3306/killbill
      - KILLBILL_DAO_USER=root
      - KILLBILL_DAO_PASSWORD=killbill
      - KILLBILL_CATALOG_URI=SpyCarAdvanced.xml
  kaui:
    image: killbill/kaui:4.0.4
    ports:
      - "9090:8080"
    environment:
      - KAUI_CONFIG_DAO_URL=jdbc:mysql://db:3306/kaui
      - KAUI_CONFIG_DAO_USER=root
      - KAUI_CONFIG_DAO_PASSWORD=killbill
      - KAUI_KILLBILL_URL=http://killbill:8080
  db:
    image: killbill/mariadb:0.24
    volumes:
      - type: volume
        source: db
        target: /var/lib/mysql
    expose:
      - "3306"
    environment:
      - MYSQL_ROOT_PASSWORD=killbill

ثم شغّل كل شيء:

docker compose up

• يستغرق التشغيل بضع دقائق. إذا توقفت إحدى الحاويات، خصّص لـ Docker ذاكرة لا تقل عن 4 غيغابايت.
• تعمل Kaui على http://127.0.0.1:9090 ببيانات الدخول الافتراضية admin / password.
• مستكشف الـ API متاح على http://127.0.0.1:8080/api.html.
• هذه البيانات للاختبار المحلي فقط. غيّرها قبل أن يخرج أي شيء من جهازك.

#أول اشتراك عبر الـ API

بعد تشغيل الحاويات، تنشئ هذه الاستدعاءات مستأجرًا، وخطة بسيطة، وعميلًا، واشتراكًا. كل طلب بعد إنشاء المستأجر يستخدم مفتاح الـ API والسرّ الخاصين به في الترويسات.

KB=http://127.0.0.1:8080
AUTH=(-u admin:password -H "X-Killbill-ApiKey: bob" -H "X-Killbill-ApiSecret: lazar")
JSON=(-H "Content-Type: application/json" -H "X-Killbill-CreatedBy: demo")

# 1. إنشاء مستأجر (مساحة معزولة بمفتاح وسرّ خاصين)
curl -X POST -u admin:password "${JSON[@]}" \
  -d '{"apiKey": "bob", "apiSecret": "lazar"}' \
  "$KB/1.0/kb/tenants"

# 2. إنشاء خطة بسيطة: Pro بسعر 29 دولارًا شهريًا مع تجربة 14 يومًا
curl -X POST "${AUTH[@]}" "${JSON[@]}" \
  -d '{"planId": "pro-monthly", "productName": "Pro", "productCategory": "BASE",
       "currency": "USD", "amount": 29, "billingPeriod": "MONTHLY",
       "trialLength": 14, "trialTimeUnit": "DAYS"}' \
  "$KB/1.0/kb/catalog/simplePlan"

# 3. إنشاء حساب عميل (المعرّف الجديد في ترويسة Location)
curl -i -X POST "${AUTH[@]}" "${JSON[@]}" \
  -d '{"name": "Jane Doe", "email": "jane@example.com", "currency": "USD"}' \
  "$KB/1.0/kb/accounts"

ACCOUNT_ID=paste-the-id-here

# 4. إضافة وسيلة دفع افتراضية (دفع خارجي للاختبار)
curl -X POST "${AUTH[@]}" "${JSON[@]}" \
  -d '{"pluginName": "__EXTERNAL_PAYMENT__"}' \
  "$KB/1.0/kb/accounts/$ACCOUNT_ID/paymentMethods?isDefault=true"

# 5. اشتراك الحساب في الخطة
curl -X POST "${AUTH[@]}" "${JSON[@]}" \
  -d "{\"accountId\": \"$ACCOUNT_ID\", \"planName\": \"pro-monthly\"}" \
  "$KB/1.0/kb/subscriptions"

# 6. عرض الفاتورة التي أنشأها Kill Bill
curl "${AUTH[@]}" "$KB/1.0/kb/accounts/$ACCOUNT_ID/invoices"

يجب أن تظهر فاتورة تجريبية بقيمة صفر. افتح الحساب نفسه في Kaui لترى الاشتراك والفواتير والتسلسل الزمني. في بيئة الإنتاج ينفّذ خادمك هذه الاستدعاءات عبر إحدى مكتبات العملاء بدل curl، وتحلّ إضافة بوابة دفع حقيقية محلّ الدفع الخارجي.

#الإضافات: حيث تكمن المرونة

القوة الحقيقية لـ Kill Bill هي بناء منطقك الخاص فوق النواة. تتنوع الإضافات إلى عدة أنواع:

تغطي إضافات مفتوحة المصدر الاحتياجات الشائعة، مثل مزوّدي الضرائب (AvaTax) وإشعارات البريد والتحليلات، وتصلح أيضًا أمثلة عند كتابة إضافاتك. تُثبَّت الإضافات عبر KPM، مدير حزم Kill Bill، أو من Kaui.

#مفتوح المصدر أم Aviate؟

كلاهما مبني على النواة مفتوحة المصدر نفسها.

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

#متى يكون Kill Bill الخيار الصحيح

مناسب إذا:

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

غير مناسب إذا:

• لم تُطلق منتجك بعد وتحتاج فوترة تعمل هذا الأسبوع. Stripe Billing أو Paddle أو Lemon Squeezy ستكون أسرع.
• كان نموذجك اشتراكات بسيطة على بوابة دفع واحدة.
• لم يكن في الفريق من يستطيع تولّي خدمة Java وقاعدة بيانات وتحديثاتهما.
• أردت صفحة دفع وبوابة عملاء جاهزتين. مع Kill Bill عليك بناؤهما.

#رأيي

Kill Bill هو ما تبدو عليه الفوترة حين تعاملها كبنية تحتية لا كميزة. النموذج صريح (كتالوج، مراحل، حزم، فواتير، حالات تأخر)، وكل تغيير في الحالة مُسجَّل للتدقيق، ونظام الإضافات يتيح تغيير السلوك دون نسخ المشروع وتعديله. الثمن تشغيلي: ترث خادمًا حقيقيًا بنموذج بيانات حقيقي، والكتالوج يحتاج وقتًا للتعلّم.

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

#الأسئلة الشائعة

#روابط

• الموقع: killbill.io
• التوثيق: docs.killbill.io
• دليل البدء: docs.killbill.io/latest/getting_started
• مرجع الـ API: apidocs.killbill.io
• الشيفرة المصدرية: github.com/killbill/killbill
• المجتمع: مجموعة مستخدمي Kill Bill على Google