# Көтерме саудаға

> Ірі сомалы счёт, тапсырыс нөмірі бойынша есеп айырысу, бір сұрауда 100-ге дейін счёт, тұрақты клиенттерге жазылым, 1С-пен байланыстыру, ішінара төлем мен қайтару.

## Қысқаша

Көтерме саудада бір күнде аз счёт, бірақ әрқайсысы ірі — және әрқайсысының артында нақты тапсырыс, жүкқұжат, есеп айырысу тұр. Сондықтан бұл жерде маңыздысы QR емес, **есептің дұрыс жүруі**: `externalOrderId` арқылы счётты тапсырысқа байлау, `Idempotency-Key` арқылы қосарланудан қорғану және webhook арқылы төлемді өз жүйеңізге жазу. Бір сұрауда 100-ге дейін счёт шығаруға болады, ал тұрақты клиенттердің ай сайынғы төлемін жазылымға беруге болады.

## Негізгі сценарий

1. Менеджер 1С-те немесе CRM-де тапсырысты бекітеді: №РН-00142, 1 480 000 ₸.
2. Жүйе счёт жасайды:

```json
POST /api/v1/invoices
{
  "amount": 1480000,
  "kind": "phone",
  "description": "Тапсырыс РН-00142",
  "externalOrderId": "RN-00142",
  "customer": { "name": "ЖШС «Арна Трейд»", "phone": "77011234567" },
  "metadata": { "manager": "sultan", "warehouse": "almaty-1", "doc": "RN-00142" }
}
```

3. Клиенттің Kaspi-іне push келеді, ол төлейді.
4. Сізге `invoice.paid` webhook келеді — 1С-те төлем тіркеледі, тапсырыс жөнелтуге шығады.

Көтермеде `kind: "phone"` көбіне ыңғайлы: клиент офисте отырады, QR көрсететін экран жоқ. Бірақ мұнда екі шектеу бар: **`description` 60 таңба** және телефон `7XXXXXXXXXX` пішімінде болуы керек. Клиент қасыңызда тұрса немесе қоймадан алып жатса, `kind: "qr"` қолайлы, онда сипаттама 100 таңбаға дейін.

## Сома туралы

- `amount` — теңгемен. QR счёт ең көбі екі ондық белгіні алады, **телефонға счёт бүтін теңге болуы керек**. Тиынды дөңгелектеуді өз жүйеңізде жасаңыз, әйтпесе сома қабылданбай қалады: [Сома дұрыс емес немесе тиын жоғалып жатыр](/kb/wrong-amount).
- Біздің жағымызда құжатталған жоғарғы сома шегі жоқ, бірақ **Kaspi өз жағынан шектеу қоюы мүмкін** — ол шектеулерді Kaspi белгілейді, біз оларға әсер ете алмаймыз. Сондықтан бұрын-соңды болмаған ірі сомамен жұмыс бастар алдында бір счётты сынап көріңіз.
- Клиенттің Kaspi жағындағы лимиті де бар. Сома өтпесе, мәселе бізде емес екенін тексеріңіз: [Мәселе менде ме, Kaspi-де ме](/kb/is-it-us-or-kaspi).

## Қосарланудан қорғану

Ірі сомада қосарланған счёт — нақты шығын. Екі құралды бірге қолданыңыз.

**`Idempotency-Key` тақырыбы.** Мәні тапсырысқа байланған болсын, мысалы `RN-00142-v1`. Сол кілтпен қайталап жіберсеңіз жаңа счёт жасалмайды, бұрынғысы қайтады (HTTP 200, `idempotentReplay: true`). Желі үзіліп, жауап жетпей қалғанда осы құтқарады.

**`externalOrderId`.** Сіздің тапсырыс нөміріңіз. Webhook-та қайта келеді, іздеуде де қолданылады. Осы арқылы счётты құжатқа байлайсыз.

Егер қосарланған счёттар жаппай кетіп жатса, ең бірінші кілтті жойып, ағынды тоқтатыңыз: [Счёттар қосарланып жатыр](/kb/duplicate-invoices). Толық сипаттама: [Идемпоттылық](/kb/idempotency).

## Топтап счёт: POST /invoices/bulk

Ай басында дилерлерге, дүкендерге немесе нүктелерге бір мезгілде счёт шығару керек болса, бір сұрауда **1-100 счёт** жібересіз.

Маңызды тәртіп:

- **Әр элемент бөлек тексеріледі.** Біреуінің телефоны қате болса, қалғандары жасала береді. Бәрі құламайды.
- Жауапты **элемент бойынша қарап шығыңыз**: қайсысы жасалды, қайсысы қандай қатемен құлады.
- Құлағандарын түзеп қайта жіберіңіз — бірақ сол `Idempotency-Key` немесе сол `externalOrderId` мәндерімен, әйтпесе сәтті жасалғандары қосарланады.
- 100-ден көп болса, бірнеше сұрауға бөліңіз. Бәрін бір мезетте атқылап жібермеңіз: [Сұрау жиілігінің шектеулері](/kb/rate-limits).
- Есепте `metadata` ішіне дилер кодын жазып қойыңыз, кейін топтауға ыңғайлы.

Толығырақ: [Топтап счёт жасау](/kb/bulk-invoices).

## Тұрақты клиенттерге жазылым

Ай сайын бір клиентке бір сома шығып тұратын болса (сервис ақысы, абоненттік жеткізу, жалдамалы жабдық), [жазылым](/kb/subscriptions-api) қолайлы.

