Жазылымдар API-і: SaaS үшін тарифтер, қолжетімділік және лимиттер

Кабинетте тарифтерді қалай сипаттап, xsub_… кілтімен /v2/subscriptions арқылы қолжетімділікті, сынақ мерзімдерін және лимит шығынын тексеруге болады.

xpayment-те жазылымдар неге қажет

SaaS, қосымша, клуб немесе мектеп жүргізсеңіз және пайдаланушылар тарифтер бойынша қолжетімділік үшін төлесе, үш нәрсені сақтау керек: әр тарифке не кіреді, қашанға дейін төленген және лимиттің қаншасы жұмсалған. «Подписки» (Жазылымдар) бөлімі мұны өз мойнына алады. Тарифтерді кабинетте сипаттайсыз, ал сервисіңіз API арқылы сұрайды: «бұл пайдаланушыға не қолжетімді?».

xpayment мыналарды жүргізеді:

Бұл API арқылы төлем жасаудан өзгеше: төлем ақшаны бір рет қабылдайды, ал жазылым «пайдаланушыда қазір қолжетімділік бар ма» деген сұраққа жауап береді. Екеуі байланысты: жазылымға шот — қарапайым Kaspi-дегі телефонға шот.

Бұл қалай құрылған

«Подписки» кабинеті       Сіздің сервисіңіз                  xpayment
 жоспарлар, лимиттер <--> PUT  /v2/subscriptions/accounts/{id}   (пайдаланушы жасау)
 беру, төлем              GET  .../{id}/check?capability=...     (қолжетімділік бар ма?)
                          POST .../{id}/usage                    (шығынды есепке алу)

Бұл API үшін сізде жеке кілт бар: xsub_…. Ол жазылымдар жобасымен бірге беріледі және тек /v2/subscriptions мекенжайында жұмыс істейді. Төлем кілттері xapi_… және жазылым кілттері xsub_… алмастырылмайды: бір түрдегі кілт екіншісінің эндпоинттерінде 401 береді.

Жазылымдар әзірге бета күйінде. Шарттар мен өрістер нақтылануы мүмкін; өзекті анықтамалық — құжаттамада.

Кабинетте баптау

1. Жоба және кілт

Подписки (Жазылымдар) бөлімін ашып, жоба жасаңыз («Новый проект», Жаңа жоба). Онымен бірге xsub_… кілті жасалады: ол бір рет көрсетіледі, кейін тек префиксі көрінеді. Кілтті xapi_… сияқты серверде сақтаңыз.

Кілтті ауыстыруға болады: жаңа кілт бірден жұмыс істей бастайды, ал ескісі сервисті жаңартып үлгеруіңіз үшін тағы 24 сағат әрекет етеді. Ескі кілтті мерзімінен бұрын жоба баптауларында аяқтауға болады.

2. Каталог

Кабинет қойындыларында нені сатып жатқаныңызды сипаттайсыз:

Не Не үшін Мысал
Мүмкіндік Қолжетімділік жалаушасы catalog — «Тауар каталогы»
Лимит Бірлігі мен өшіру кезеңі бар есептегіш (жоқ, күн, ай) orders_m — айына «Тапсырыстар»
Жоспар Блоктардан (топтардан) құралған мүмкіндіктер мен лимиттер жиынтығы «Каталог» блогындағы «Старт»
Қосымша Жоспарға қосымша сатып алуға болатын нәрсе seat_extra — «Қосымша қызметкер»

Әр нысанның сервисіңіз API-де қолданатын коды бар, сондықтан қысқа әрі тұрақты кодтарды таңдаңыз. Жоспар «жоба», «белсенді» және «мұрағатта» күйлерінде болады; жазылым құрамына тек белсенді жоспарлар кіреді.

3. Аккаунттар және жазылымдар беру

Аккаунт — өніміңіздің пайдаланушысы немесе компаниясы. Аккаунтқа жазылымды:

Кабинет қойындылары шолуды, жазылымдар мен аккаунттар тізімін, төлемдерді, сынақ кезеңдерін, лимит шығынын және аналитиканы көрсетеді.

4. Касса және төлем

Жазылымдар жоба кассасынан аккаунттың телефонына шығарылатын Kaspi шотымен төленеді. Ол үшін аккаунтта телефон нөмірі көрсетілуі керек (әйтпесе API 409 PHONE_REQUIRED жауап береді), ал жобада касса таңдалған болуы керек: Кассаны қосу және API v2 кілті.

Автошот қалай жұмыс істейді: кезеңнің аяқталуына бірнеше күн қалғанда xpayment Kaspi шотын шығарады және ол төленгенше әрекетті қайталайды; төлем кезеңді ұзартады. Касса бұзылса немесе таңдалмаса, сіз түзетпейінше шот кетпейді. Ақша тікелей сіздің Kaspi шотыңызға түседі.

Сервисіңізге арналған API

База: https://api.xpayment.kz/v2/subscriptions. Тақырып: Authorization: Bearer xsub_…. Жауаптар Cache-Control: no-store тақырыбымен келеді. Бұл API-дегі қате мәтіндері ағылшынша.

Әдіс Жол Не істейді
PUT /accounts/{externalID} Аккаунт жасау немесе жаңарту
GET /accounts/{externalID} Аккаунттың құқықтары (entitlements)
GET /accounts/{externalID}/check Бір мүмкіндікті немесе лимитті тексеру
POST /accounts/{externalID}/trial Сынақ кезеңін іске қосу
POST /accounts/{externalID}/usage Лимит шығынын есепке алу

externalID — сіздің пайдаланушы идентификаторыңыз: A–Z a–z 0–9 . _ : @ + - таңбаларынан 1–100 таңба. Мекенжайда оны URL-кодтау керек (user@mail.kz → user%40mail.kz).

