انتقل إلى المحتوى

بالتفصيل

الفوترة لكل مستخدم عبر Stripe، وwebhooks تصمد أمام إعادة الإرسال

نُشر في · قراءة في 5 دقائق·

متوفرة أيضًا باللغات: Deutsch وEnglish وEspañol وFrançais و日本語 وPortuguês (Brasil) وРусский و简体中文

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

باختصار

  • في Seed، كمية الاشتراك في Stripe هي عدد أعضاء المجموعة، والمالك منهم. Stripe يحسب التناسب، والتطبيق لا يحسب أي مبلغ.
  • ينضم العضو أولًا ثم تتبعه الفاتورة: مهمة في الـworker تبلغ Stripe بالعدد الجديد، وتعيد المحاولة بمفتاح idempotency نفسه ما دام Stripe متوقفًا.
  • يُحفظ معرّف كل حدث في المعاملة نفسها التي تطبّقه: التكرار لا يغيّر شيئًا، والفشل يتراجع عن الاثنين معًا ليعيد Stripe المحاولة.
  • الحدث الأقدم لا يعيد الخطة إلى الوراء أبدًا، ومهمة ليلية تصحّح أي عدد مقاعد انحرف.

كيف تفوتر منتج SaaS لكل مستخدم (per-seat) عبر Stripe دون أن تبتعد الفاتورة عن الفريق الحقيقي؟ في Seed، كمية الاشتراك هي ببساطة عدد أعضاء المجموعة، والتطبيق لا يعتمد على طلب واحد أو webhook واحد ليبقيها كذلك. يُحفظ تغيير الأعضاء أولًا، ثم تبلغ مهمةٌ تُعاد عند الفشل Stripe بالعدد الجديد، ويُسجَّل كل webhook بمعرّف حدثه في المعاملة نفسها التي تطبّقه، وتصلح مهمة ليلية ما أفلت.

هذا المقال للمطوّرين الذين يضيفون فوترة الفرق إلى منتج SaaS، ولكل من رأى معالج webhooks يعمل جيدًا حتى أعاد Stripe إرسال حدث. كل ما يلي موجود في كود Seed برخصة MIT، وأقتبس الأسطر الحقيقية.

ماذا تعني الفوترة لكل مستخدم في Seed؟

الفوترة تخصّ المجموعة، وهي الفريق في Seed. لكل مجموعة اشتراك واحد يدفعه مالكها. في الكتالوج خطتان (PLANS):

الخطة السعر الأعضاء التجربة
Free 0 حتى 3 لا
Pro 9.00 € لكل عضو شهريًا حتى 50 14 يومًا

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

هذا ما يدفعه الفريق بأسعار النسخة التجريبية. حرّك المؤشر:

كم تكلّف خطة Pro في العرض التجريبي فريقك

تُحتسب خطة Pro لكل عضو. حدّد حجم فريقك.

فريقك، شهريًا
‏45.00 €
لكل عضو، شهريًا
‏9.00 €
أسعار خطط العرض التجريبي، قبل الضريبة.

خمسة أشخاص على Pro يدفعون 45 € شهريًا. يرى المالك سعر المقعد الإضافي قبل أن يدعو أحدًا: نموذج الدعوة يعرض ما يضيفه العضو الجديد ويطلب الموافقة عليه. والـAPI يرفض الدعوة بلا هذه الموافقة (SEAT_PRICE_NOT_ACCEPTED)، فالقاعدة تصمد حتى لو أُرسل النموذج بلا JavaScript.

لماذا ينضم العضو قبل أن يعلم Stripe؟

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

يحفظ Seed تغيير الأعضاء أولًا في معاملة خاصة به. تأكيدها يكتب صفًا في الـoutbox، ويحوّل الـworker كل تغيير (انضم، أُزيل، غادر) إلى مهمة مزامنة للمقاعد. تقرأ المهمة العدد حين تعمل، ولا تخاطب Stripe إلا إذا اختلف عن المحفوظ (seat-sync.ts):

const members = await new PostgresInvitationRepository(sql).countMembers(groupId)
if (members < 1 || row.quantity === members) return
const result = await provider.updateQuantity({
  subscriptionId: row.providerSubscriptionId,
  quantity: members,
  // A retry of this row asks for the same count with the same key; a later count gets its own.
  idempotencyKey: `seats:${event.id}:${members}`,
})
if (!result.ok) {
  throw new Error(`seat sync of group ${groupId} failed: ${result.error.code} ...`)
}

