SaaS capstone 3: obuna to'lovi va billing — tarif, sinov, hisob-faktura, Payme/Click va dunning
Qisqacha: Billing — tarif (narx va limitlar), obuna holat mashinasi (sinov → faol → qarzdor → bekor) va to'lovni bog'laydigan modul. O'zbekistonda Payme va Click bilan kartadan har oy avtomatik yechish kursda sinalmagan, shuning uchun
jamoahisob-faktura modelida ishlaydi: davr tugaydi → faktura → egasi to'laydi → webhook obunani faollashtiradi. To'lanmasa — 1, 3, 7 kunlik eslatmalar (dunning), keyin bekor va yozish 402. To'lov holati faqat tekshirilgan webhook'dan o'zgaradi, o'sha tranzaksiya ichida.
Bu darsda
- Tarif modelini (narx, limitlar, sinov) va to'lov modelini (hisob-faktura yoki avtomatik yechish) tanlaysiz.
- Obuna holat mashinasini billing moduliga ulaysiz: huquq (402), limit (409), faktura, dunning.
- Payme va Click webhook'ini obunaga bog'laysiz:
tolandihook'i to'lov tranzaksiyasi ichida. - Hisob-fakturani idempotent qilasiz: bitta jamoada bitta ochiq faktura.
- Kanon kodidagi to'rtta billing nuqsonini o'lchov bilan topasiz va tuzatish rejasini yozasiz.
Oldin bilishingiz kerak: SaaS capstone 2, Obuna va davriy to'lovlar, Payme Merchant API, Click integratsiyasi, Dizayn: to'lov tizimi, To'lov xavfsizligi.
1. Nega bu kerak?
jamoa — pullik xizmat. SaaS capstone 2 da vazifalar va fayllar ishladi, lekin hali hech kim to'lamaydi. Billing — mahsulotning eng sezgir joyi: bu yerdagi xato foydalanuvchi uchun "ilova sekin" emas, "pulim ketdi" bo'ladi.
Hayotiy o'xshatish: sport zal abonementi. Birinchi hafta bepul sinov. Keyin oyma-oy to'laysiz. To'lov kechiksa, ma'muriyat qo'ng'iroq qiladi: bir kundan keyin, uch kundan keyin, bir haftadan keyin. Keyin abonement yopiladi. Hamma qoidalar shu yerda: sinov muddati, davr, eslatma va bekor qilish.
Obuna holat mashinasini Obuna va davriy to'lovlar darsida yozgansiz, Payme va Click routerlarini esa 29-qismda. To'lov tizimi dizayni — Dizayn: to'lov tizimi darsida. Bu darsda ularni jamoa ga ulaymiz va ulash joylarida nima buzilishi mumkinligini ko'ramiz.
2. Talab
| Hikoya | Asosiy mezon | Natija |
|---|---|---|
| Jamoa ochaman | 14 kunlik sinov, to'lovsiz | holat sinov |
| Tarif chegarasini bilaman | 500 dan ortiq vazifa | 409 limit-vazifa |
| Fakturani to'layman | Payme yoki Click; to'lovdan keyin | holat faol, +1 oy |
| xuddi o'sha to'lov ikki marta keldi | bitta ledger yozuvi | |
| To'lashni unutdim | eslatma 1, 3, 7 kun, keyin bekor | yozish 402 |
| Egasi sifatida faktura so'rayman | qayta so'rasam | o'sha faktura |
Maqsad emas: kartani saqlab har oy avtomatik yechish, chegirma va promokod, ko'p valyuta, QQS hisobi. Bular ADR-0009 ning "Ochiq" bo'limida.
3. Qarorlar
3.1 Tarif: narx — namuna
ADR-0009 ikki tarif yozgan. Narxlar — namuna, real tarif emas:
| Tarif | Narx (namuna) | A'zo | Vazifa |
|---|---|---|---|
boshlangich |
49 000 so'm/oy | 5 | 500 |
jamoa |
149 000 so'm/oy | 15 | 5 000 |
Kodda narx tiyinda saqlanadi (4_900_000 = 49 000 so'm), butun son sifatida (Pul bilan ishlash JS'da). Haqiqiy narxni kanon qo'ymagan va qo'ymaydi. Bu biznes qarori: raqobatchilar, xarajat, mijozning to'lash qobiliyati. O'z narxingizni topish usulini Frilans: mijoz topish, narx va shartnoma darsida ko'rasiz.
Ikkinchi qaror — bepul tarif yo'q, faqat 14 kunlik sinov. Sabab ADR'da yozilgan: bepul jamoalar bazani to'ldiradi, bitta dasturchi uchun ularni moderatsiya qilish qimmat. Narxi — "bepul sinab ko'raman" degan kichik mijozlar sinov tugagach ketishi mumkin.
3.2 To'lov modeli: faktura yoki avtomatik yechish
| Variant | Afzallik | Kamchilik (jamoa uchun) |
|---|---|---|
| kartani saqlab har oy yechish | mijoz unutmaydi, tushum barqaror | Payme Subscribe API va karta tokeni — kursda sinalmagan |
| hisob-faktura: har davr mijoz o'zi to'laydi | 29-qismdagi Merchant API yetadi, karta serverga tushmaydi | mijoz unutadi — dunning kerak |
| Stripe (xalqaro) | eng qulay obuna API | O'zbekistondagi biznes uchun mavjud emas (29-qism) |
Kanon ikkinchisini tanladi. Bu holat mashinasiga ta'sir qiladi: 29-qismdagi undir amali ("kartadan yech") bu yerda yangi faktura ochish va xat degani. qayta-urinish esa — eslatma xati, faktura ochiq qoladi.
Holat mashinasi o'zgarmadi, faqat amallarning ma'nosi o'zgardi. Bu Hexagonal arxitektura foydasi: sof funksiya "nima qilish kerak"ni aytadi, Billing esa "qanday" ni hal qiladi. Ertaga avtomatik yechish qo'shilsa, undir amali kartadan yechadigan adapterga boradi, obuna.ts esa o'sha-o'sha qoladi.
Tekshirib ko'ring: Nega hisob-faktura modelida dunning majburiy, avtomatik yechishda esa "faqat qayta urinish" yetishi mumkin?
Javob
Avtomatik yechishda tizim o'zi kartadan pul oladi. Muvaffaqiyatsizlik — odatda kartada pul yo'q yoki karta muddati o'tgan: bir necha kundan keyin qayta urinish ko'pincha o'tadi. Hisob-fakturada esa to'lov mijozning harakatiga bog'liq — u fakturani ko'rishi, eslashi va to'lashi kerak. Eslatmasiz faktura unutiladi. Shuning uchun dunning bu yerda eslatma xatlari ketma-ketligi, faktura esa shu orada ochiq qoladi.
3.3 Qarzdor davrida xizmat ishlaydimi
huquqBormi() qarori: qarzdor holatida xizmat davom etadi (inglizcha "grace period"). Bekor bo'lgandan keyin o'qish ishlaydi, yozish — 402.
| Variant | Afzallik | Kamchilik |
|---|---|---|
| to'lanmasa darhol bloklash | qarz to'planmaydi | bitta kechikkan to'lov — butun jamoa ishi to'xtaydi |
| dunning davrida ishlash (kanon) | mijoz ishini yo'qotmaydi, to'lashga vaqt bor | 11 kungacha bepul xizmat |
402 Payment Required — "to'lov kerak". RFC 9110 uni rasman "kelajakda ishlatish uchun ajratilgan" (reserved for future use) deb yozadi: standart ma'no yo'q, brauzer ham uni alohida ishlamaydi. Shunga qaramay ko'p SaaS API'lar uni aynan shu holat uchun ishlatadi: so'rov to'g'ri, ruxsat ham bor, faqat obuna faol emas. Shuning uchun javob tanasida aniq kod (obuna-faol-emas) bo'lishi shart — mijoz faqat raqamga tayanmasin.
3.4 Ledger: "kerak emas" degan edik
Dizayn: to'lov tizimi darsida jamoa uchun "ledger (har pul harakati debet va kredit sifatida yoziladigan, o'zgartirilmaydigan daftar) kerak emas" degan xulosaga kelgan edik: mablag' saqlamaymiz, hamyon yo'q. Kanon esa 29-qismdagi tolov/ paketini o'zgarishsiz ko'chirdi va ledger u bilan birga keldi.
Bu murosali tanlov. Narxi — hisob_yozuvlari, triggerlar va qaytarishlar jadvali, ishlatilmaydigan uzum/stripe qiymatlari. Foydasi — sinalgan kodni qayta yozmaslik va bepul tekshiruv: testda "takroriy Perform ikkinchi yozuv qo'shmadi" ni ledger balansi bilan isbotlash oson. Kichik loyihada "sinalgan kodni o'zgartirmay ko'chirish" ko'pincha "faqat kerakli qismini qayta yozish"dan arzon.
4. Qurish
4.1 Tariflar va huquq
Tariflar — kodda, konstanta sifatida (billing/billing.ts, qatorga bo'lindi, kanon bilan aynan):
export const TARIFLAR: Readonly<Record<string, Tarif>> = {
boshlangich: { kod: "boshlangich", nom: "Boshlang'ich (namuna)",
narx: 4_900_000, davr: "oy", maksAzo: 5, maksVazifa: 500 },
jamoa: { kod: "jamoa", nom: "Jamoa (namuna)",
narx: 14_900_000, davr: "oy", maksAzo: 15, maksVazifa: 5_000 },
};
export const SINOV_KUN = 14;GET /v1/tariflar ham shu ro'yxatni beradi, har qatorga izoh: "NAMUNA narx — real tarif emas" qo'shib. Tariflar bazada emas, kodda — o'zgarishi deploy bilan. Kichik loyihada bu yetarli. Admin panelidan narx o'zgartirish kerak bo'lsa, jadvalga ko'chadi.
Har yozishdan oldin huquq() chaqiriladi. U oldingi darsda obuna qatori qulfi ichida ishlagan edi:
async huquq(c: PoolClient, jamoa: number, tur: "vazifa" | "azo")
: Promise<void> {
const o = await this.ol(jamoa, c);
if (!huquqBormi(o, this.soat()))
throw new IlovaXatosi(402,
"Obuna faol emas — to'lovdan keyin davom etadi",
{ kod: "obuna-faol-emas" });
const t = tarif(o.reja.kod);
const sql = tur === "vazifa"
? "SELECT count(*)::int AS n FROM vazifalar"
+ " WHERE jamoa_id = $1"
: "SELECT count(*)::int AS n FROM azoliklar"
+ " WHERE jamoa_id = $1";
const { rows: [n] } = await c.query<{ n: number }>(sql, [jamoa]);
const maks = tur === "vazifa" ? t.maksVazifa : t.maksAzo;
if ((n?.n ?? 0) >= maks)
throw new IlovaXatosi(409,
`Tarif chegarasi: ${tur} ${String(maks)}`,
{ kod: `limit-${tur}` });
}Ikki xil rad, ikki xil kod. 402 — "to'lang", 409 — "tarifni oshiring yoki keraksizini o'chiring". Frontend ularni ajratib, har biriga o'z tugmasini ko'rsatadi.
4.2 Holat mashinasi
obuna.ts — 29-qismdagi sof funksiyalar, o'zgarishsiz ko'chirilgan:
stateDiagram-v2
[*] --> sinov: jamoa ochildi
sinov --> faol: to'lov o'tdi
sinov --> qarzdor: faktura to'lanmadi
faol --> qarzdor: faktura to'lanmadi
qarzdor --> faol: to'lov o'tdi
qarzdor --> qarzdor: eslatma 1, 3, 7 kun
qarzdor --> bekor: 4-urinish
faol --> tugagan: davr oxirida bekorqarzdor → qarzdor strelkasiga qarang. Har to'lanmagan urinish holatni o'zgartirmaydi, faqat hisoblagichni oshiradi va keyingi eslatma vaqtini qo'yadi. To'rtinchi urinishda — bekor.
Huquq funksiyasi uch qatordan iborat (qatorga bo'lindi, kanon bilan aynan):
export function huquqBormi(o: Obuna, hozir: Date): boolean {
if (o.holat === "sinov" || o.holat === "faol")
return hozir < o.davrOxiri;
// dunning davrida xizmat davom etadi (grace) — biznes qarori
if (o.holat === "qarzdor") return true;
return false;
}Birinchi qatorni eslab qoling: sinov va faol faqat davr oxirigacha huquq beradi. Bu kichik tafsilot keyinroq kutilmagan natija beradi («Natijani halol o'qish» bo'limida).
4.3 Faktura: bitta jamoada bitta ochiq
Faktura so'rovi takrorlanishi tabiiy. Egasi tugmani ikki marta bosadi, sikl va egasi bir vaqtda faktura ochadi. Kanon buni jadval bilan hal qiladi: ochiq_fakturalar (jamoa_id PRIMARY KEY, faktura_id UNIQUE). Bir jamoada bir vaqtda ikkinchi ochiq faktura bo'lishi mumkin emas. Kod (qatorga bo'lindi, kanon bilan aynan):
async faktura(c: PoolClient, jamoa: number, summa?: number)
: Promise<{ raqam: string; buyurtmaId: number; summa: number }> {
const { rows: [bor] } = await c.query<
{ raqam: string; buyurtma_id: string; summa: string }>(
"SELECT f.raqam, f.buyurtma_id, f.summa FROM ochiq_fakturalar o"
+ " JOIN hisob_fakturalar f ON f.id = o.faktura_id"
+ " WHERE o.jamoa_id = $1", [jamoa]);
if (bor !== undefined)
return { raqam: bor.raqam, buyurtmaId: Number(bor.buyurtma_id),
summa: Number(bor.summa) };
const o = await this.ol(jamoa, c);
const s = summa ?? o.reja.narx;
const { rows: [egasi] } = await c.query<{ id: string }>(
"SELECT foydalanuvchi_id AS id FROM azoliklar"
+ " WHERE jamoa_id = $1 AND rol = 'egasi'", [jamoa]);
const { rows: [b] } = await c.query<{ id: string }>(
"INSERT INTO buyurtmalar (foydalanuvchi_id, summa, tavsif)"
+ " VALUES ($1, $2, $3) RETURNING id",
[egasi?.id, s, `jamoa ${String(jamoa)}: ${o.reja.kod}`]);
const raqam = `JM-${String(this.soat().getUTCFullYear())}-${
String((await c.query<{ n: string }>(
"SELECT nextval('faktura_raqami') AS n")).rows[0]?.n)
.padStart(6, "0")}`;
const { rows: [f] } = await c.query<{ id: string }>(
"INSERT INTO hisob_fakturalar (raqam, jamoa_id, buyurtma_id,"
+ " tarif, summa, davr_boshi, davr_oxiri)"
+ " VALUES ($1, $2, $3, $4, $5, $6, $7) RETURNING id",
[raqam, jamoa, b?.id, o.reja.kod, s, o.davrOxiri, o.davrOxiri]);
await c.query("INSERT INTO ochiq_fakturalar"
+ " (jamoa_id, faktura_id)"
+ " VALUES ($1, $2)", [jamoa, f?.id]);
this.xatlar.push({ jamoa, shablon: "faktura", faktura: raqam });
return { raqam, buyurtmaId: Number(b?.id), summa: s };
}Uch narsa:
- Faktura = buyurtma. 29-qismdagi
buyurtmalarjadvali o'zgarmagan, Payme va Click esa buyurtma bilan ishlaydi. Shuning uchun har faktura uchun bitta buyurtma ochiladi, Payme'gaorder_idsifatida uning id'si beriladi. - Raqam —
JM-2026-000001shaklida,faktura_raqamiketma-ketligidan. Ketma-ketlik bo'shliq qoldirishi mumkin (ROLLBACK bo'lgan raqam qaytmaydi). Faktura uchun bu odatda muammo emas, lekin buxgalteriya talabi bo'lsa — alohida hisoblagich kerak. - Davr — pastdagi qatorga e'tibor bering:
o.davrOxiri, o.davrOxiri. Bu xato, «Natijani halol o'qish» bo'limida qaytamiz.
4.4 To'lov: webhook — yagona haqiqat manbai
sequenceDiagram
participant E as Egasi
participant A as API
participant P as Payme
E->>A: POST /obuna/faktura
A-->>E: raqam, order_id, summa
E->>P: to'lov sahifasi (karta)
P->>A: CheckPerformTransaction
P->>A: CreateTransaction
P->>A: PerformTransaction
A->>A: bitta tranzaksiya: ledger, faktura, obuna
A-->>P: state 2Obuna egasi brauzerda "to'landi" sahifasini ko'rganda emas, Payme serveri PerformTransaction yuborganda faollashadi. Bu ADR-0004: holat faqat tekshirilgan webhook'dan o'zgaradi. Redirect sahifasiga ishonish — soxtalashtirishning eng oson yo'li (To'lov xavfsizligi).
29-qismdagi routerlarga bitta narsa qo'shildi — tolandi hook'i. Router uni PerformTransaction (Click'da — complete) tranzaksiyasining ichida chaqiradi (qatorga bo'lindi, kanon bilan aynan):
tolandi = async (c: PoolClient, buyurtmaId: number)
: Promise<void> => {
const { rows: [f] } = await c.query<{ jamoa_id: string }>(
"SELECT jamoa_id FROM hisob_fakturalar WHERE buyurtma_id = $1",
[buyurtmaId]);
if (f === undefined) return; // jamoa fakturasi emas
await c.query("DELETE FROM ochiq_fakturalar WHERE jamoa_id = $1",
[f.jamoa_id]);
await this.hodisa(c, Number(f.jamoa_id), { tur: "tolov_otdi" });
};Nega o'sha tranzaksiyada? Ikki alohida tranzaksiya bo'lsa, ular orasida jarayon qulashi mumkin: pul olingan, obuna esa "sinov" da qolgan. Bitta tranzaksiyada esa yo hammasi (tranzaksiya bajarilgan, ledger yozuvi, faktura yopildi, obuna faol), yo hech narsa. Hook xato bersa, butun Perform bekor bo'ladi va Payme uni qayta yuboradi.
hodisa() ichida obuna qatori FOR UPDATE bilan qulflanadi. Billing sikli va webhook bir vaqtda kelsa, biri ikkinchisini kutadi. Takroriy Perform esa 29-qismdagi idempotentlik bilan ushlanadi: tranzaksiya allaqachon bajarilgan — o'sha javob, hook ikkinchi marta chaqirilmaydi.
Click'da ham xuddi shu: prepare buyurtmani tekshiradi, complete esa to'lovni yozadi va hook'ni chaqiradi. Farq formatda: Click application/x-www-form-urlencoded yuboradi va summa so'mda, ikki kasr bilan ("49000.00"), imzo esa MD5 bilan hisoblanadi. Kanon testida summa (f.summa / 100).toFixed(2) bilan yasaladi. Bu tiyin → so'm o'tkazish faqat chegarada, provayder bilan gaplashganda bo'ladi; ichkarida hamma joyda tiyin.
Tekshirib ko'ring:
tolandihook'i ichida xat yuborish (SMTP) chaqirilsa nima bo'ladi?
Javob
Uchta yomon narsa. Birinchisi: SMTP sekin yoki o'chiq bo'lsa, Payme'ning Perform so'rovi kutib qoladi va provayder uni timeout deb hisoblashi mumkin. Ikkinchisi: xat ketdi, keyin tranzaksiya yiqildi — mijoz "to'landi" xatini oldi, lekin obuna faol emas. Uchinchisi: Payme Perform ni qayta yuborsa, xat ikki marta ketishi mumkin. To'g'ri yo'l — hook ichida faqat bazaga yozish (xat navbatiga qator), yuborish esa ishchida. Bu oldingi darsdagi ADR-0005 qoidasi.
4.5 Biz shunday xato qildik: Payme -32700
Payme so'rovlarini Content-Type: text/json bilan yuboradi — application/json emas. 29-qismdagi router buni biladi: tanani o'zi matn sifatida o'qiydi va o'zi JSON.parse qiladi. JSON buzilgan bo'lsa — Payme kutgan xato kodi -32700.
jamoa da birinchi variantda app.use(express.json()) routerdan oldin turardi. Natija: Payme so'rovlari sinovda -32700 ("JSON tahlil xatosi") qaytardi, holbuki JSON to'g'ri edi. Sabab — oqim. Body-parser tanani oldin o'qib bo'lgan bo'lsa, router uchun o'qiladigan narsa qolmaydi. Router bo'sh satrni tahlil qila olmaydi. Xom xato logi saqlanmagan, xulosa kanon hisobotidan.
Tuzatish — tartib (ilova.ts, qatorga bo'lindi, kanon bilan aynan):
// Payme router tanani o'zi o'qiydi (text/json); Click — urlencoded
app.use("/v1/tolov/payme", paymeRouter({ pool: s.pool,
login: s.payme.login, kalit: s.payme.kalit,
tolandi: billing.tolandi,
hozir: () => (s.soat?.() ?? new Date()).getTime() }));
app.use("/v1/tolov/click",
express.urlencoded({ extended: false, limit: "8kb" }),
clickRouter({ pool: s.pool, serviceId: s.click.serviceId,
sir: s.click.sir, tolandi: billing.tolandi }));
app.use(express.json({ limit: "16kb" }));Webhook marshrutlari — umumiy body-parser'dan oldin, har biri o'z formatida. Bu faqat Payme'ga xos emas. Imzoni xom tana bo'yicha tekshiradigan har webhook (Stripe, GitHub, Telegram) uchun bir xil qoida: tana tahlil qilinmasdan oldin olinadi (Kiruvchi webhook'larni qabul qilish). Nest'da bodyParser: false aynan shuning uchun.
4.6 Dunning: jonli model
Billing sikli har soat ishlaydi (oldingi dars). Bitta obuna uchun u qanday qaror qiladi? Kanon testi sinov boshidan 14, 14.5, 15.5, 18.5 va 25.5 kunda siklni chaqiradi. Mana shu mantiqning soddalashtirilgan modeli (vaqt — kunlarda):
// vaqt — kunlarda (0 — jamoa ochilgan payt), sinov — 14 kun
const DUNNING_KUN = [1, 3, 7];
function tolovOtmadi(o, hozir) {
o.urinishlar++;
const kun = DUNNING_KUN[o.urinishlar - 1];
if (kun === undefined) {
o.holat = "bekor";
return "obuna-bekor";
}
o.holat = "qarzdor";
o.keyingi = hozir + kun;
return "tolov-otmadi";
}
// billing sikli: bitta obuna uchun bitta qadam
function sikl(o, hozir) {
if (o.holat === "qarzdor" && o.keyingi <= hozir) {
return tolovOtmadi(o, hozir);
}
const davrTugadi = o.davrOxiri <= hozir && o.yangilangan < hozir;
if ((o.holat === "sinov" || o.holat === "faol") && davrTugadi) {
o.yangilangan = hozir;
if (o.ochiqFaktura) return tolovOtmadi(o, hozir);
o.ochiqFaktura = true; // undir: yangi faktura
return "faktura";
}
return "-";
}
const huquqBormi = (o) =>
o.holat !== "bekor" && o.holat !== "tugagan";
const o = { holat: "sinov", davrOxiri: 14, yangilangan: 0,
urinishlar: 0, keyingi: null, ochiqFaktura: false };
for (const kun of [14, 14.5, 15.5, 18.5, 25.5]) {
const xat = sikl(o, kun);
console.log(`${kun}-kun: ${o.holat}:${o.urinishlar}, xat ${xat}`);
}
console.log("vazifa yozish:", huquqBormi(o) ? 201 : 402);Konsolda:
14-kun: sinov:0, xat faktura
14.5-kun: qarzdor:1, xat tolov-otmadi
15.5-kun: qarzdor:2, xat tolov-otmadi
18.5-kun: qarzdor:3, xat tolov-otmadi
25.5-kun: bekor:4, xat obuna-bekor
vazifa yozish: 402Holatlar ketma-ketligi kanon testi bilan aynan: sinov:0 → qarzdor:1 → qarzdor:2 → qarzdor:3 → bekor:4, xatlar — faktura, uch marta tolov-otmadi, obuna-bekor, oxirida 402. Modeldagi huquqBormi soddalashtirilgan: kanon funksiyasi sinov va faol uchun davr oxirini ham tekshiradi. Aynan shu farq keyingi bo'limda muhim bo'ladi.
5. Tekshirish
5.1 Billing testlari
test/billing.test.ts — beshta test, 29-qismdagi Payme va Click lokal soxta serverlari (simulyatorlari) bilan. Soat — soxta (soat: () => new Date(soat)), shuning uchun 14 kun bir soniyada o'tadi (Vaqt va tasodifni boshqarish).
| Test | Natija |
|---|---|
| sinov → faktura → Payme | sinov 14 kun; faktura JM-2026-…, qayta so'rov — o'sha raqam; kam summa — -31001; Perform → state 2; takroriy Perform — o'sha state 2; obuna faol, davr oxiri 2026-12-24 (sinov oxiri + 1 oy); ledger: debet = kredit = summa |
| muddati o'tgan tranzaksiya | Create, 13 soat kutish, Perform → -31008, state -1, obuna sinov da qoldi |
| Click | buzuq imzo — -1; prepare/complete → faol; takroriy complete — xato emas, ledger bir marta |
| dunning | sinov:0 → qarzdor:1/2/3 → bekor:4, keyin yozish — 402 |
| parallel sikl | uchta sikl bir vaqtda — bitta faktura |
Hammasi — npm run check ning 11/11 testi ichida. Davr oxiri 2026-12-24 muhim: egasi sinovning 2-kunida to'lagan, lekin yangi davr sinov oxiridan boshlanadi. U to'lagan pulning bir kunini ham yo'qotmaydi.
5.2 Natijani halol o'qish: to'rtta billing nuqsoni
Testlar yashil. Lekin kanon kodini o'qib, keyin sof funksiyalarni (obuna.ts) ishga tushirib, to'rtta nuqson topdik. Ular billing testlarida yo'q, chunki testlar boshqa vaqtlarni sinaydi. Skript va natijalar mashq papkasidagi olchov/ da (biz yozdik, kanon xomida yo'q).
1. Birinchi eslatma faktura bilan bir soat farqda. Sikl har soat ishlaydi. Faktura ochilgan soatdan keyingi siklda shart yana bajariladi: davr tugagan, faktura ochiq. Natija — tolov_otmadi, birinchi "to'lov o'tmadi" xati. DUNNING_KUN ning birinchi "1 kun"i esa shundan keyin boshlanadi. Test sikl'ni 14 va 14.5-kunda chaqirgani uchun buni ko'rsatmaydi.
2. Sinov tugagach bir soatlik 402. huquqBormi() sinov uchun hozir < davrOxiri ni tekshiradi. Sinov tugadi, holat hali sinov — yozish 402. Keyingi siklda holat qarzdor bo'ladi va xizmat qaytadan ishlaydi. Soatlik modelning natijasi (obuna.ts ning o'z funksiyalari bilan). Ikkinchi qatordagi yozish ustuniga qarang:
sinov oxiri -1 soat: sinov:0, xat -, yozish 201
sinov oxiri +0 soat: sinov:0, xat faktura, yozish 402
sinov oxiri +1 soat: qarzdor:1, xat tolov-otmadi, yozish 201
sinov oxiri +2 soat: qarzdor:1, xat -, yozish 201
sinov oxiri +25 soat: qarzdor:2, xat tolov-otmadi, yozish 201Foydalanuvchi uchun bu g'alati: bir soat bloklangan, keyin yana ochilgan. Sabab — ikki qaror ("davr oxirida huquq tugaydi" va "qarzdorga grace") alohida-alohida to'g'ri, birga esa bo'shliq qoldiradi.
3. Bekor obunaga kech to'lov — qaytarilmaydi. Bekor bo'lgan jamoaning fakturasi ochiq qoladi va uni hali to'lash mumkin. To'lov kelsa, holat mashinasi to'g'ri javob beradi: [{"tur":"qaytar","summa":4900000}] — "pulni qaytar". Lekin Billing.hodisa() faqat undir va xat amallarini bajaradi, qaytar ni jim tashlab yuboradi. Natija: pul olindi, obuna tiklanmadi, qaytarish ham yo'q. Mijoz bilan nizo kafolatlangan.
4. Faktura davri. hisob_fakturalar ga davr_boshi ham, davr_oxiri ham o.davrOxiri yoziladi. Fakturada "24-noyabrdan 24-noyabrgacha" chiqadi. Kutilgani — davr_oxiri = oyQosh(davrOxiri, 1).
Tekshirib ko'ring: Nega to'rttala nuqson ham kanonning beshta billing testida ko'rinmadi, holbuki testlar soxta soat bilan 25 kunni "yashab" o'tdi?
Javob
Testlar siklni faqat tanlangan nuqtalarda chaqiradi: 14, 14.5, 15.5 … kun. Sinov oxiridan keyingi bir soatlik 402 o'sha nuqtalar orasiga tushadi. Fakturadan bir soat keyingi eslatma ham shunday. qaytar amali esa faqat "bekor obunaga kech to'lov" holatida chiqadi — bunday test yo'q. Faktura davri esa tekshirilmaydi: testlar faqat raqam va summaga qaraydi. Test faqat so'ralgan savolga javob beradi.
Uchinchisi eng xavflisi: u pulga tegadi. To'rttalasi uchun tuzatish rejasi «O'zingiz qiling» bo'limida. Saboq umumiy: holat mashinasi qaytargan har amal bajarilsin, noma'lumi esa xato bersin. if … else if zanjiri yangi amal turini jim yutadi. switch va TypeScript never tekshiruvi esa uni kompilyatsiyada ushlaydi (Discriminated union va to'liqlik tekshiruvi).
5.3 Sinalmaganlar
- Haqiqiy Payme va Click sandbox. Hamma to'lov testlari lokal soxta serverlar bilan. Haqiqiy merchant akkaunt va shartnoma — biznes ishi: yuridik shaxs, bank hisobi, provayder bilan kelishuv. Kursda bu qilinmadi.
- Kartani saqlab avtomatik yechish (Payme Subscribe API va boshqalar) — hujjat bo'yicha mavjud, kursda sinalmagan.
- To'lov sahifasi havolasi. RFC'da "obuna → to'lov sahifasi URL'i" yozilgan, kanon esa faqat
order_idva summani qaytaradi. Havola formati — Payme Merchant API darsida.
6. Hujumchi nigohi
To'lov hujumlarining asosiy turlari To'lov xavfsizligi darsida o'lchangan. jamoa billing'ida ular qanday yopilgani:
| Hujum | Qanday urinadi | Javob |
|---|---|---|
| Kam to'lash | amount ni kamaytiradi |
-31001 (summa faktura bilan solishtiriladi) |
| Soxta webhook | Payme nomidan Perform yuboradi |
Basic auth (kassa kaliti, timingSafeEqual) — -32504 |
| Takroriy to'lov | bir Perform ni ikki marta |
o'sha javob, ledger bir marta |
| Eski tranzaksiya | 13 soatdan keyin Perform |
-31008, tranzaksiya bekor |
| "To'landi" sahifasi | redirect URL'ni o'zi ochadi | holat faqat webhook'dan |
| Limitni chetlab o'tish | pastroq tarifda 20 parallel yozuv | obuna qatori qulfi |
Payme hujjati so'rovlar faqat ma'lum IP oralig'idan kelishini aytadi (oraliq — Payme Merchant API darsida). Kanon routerida ruxsatIp ixtiyoriy parametr sifatida bor, lekin jamoa uni ulamagan. Production'da teskari proksi darajasida cheklash — qo'shimcha qatlam.
Click imzosi MD5 bilan hisoblanadi. MD5 bugun kriptografik jihatdan zaif hisoblanadi, lekin bu provayder shartnomasi — uni o'zimiz tanlay olmaymiz. Biz qila oladigan narsa: imzoni timingSafeEqual bilan solishtirish (vaqt hujumiga qarshi), sirni .env da saqlash va har so'rovda summani bazadagi buyurtma bilan tekshirish. Imzo to'g'ri bo'lsa ham, summa mos kelmasa — -2. Bitta himoyaga emas, bir nechta mustaqil tekshiruvga tayanamiz.
7. Ko'p uchraydigan xatolar
7.1 Redirect'ga ishonish
"To'lov muvaffaqiyatli" sahifasi — faqat foydalanuvchi uchun. Obuna holati — webhook'dan.
7.2 To'lov va obunani ikki tranzaksiyada yozish
Orasida qulash — "pul bor, obuna yo'q". Hook to'lov tranzaksiyasi ichida.
7.3 Body-parser'ni webhook'dan oldin qo'yish
Xom tana yo'qoladi: imzo tekshiruvi yoki -32700. Webhook marshrutlari — umumiy parser'dan oldin.
7.4 Pulni kasr son bilan
49000.00 emas, 4_900_000 tiyin. Proratsiya — BigInt bilan, yaxlitlash qoidasi yozilgan.
7.5 Holat mashinasi amalini yutish
Har amal turi bajarilsin. Noma'lum tur — xato, jim else emas.
7.6 Narxni o'ylab topish
Darsdagi narxlar — namuna. Haqiqiy narx — bozor tadqiqoti va hisob-kitob natijasi.
8. Mashqlar
Mashqlar kurs/mashqlar/38/04-saas-billing/ da. 2- va 3-mashq yechimlari Node 24.21.0 da tekshirilgan (biz ishga tushirdik).
1-mashq (oson): bo'shliqlarni to'ldiring
- Obuna faol emas, yozish so'rovi javobi —
- Kanonda bitta jamoaning bir vaqtdagi ochiq fakturalari soni — ko'pi bilan
- 49 000 so'm tiyinda —
- Payme'da kam summa yuborilsa, xato kodi —
- Obuna holatini o'zgartiradigan yagona manba — tekshirilgan
Yechim
- 402 — Payment Required; tarif limiti esa 409.
- 1 —
ochiq_fakturalardajamoa_idbirlamchi kalit. - 4900000 — 1 so'm = 100 tiyin; kodda
4_900_000. - -31001 — Payme Merchant API'ning "noto'g'ri summa" xatosi.
- webhook — redirect sahifasi emas (ADR-0004).
2-mashq (o'rta): proratsiya
Egasi davr o'rtasida tarifni almashtiradi. proratsiya(eskiNarx, yangiNarx, bosh, oxir, hozir) yangi va eski tarifning qolgan qismi farqini tiyinda qaytarsin: musbat — undirish, manfiy — qaytarish. Hisob BigInt bilan, har qism alohida pastga yaxlitlanadi (kanondagidek). Davr — 24-noyabrdan 24-dekabrgacha. Uch holatni sinang: o'rtada yuqoriga, o'rtada pastga, oxiridan 1 soat oldin yuqoriga.
Ishora: BigInt bo'lishi butun qismni qaytaradi (BigInt: juda katta butun sonlar). Vaqtlar — Date.parse dan millisekund.
Yechim
// narxlar — tiyinda (1 so'm = 100 tiyin), NAMUNA tariflar
const BOSHLANGICH = 4_900_000;
const JAMOA = 14_900_000;
function proratsiya(eskiNarx, yangiNarx, bosh, oxir, hozir) {
const jami = BigInt(oxir - bosh);
const qolgan = BigInt(Math.max(0, oxir - hozir));
const kredit = (BigInt(eskiNarx) * qolgan) / jami;
const yangiQism = (BigInt(yangiNarx) * qolgan) / jami;
return Number(yangiQism - kredit);
}
const som = (t) => `${(t / 100).toFixed(2)} so'm`;
const bosh = Date.parse("2026-11-24T09:00:00Z");
const oxir = Date.parse("2026-12-24T09:00:00Z");
const holatlar = [
["oyning o'rtasida yuqoriga", BOSHLANGICH, JAMOA,
"2026-12-09T09:00:00Z"],
["oyning o'rtasida pastga", JAMOA, BOSHLANGICH,
"2026-12-09T09:00:00Z"],
["oxiridan 1 soat oldin", BOSHLANGICH, JAMOA,
"2026-12-24T08:00:00Z"],
];
for (const [nom, eski, yangi, vaqt] of holatlar) {
const farq = proratsiya(eski, yangi, bosh, oxir, Date.parse(vaqt));
const amal = farq > 0 ? "undir" : farq < 0 ? "qaytar" : "-";
console.log(`${nom}: ${amal} ${farq} tiyin`,
`(${som(Math.abs(farq))})`);
}Konsolda:
oyning o'rtasida yuqoriga: undir 5000000 tiyin (50000.00 so'm)
oyning o'rtasida pastga: qaytar -5000000 tiyin (50000.00 so'm)
oxiridan 1 soat oldin: undir 13889 tiyin (138.89 so'm)Uchala son kanon obuna.ts dagi proratsiya bilan aynan (biz ikkalasini ham ishga tushirdik). Uchinchi qatorga qarang: aniq farq 13 888.(8) tiyin. Lekin har qism alohida yaxlitlanadi: 20 694 − 6 805 = 13 889. Bitta tiyin — yaxlitlash qoidasi natijasi. Shuning uchun qoida kodda yozilgan bo'lishi kerak, "taxminan" emas. 138 so'm undirish uchun esa Payme fakturasi ochish ma'nosiz — haqiqiy tizim bunday kichik farqni keyingi davrga qo'shadi. Bu ham biznes qarori.
3-mashq (qiyin): dunning jadvali
Faktura ochilgan vaqtdan boshlab mijozga qachon nima kelishini hisoblang. Sikl har soat ishlaydi, shuning uchun birinchi eslatma fakturadan bir soat keyin («Natijani halol o'qish» bo'limidagi 1-nuqson). Keyingi eslatmalar oralig'i — DUNNING_KUN = [1, 3, 7], oxirgisidan keyin — bekor. Vaqtni Toshkent vaqtida (UTC+5) YYYY-MM-DD HH:MM ko'rinishida chiqaring.
Ishora: toISOString() UTC qaytaradi — oldin 5 soat qo'shing, keyin slice va replace (Date asoslari).
Yechim
const SOAT = 3_600_000;
const KUN = 24 * SOAT;
const DUNNING_KUN = [1, 3, 7];
// Toshkent vaqti (UTC+5) — "2026-11-24 14:00"
const toshkent = (t) =>
new Date(t + 5 * SOAT).toISOString().slice(0, 16).replace("T", " ");
function dunningJadvali(fakturaVaqti) {
const jadval = [["faktura", fakturaVaqti]];
let t = fakturaVaqti + SOAT; // keyingi soatlik sikl
DUNNING_KUN.forEach((kun, i) => {
jadval.push([`${i + 1}-eslatma`, t]);
t += kun * KUN;
});
jadval.push(["bekor", t]);
return jadval.map(([nom, vaqt]) => `${nom}: ${toshkent(vaqt)}`);
}
console.log(dunningJadvali(Date.parse("2026-11-24T09:00:00Z"))
.join("\n"));Konsolda:
faktura: 2026-11-24 14:00
1-eslatma: 2026-11-24 15:00
2-eslatma: 2026-11-25 15:00
3-eslatma: 2026-11-28 15:00
bekor: 2026-12-05 15:00Jadval kanon xulqini ko'rsatadi: fakturadan 11 kun-u bir soatdan keyin bekor. Birinchi ikki qator orasidagi bir soat — mijoz "faktura" va "to'lov o'tmadi" xatlarini deyarli birga oladi. Tuzatilgan versiyada birinchi eslatma fakturadan bir kun keyin keladi va jadval bir kunga suriladi. Toshkent vaqtini qo'lda hisobladik, chunki Intl natijasi Node va brauzerda farq qilishi mumkin. O'zbekistonda yozgi vaqt yo'q, shuning uchun +5 doimiy.
9. O'zingiz qiling: billing moduli
billing/tolov/— 29-qismdagi paketni ko'chiring (Payme, Click, ledger,obuna.ts) vatolandihook'ini qo'shing.api/sql/002-tolov.sql:obunalar,hisob_fakturalar,ochiq_fakturalar,faktura_raqamiketma-ketligi.Billing:boshla(jamoa ochilganda sinov),huquq(402/409),hodisa(qulf bilan),faktura,tolandi,tsikl.- Marshrutlar:
GET /tariflar,GET /jamoalar/:j/obunavaPOST /jamoalar/:j/obuna/faktura(faqat egasi); Payme va Click —express.jsondan oldin. - Testlar — kanondagi beshta: Payme to'liq oqim va takror, muddati o'tgan tranzaksiya, Click, dunning, parallel sikl.
- Nuqsonlarni tuzating — har biriga avval eski kodda yiqiladigan test:
- birinchi eslatma — fakturadan
DUNNING_KUN[0]kun keyin, bir soatdan keyin emas; - davr tugagach birinchi siklgacha 402 bo'lmasin (masalan, ochiq faktura bo'lsa — grace);
qaytaramali —qaytarishlarjadvaliga yozuv va egasiga xat; noma'lum amal — xato;- faktura davri —
oyQosh(davrOxiri, 1)bilan.
- birinchi eslatma — fakturadan
- Kunlik solishtirish: Payme
GetStatementnatijasini bazadagi tranzaksiyalar bilan solishtiradigan fon ish, kun chegarasiAsia/Tashkent(Refund, reconciliation va moliyaviy hisob).
Yechim namunasi: (c) — `qaytar` ni yutmaslik
Kanonda bu tuzatish yo'q. Yo'nalish — amal turlarini to'liq qamrab olish, TypeScript tekshiradigan qilib:
for (const a of n.amallar) {
switch (a.tur) {
case "undir": await this.faktura(c, jamoa, a.summa); break;
case "xat":
this.xatlar.push({ jamoa, shablon: a.shablon }); break;
case "qaytar": await this.qaytarishYoz(c, jamoa, a.summa); break;
default: { const yoq: never = a; throw new Error(String(yoq)); }
}
}qaytarishYoz — qaytarishlar jadvaliga idempotentlik kaliti bilan yozuv (masalan, kech-tolov:<faktura raqami>) va egasiga xat. Pulni qaytarishning o'zi — Payme CancelTransaction yoki qo'lda, buxgalter orqali. Test: bekor obuna + Payme Perform → qaytarishlar da bitta qator, obuna bekor da qoladi. Yangi amal turi qo'shilsa, never qatori kompilyatsiyani to'xtatadi.
10. Real ishda
- SaaS'da billing — ko'pincha eng ko'p qayta yoziladigan modul. Tarif, chegirma, yillik to'lov, QQS — har yangi talab holat mashinasiga yangi o'tish qo'shadi.
- O'zbekistonda mahalliy mijozlar Payme, Click va Uzum orqali to'laydi, xalqarolar — kartadan. Ko'p SaaS ikkala yo'lni ham saqlaydi: mahalliy uchun faktura, xalqaro uchun avtomatik yechish.
- Qo'llab-quvvatlashda eng ko'p keladigan murojaat — "pul yechildi, lekin xizmat ishlamayapti". Javob uchun uchta manba kerak: provayder tranzaksiyasi, ledger yozuvi va obuna holati tarixi. Ular bo'lmasa, har murojaat qo'lda tergovga aylanadi.
- Buxgalteriya faktura raqamlari ketma-ket va bo'shliqsiz bo'lishini talab qilishi mumkin. Bu — dasturchi bilan buxgalter suhbatining birinchi savoli.
- Intervyuda "obuna tizimini qanday qurasiz?" savoliga holat mashinasi, webhook idempotentligi va dunning bilan javob bering. Kech to'lov kabi chekka holatni aytsangiz, ajralib turasiz.
Xulosa
- Billing = tarif (namuna narxlar, limitlar) + obuna holat mashinasi + to'lov; bepul tarif yo'q, 14 kunlik sinov.
jamoa— hisob-faktura modelida: Payme/Click bilan avtomatik yechish sinalmagan;undir= yangi faktura va xat.- Obuna faqat tekshirilgan webhook'dan o'zgaradi —
tolandito'lov tranzaksiyasi ichida; webhook marshrutlari body-parser'dan oldin. - Faktura idempotent: bitta jamoada bitta ochiq; dunning 1, 3, 7 kun → bekor → 402.
- Testlar yashil, lekin kod o'qish va o'lchov to'rtta nuqson topdi: bir soatlik 402, eslatma vaqti, yutilgan
qaytar, faktura davri.
Keyingi dars: SaaS capstone 4: production'ga chiqarish — Dockerfile, Compose (api × 2, ishchi, web), migratsiya, zaxira, CI va lokal production o'lchovi.
Manbalar
- Payme Business — Merchant API hujjati: https://developer.help.paycom.uz/ (tekshirildi, 2026-11: JSON-RPC 2.0, HTTP POST, javob har doim HTTP 200; Subscribe API bo'limi bor. Xato kodlari va 12 soatlik timeout — 29-qism darslarida hujjatdan olingan, bu safar sahifa (SPA) matni avtomatik o'qilmadi)
- Click — integratsiya hujjati: https://docs.click.uz/ (tekshirildi, 2026-11: SHOP API — Prepare va Complete so'rovlari; MD5 formulasi va xato kodlari — 29-qism darsida Click'ning rasmiy kutubxonasidan)
- Stripe — qo'llab-quvvatlanadigan mamlakatlar: https://stripe.com/global (tekshirildi, 2026-11-10: ro'yxatda O'zbekiston yo'q)
- RFC 9110 — 402 Payment Required: https://www.rfc-editor.org/rfc/rfc9110#name-402-payment-required (tekshirildi, 2026-11: "reserved for future use")
- Kurs tajribasi (IlmHamroh, 2026-11):
jamoabilling — 5 test (Payme va Click lokal soxta serverlari, soxta soat),npm run check11/11. Nuqsonlar — kod o'qish vaobuna.tsfunksiyalarini ishga tushirish bilan topildi (2026-11-10), billing integratsiya testi bilan sinalmagan. Bo'laklar kanon bilan esbuild orqali solishtirildi; mashq yechimlari — biz ishga tushirdik.
Izohlar · 0
Izoh yozish uchun kiring.