Аккаунт жасау

curl -X PUT "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040" \
  -H "Authorization: Bearer xsub_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kazmart.kz", "phone": "+7 701 200 10 30", "email": "admin@kazmart.kz"}'

Барлық өріс міндетті емес: жоқ өріс өзгермейді, null оны тазалайды. Телефон +7XXXXXXXXXX түріне келтіріледі. 201 (жасалды) немесе 200 (жаңартылды) жауабында аккаунт құқықтары болады.

Аккаунт құқықтары

GET /accounts/{externalID} мынаны қайтарады:

{
  "external_id": "shop_1040",
  "name": "Kazmart.kz",
  "status": "active",
  "access": true,
  "until": "2026-12-01",
  "access_ends_at": "2026-12-01T19:00:00Z",
  "period": "month",
  "plans": [{"code": "cat_start", "name": "Старт", "block": "Каталог"}],
  "capabilities": [
    {"code": "catalog", "name": "Тауар каталогы",
     "source": {"type": "plan", "code": "cat_start", "name": "Старт", "block": "Каталог"}}
  ],
  "limits": [
    {"limit": "orders_m", "name": "Тапсырыстар", "limit_value": 300, "unlimited": false,
     "used": 121, "remaining": 179, "resets_at": "2026-11-30T19:00:00Z"}
  ]
}

status: none (жазылым жоқ), trial, active, canceling (тоқтатылған, кезең соңына дейін қолжетімділік), expired. capabilities және limits өрістері тек access: true болғанда толтырылады. Жауапты бір минуттан артық емес кэштеуге болады: кабинеттегі өзгерістер келесі сұраныстан көрінеді.

Қолжетімділікті тексеру

Бір тексеру үшін check ыңғайлырақ: capability немесе limit параметрлерінің дәл біреуін көрсетіңіз.

# мүмкіндік бар ма
curl "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/check?capability=catalog" \
  -H "Authorization: Bearer xsub_СІЗДІҢ_КІЛТІҢІЗ"

# 5 бірлікке лимит жете ме
curl "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/check?limit=orders_m&need=5" \
  -H "Authorization: Bearer xsub_СІЗДІҢ_КІЛТІҢІЗ"

Жауап әрдайым 200 (белгісіз аккаунт үшін де): {"allowed": true, "reason": null, "status": "active", ...}. allowed: false болса, reason себебін түсіндіреді:

reason Мәні
account_not_found Мұндай аккаунт жоқ
no_subscription Аккаунтта жазылым жоқ
expired Мерзімі өтті
not_in_plan Мүмкіндік аккаунт жоспарларында жоқ
limit_not_set Жоспарларда мұндай лимит жоқ
limit_exhausted Қалдық need мәнінен аз

Мүмкіндіктің немесе лимиттің белгісіз коды 404 UNKNOWN_CODE береді.

Сынақ кезеңі

curl -X POST "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/trial" \
  -H "Authorization: Bearer xsub_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -d '{"plans": ["cat_start"], "addons": [], "period": "month"}'

Аккаунт болуы керек (алдымен PUT) және қолжетімділігі болмауы керек. Сынақ кезеңі таңдалған жоспарлардың ең ұзақ сынақ кезеңіндей созылады, ал period (month немесе year) одан кейінгі кезеңді белгілейді. 201 жауабында құқықтар болады. Типтік қателер: 404 ACCOUNT_NOT_FOUND, 409 TRIAL_NOT_ALLOWED (қолжетімділік бұрыннан бар), 409 TRIAL_ALREADY_USED, 409 NO_TRIAL (ешбір жоспарда сынақ кезеңі жоқ).

Шығынды есепке алу

curl -X POST "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/usage" \
  -H "Authorization: Bearer xsub_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "X-Idempotency-Key: order-8812-created" \
  -H "Content-Type: application/json" \
  -d '{"limit": "orders_m", "delta": 1}'

Ережелер:

Лимиттер Қазақстан күнтізбесі бойынша өшіріледі: күн сайын, ай сайын немесе өшірілмейді.

Жалпы қателер және сұраныс лимиттері

HTTP Код Себебі
401 UNAUTHORIZED Тақырып жоқ, кілт қате немесе жойылған, не xsub_ емес
429 RATE_LIMITED Сұраныс тым көп; Retry-After тақырыбын қараңыз
500 INTERNAL_ERROR Күтпеген қате

Жазылымдарда шығыс вебхуктар жоқ: сервисіңіз қажет сәтте GET /accounts/{id} немесе check сұрайды.

Әдеттегі енгізу схемасы

  1. Кабинетте тарифтерді сипаттаңыз: мүмкіндіктер, лимиттер, жоспарлар және қосымшалар. Қысқа әрі тұрақты кодтарды таңдаңыз.
  2. Пайдаланушы тіркелгенде аккаунт жасаңыз: атымен, телефонымен және email-мен PUT /accounts/{id}.
  3. Сынақ болса, сынақ кезеңін іске қосыңыз: жоспар кодтарымен POST …/trial.
  4. Маңызды жерде қолжетімділікті тексеріңіз: әрекеттен бұрын check?capability=… немесе барлық құқық бірден қажет болса, GET /accounts/{id}. Жауапты бір минуттан артық кэштемеңіз.
  5. Шығынды есепке алыңыз: X-Idempotency-Key бар POST …/usage, мысалы, order-8812-created. Сонда тайм-аутқа байланысты қайталау шығынды екі рет санамайды.
  6. Ұзартумен xpayment айналысады: Kaspi автошоты төлемнен кейін кезеңді ұзартады, ал сервисіңіз келесі тексеруде жаңа мерзімді көреді.

Практикалық кеңестер

Қайдан қарау керек