ثلاث تفاصيل تحمل كل شيء:

  1. يُقرأ العدد حين تعمل المهمة، لا حين وُضعت في الطابور. خمسة ينضمون في دقيقة يحتاجون طلبًا صحيحًا واحدًا، لا خمسة تتسابق.
  2. مفتاح الـidempotency يسمّي المهمة والعدد. إن طبّق Stripe التغيير وضاع الرد، ترسل إعادة المحاولة المفتاح نفسه، فيرد Stripe بالنتيجة الأولى بدل التطبيق مرتين.
  3. الفشل يرمي خطأ. يعيد نظام المهام المحاولة بعد 1 ث، ثم 2 ث، ثم 4 ث وهكذا، بفاصل يصل إلى 15 دقيقة، لعشرين محاولة، أي نحو ساعتين ونصف (jobs.md).

تغيير الكمية يطلب من Stripe proration_behavior=create_prorations، وهو القيمة الافتراضية: يُضاف باقي الفترة إلى الفاتورة التالية أو يُخصم منها. التطبيق لا يحسب بنفسه أي يورو متناسب. حساب المال الذي لا أكتبه لا أستطيع أن أخطئ فيه.

وماذا لو لم تصل المزامنة أبدًا؟

يلتقطها طريقان آخران، فساعتان ونصف من المحاولات ليست «إلى الأبد»:

  • الـwebhook يتحقق أيضًا. حين يبلغ Stripe عن اشتراك لا تطابق كميته عدد الأعضاء، تضع المعاملة نفسها التي تحفظ الحدث مزامنةً في الطابور. هكذا يصحّح نفسه دفعٌ فُتح قبل أن ينضم أحد.
  • مهمة ليلية تقارن كل مجموعة مدفوعة. في الساعة 03:00 يبحث التنظيف عن كل اشتراك لكل عضو تختلف كميته المحفوظة عن عدد المجموعة، ويضع له مزامنة. هذا يغطي تعطلًا طويلًا في Stripe، وعددًا تغيّر دون حدث في المجموعة، كعضو حذف حسابه.

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

كيف تجعل webhook من Stripe آمنًا عند إعادة الإرسال؟

يعيد Stripe إرسال التسليم الفاشل حتى ثلاثة أيام في الوضع الحقيقي، وينبّه إلى أن الـendpoint قد يستقبل الحدث نفسه أكثر من مرة. المعالج الذي يضيف مقعدًا أو يرسل بريدًا مع كل تسليم سيفعل ذلك مرتين عاجلًا أو آجلًا.

يقوم webhook في Seed بثلاثة أمور بترتيب ثابت. أولًا التوقيع: يتحقق المحوّل @spy4x/billing من ترويسة Stripe-Signature مقابل الجسم الخام، بنافذة خمس دقائق، قبل أن يقرأ بايتًا واحدًا من JSON. التوقيع الخاطئ يأخذ 400. ثم يجري كل شيء في معاملة Postgres واحدة تبدأ بتسجيل معرّف الحدث (postgres-billing-repository.ts):

return await this.sql.begin(async (transaction) => {
  const stored = await transaction`
    INSERT INTO billing_events (id, event_type) VALUES (${event.id}, ${event.type})
    ON CONFLICT (id) DO NOTHING
    RETURNING id
  `
  if (stored.length === 0) return "duplicate"
  // ... apply the subscription, queue mails and seat syncs, record the plan change
})

billing_events.id مفتاح أساسي، فالتسليم الثاني لا يُدرج شيئًا ويعود دون أن يلمس الاشتراك. ولأن المعرّف يُحفظ داخل المعاملة، فالحالة المعاكسة آمنة أيضًا: إن فشل شيء بعده تراجع المعرّف مع الباقي، وأجاب المسار بـ500، وحصلت إعادة Stripe على محاولة ثانية نظيفة. أما حفظ المعرّف أولًا وتطبيقه لاحقًا، على خطوتين، فسيضيّع الحدث في أول مرة يعيد فيها نشرٌ تشغيل الـAPI بينهما.