Бірақ көтермеде оның шегін білу керек: **жазылым тек счёт шығарады, ақша өздігінен алынбайды** — клиент әр төлемді Kaspi-де өзі растайды. Сондықтан ол келісімшарт бойынша міндетті төлемді кепілдендірмейді, ол тек «счётты қолмен шығаруды ұмытып кету» мәселесін шешеді.

Баптаулары: аралық `month`/`week`/`day` және кратность `every`; қайталау сатысы `retryDelaysMin` (әдепкі `[15, 60, 360]` минут, ең көбі 5 мән); өткізіп алу саясаты `misfirePolicy` — `run_once` (әдепкі) немесе `skip`, `misfireAfterMin` әдепкі 1440. Клиент уақытша тоқтаса `pause`, қайта бастағанда `resume`, өткен кезекті қуып жету керек болса `{ catchUp: true }`.

Толығырақ: [Жазылымдық бизнеске](/kb/for-subscription-business).

## 1С-пен байланыстыру

Дайын модуль жоқ, бірақ типтік схема жұмыс істейді:

1. **HTTP-сервис немесе фондық тапсырма.** 1С «Счёт на оплату» немесе «Реализация» құжатынан `POST /api/v1/invoices` жібереді. `externalOrderId` — құжат нөмірі.
2. **Кілт 1С серверінде тұрады**, пайдаланушының машинасында емес.
3. **Төлемді екі жолмен қабылдайсыз.** Ең сенімдісі — webhook сіздің серверіңізге келеді, ол 1С-ке жазады. Егер 1С сыртқа шыға алмайтын контурда тұрса, `GET /api/v1/invoices` арқылы мезгілмен сұрап тұрасыз.
4. **Номенклатура бізге жіберілмейді.** Счётта тек сома мен сипаттама бар, тауар тізімі 1С-те қалады.

Нұсқаулық: https://api.qut.kz/docs/guide/1c және [1С-тен Kaspi счёттарын шығару](/kb/for-1c).

## Ішінара төлем және қайтару

**Ішінара төлем.** Бір счёттың бір бөлігін төлеу мүмкін емес — Kaspi счёты бөлінбейді. Транш керек болса, **бірнеше счёт** шығарасыз:

- Алдын ала төлем 30%: `externalOrderId: "RN-00142-A"`, сомасы 444 000.
- Қалғаны жөнелтер алдында: `externalOrderId: "RN-00142-B"`, сомасы 1 036 000.
- Екеуінің `metadata` ішінде ортақ `doc: "RN-00142"` тұрсын — есепте бір тапсырыс болып жиналады.

Тапсырысты бөліктердің **бәрі** төленгенде ғана жабыңыз.

**Қайтару.** Толық та, ішінара да болады:

```json
POST /api/v1/invoices/{id}/refund
{ "amount": 120000, "reason": "Жарамсыз тауар қайтарылды, РН-00142" }
```

Ішінара қайтарылған счёт `partially_refunded` күйіне өтеді, ал ол әлі де «төленген» деп есептеледі. Жауап белгісіз күймен келсе (`refund_unknown`) қайталап жібере салмаңыз — ірі сомада бұл қымбатқа түседі: [Екі рет қайтарып жіберуден қалай сақтану керек](/kb/double-refund). Толығы: [Қайтару API](/kb/refunds-api).

## Есеп айырысу және салыстыру

- **CSV экспорт** — кезең бойынша, бухгалтерияға беруге дайын: [CSV экспорт және есеп](/kb/csv-export).
- **Салыстыруды `externalOrderId` бойынша жасаңыз**, сома бойынша емес. Бірдей сомалы екі тапсырыс жиі кездеседі.
- **Ақша тіке сіздің Kaspi шотыңызға түседі**, бізде ұсталмайды. Сондықтан банк үзіндісімен салыстырғанда сома сол қалпында көрінеді, Kaspi-дің өз шарттарын ескеріңіз.
- **Кеш келген төлемді ұмытпаңыз.** Жабылған счётқа ақша кейін келсе, `invoice.paid` `late: true` белгісімен келеді — ай жабылып кеткен болуы мүмкін: [Кеш келген төлем](/kb/late-payment).

## Жиі қойылатын сұрақтар

**Ең үлкен сома қанша болуы мүмкін?** Біздің жағымызда құжатталған шек жоқ. Kaspi мен клиенттің өз лимиттері болуы мүмкін — оны Kaspi белгілейді. Үлкен сомамен жұмысты бір сынақ счётынан бастаңыз.

**Бір сұрауда қанша счёт жіберуге болады?** 1-ден 100-ге дейін. Әр элемент бөлек тексеріледі, біреуінің қатесі қалғандарын құлатпайды.

**Клиент соманың жартысын төлей ала ма?** Бір счёт бойынша — жоқ. Транш үшін бөлек счёттар шығарасыз және оларды `metadata` арқылы бір тапсырысқа байлайсыз.

**Жазылым келісімшарттық төлемді кепілдендіре ме?** Жоқ. Ол счётты кестеге сай шығарады, ал төлемді клиент өзі растайды. Ақша өздігінен алынбайды.

**1С-ке дайын өңдеу бар ма?** Дайын модуль жоқ, бірақ типтік схема мен нұсқаулық бар: https://api.qut.kz/docs/guide/1c