بناء نظام فوترة SaaS في Go: ما لا تتعامل معه واجهة برمجة الدفع

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

هذا المنشور يغطي بنية الفوترة التي بنتها Voxire لـ RTYLR، منصة SaaS التي تخدم شركات المطاعم والتجزئة في لبنان ودول الخليج.

ما تتعامل معه فعلاً واجهة برمجة الدفع

Stripe وPaddle والمعالجات المماثلة ممتازة في تحصيل البطاقات وتحريك الأموال. تتعامل مع الامتثال والكشف عن الاحتيال والعلاقات المصرفية التي لا تريد بالتأكيد بناءها بنفسك.

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

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

آلة حالة الاشتراك

كل اشتراك يمر عبر مجموعة من الحالات. تعريفها بوضوح يمنع فئة الأخطاء حيث تُعالج حالات مثل "مدفوع جزئياً" أو "فترة سماح" بشكل غير متسق عبر أجزاء مختلفة من الكود.

const (
    StatusTrialing   SubscriptionStatus = "trialing"
    StatusActive     SubscriptionStatus = "active"
    StatusPastDue    SubscriptionStatus = "past_due"
    StatusSuspended  SubscriptionStatus = "suspended"
    StatusCanceled   SubscriptionStatus = "canceled"
)

الانتقالات بين الحالات قرارات أعمال. في RTYLR:

• trialing ينتقل إلى active عند تسجيل أول دفعة ناجحة
• active ينتقل إلى past_due عندما تفشل دفعة وتوجد نافذة لإعادة المحاولة
• past_due ينتقل إلى suspended بعد ثلاث محاولات دفع فاشلة على مدى سبعة أيام
• suspended ينتقل إلى active عندما يقدم المستأجر طريقة دفع صالحة وتنجح الرسوم المعلقة

حساب الفرق المتناسب

حساب الفرق المتناسب ما يحدث عندما يغير مستأجر خطته في منتصف الدورة. مطعم على خطة Standard بـ 50 دولاراً شهرياً يترقى إلى خطة Pro بـ 120 دولاراً في اليوم العشرين من دورة 30 يوماً.

اعتماد مقابل Standard غير المستخدم: 50 دولاراً × (10/30) = 16.67 دولاراً رسوم Pro للفترة المتبقية: 120 دولاراً × (10/30) = 40.00 دولاراً صافي الرسوم عند الترقية: 40.00 - 16.67 = 23.33 دولاراً

func CalculateProration(currentPlan, newPlan *Plan, daysRemaining, daysInCycle int) decimal.Decimal {
    ratio := decimal.NewFromInt(int64(daysRemaining)).Div(decimal.NewFromInt(int64(daysInCycle)))
    creditUnused := currentPlan.Price.Mul(ratio)
    chargeNew := newPlan.Price.Mul(ratio)
    return chargeNew.Sub(creditUnused)
}

استخدم مكتبة decimal وليس float64 لجميع حسابات العملة. حساب النقطة العائمة على المال يسبب أخطاء تقريب تتراكم في تناقضات حقيقية في إجماليات الفواتير.

استرداد المدفوعات الفاشلة

معظم منتجات SaaS تخسر 5-10% من إيراداتها الشهرية من مدفوعات فاشلة لم تُعاد محاولتها بشكل صحيح. تسلسل أساسي لـ RTYLR:

1. فشل الدفع: إعادة المحاولة فوراً مرة واحدة
2. اليوم الأول: إرسال إشعار بالبريد الإلكتروني، تعيين الحالة إلى past_due
3. اليوم الثالث: إعادة محاولة الدفع، إرسال تذكير إذا استمر الفشل
4. اليوم السابع: المحاولة الأخيرة، إرسال إشعار عاجل
5. اليوم الثامن: تعيين الحالة إلى suspended، إلغاء وصول الميزات

جدول استرداد المدفوعات يعيش في جدول قاعدة بيانات، غير مُشفَّر. مستويات خطط مختلفة يمكن أن يكون لها نوافذ مختلفة. الحسابات المؤسسية تحصل على فترات سماح أطول.

إنشاء الفواتير

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

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

دروس من فوترة RTYLR

ثلاثة أشياء كانت أكثر تعقيداً مما توقعنا:

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

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

وصول الدعم أثناء التعليق. المستأجرون المعلقون لا يزالون بحاجة إلى الوصول إلى قسم الفوترة لتحديث طريقة الدفع. أنشئ وضع دفع فقط يصمد أثناء التعليق.