رسائل المالك (فشل الدفع، اقتراب نهاية التجربة، نهاية الخطة) توضع في الـoutbox في المعاملة نفسها، فالحدث المكرر لا يضع رسالة ثانية أبدًا. والحدث الذي لا يعالجه Seed يأخذ 200، فيتوقف Stripe عن إرساله.

وماذا عن الأحداث التي تصل بغير ترتيبها؟

لا يضمن Stripe ترتيب الأحداث. حدث customer.subscription.updated متأخر يقول «trialing» يجب ألا يلغي active الذي سبقه. يكتب Seed الاشتراك بعملية upsert لا تتحرك إلا إلى الأمام:

ON CONFLICT (group_id) DO UPDATE SET ...
WHERE (subscriptions.provider_event_at, subscriptions.provider_event_rank)
    <= (EXCLUDED.provider_event_at, EXCLUDED.provider_event_rank)

يُقارن وقت الحدث أولًا، ونوعه يفصل عند التعادل: الإنشاء ثم التحديث ثم الحذف. الحدث الأقدم لا يطابق أي صف ولا يغيّر شيئًا. وقاعدة ثانية في WHERE نفسها تمنع اشتراكًا جديدًا لا يدفع (بعد خصم فاشل متأخر مثلًا) من أن يحل محل اشتراك يدفع.

سأكون صريحًا بشأن الحد. توثيق Stripe ينصح بعدم ترتيب الأحداث حسب created لأنه بالثواني الكاملة. يستخدمه Seed حاجزًا ضد الرجوع فقط، ولا يستخدمه أبدًا لكشف التكرار، فذلك عمل معرّف الحدث. حدثان من النوع نفسه في الثانية نفسها يصلان معكوسين ما زالا يتركان الأقدم محفوظًا، حتى يصحّحه الحدث التالي أو تغيير في البوابة. هذه الحالة مكتوبة في توثيق الفوترة، والإصلاح ينتظر spy4x/ts-libs#380. أفضّل أن أخبرك على أن تكتشفها بنفسك.

هل تثبت الاختبارات ذلك؟

تعمل على Postgres حقيقي. من بين الخطوات الـ26 في مجموعة اختبارات الـwebhook (tests/integration/billing.integration.test.ts): «التسليم الثاني للحدث نفسه لا يغيّر شيئًا» و«الحدث الأقدم من المحفوظ لا يعيد الخطة إلى الوراء». وللمقاعد مجموعتها الخاصة (tests/integration/seat-billing.integration.test.ts) بخطوات مثل «العضو المُزال والعضو المغادر يُنقص كلٌّ منهما العدد واحدًا» و«المهمة الليلية تضع تغيير مقاعد لكل مجموعة انحرفت».

ما الذي لا يفعله Seed؟

لتعرف قبل أن تبني عليه:

  • خطة مدفوعة واحدة، شهرية، لكل عضو. لا فوترة حسب الاستخدام أو العدّاد، ولا مستويات. إضافة خطة خمس خطوات في Plans and limits.
  • Stripe فقط. الكود يخاطب واجهة مزوّد، لكن Stripe هو المحوّل الوحيد الموجود. ويمكن أيضًا إيقاف الفوترة، فتحصل كل مجموعة على كل الميزات.
  • invoice.paid وinvoice.payment_failed يُحفظان لكنهما لا يغيّران شيئًا بعد. الخطة تتبع حالة الاشتراك نفسه.
  • المال يبقى في Stripe. التطبيق يحفظ ما تبلغ به الـwebhooks ولا يقرر الخطة بنفسه أبدًا.

جرّبه

افتح النسخة التجريبية، وأنشئ مجموعة وانظر إلى تبويب الفوترة فيها، ثم ادعُ أحدًا وسترى سعر المقعد قبل الإرسال. الخلاصة في صفحة الفوترة، وSet up billing تأخذك من لا فوترة إلى Stripe حقيقي، في وضع الاختبار أولًا، وللمجموعات صفحتها. إن كان معالج الـwebhooks عندك يحفظ معرّف الحدث في خطوة ويطبّقه في أخرى، فذلك أول سطر كنت سأغيّره اليوم.

تلقَّ المقال التالي عبر البريد

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

كل المقالات