# CSV экспорт және есеп: счёттарды тізім етіп алу

> Счёттарды кабинеттен және API арқылы шығару, сүзгілер мен бағандардың мағынасы, UTF-8 кодтауы, Excel-дегі иероглиф және Kaspi Pay есебімен салыстыру — сандар неге дәл сәйкес келмеуі мүмкін.

## Қысқаша

Счёттардың тізімін екі жолмен аласыз: **кабинеттегі Счёттар бөлімінен** (сүзгі қойып, көрініп тұрған тізімді шығарасыз) және **API арқылы** (`GET /api/v1/invoices`, кезең мен күй бойынша сүзгісі бар). Екеуі де бір деректі береді — айырмашылығы тек ыңғайлылықта.

Ең маңызды екі ереже: **кодтауы UTF-8** (Excel-де файлды екі рет шертіп ашсаңыз иероглиф шығады) және **sandbox пен нақты режим бөлек** (тест счёттарын бухгалтерияға беруге болмайды).

## Кабинеттен шығару

Кабинет → **Счёттар**. Тізімді шығармас бұрын сүзгілерді қойыңыз:

| Сүзгі | Не істейді |
|---|---|
| Іздеу | Счёттың идентификаторы, тапсырыс нөмірі, сипаттама, клиенттің телефоны немесе аты бойынша |
| Күй | `pending`, `paid`, `failed`, `expired`, `cancelled`, `refunded` |
| Режим | Ұйымның режимі: sandbox счёттары нақты счёттардан бөлек тұрады |
| Кассир | Кілт нақты кассирге байланған болса, тізімде тек сол кассирдің счёттары болады |

Сүзгіні қойып алған соң тізімді файл етіп сақтайсыз. Кезеңді дәл қою керек болса (мысалы бір күнтізбелік ай), API нұсқасы ыңғайлырақ — оның `from` және `to` параметрлері бар.

## API арқылы шығару

`GET /api/v1/invoices` барлық сүзгіні қабылдайды:

| Параметр | Мәні |
|---|---|
| `from`, `to` | Кезеңнің басы мен соңы (ISO күн-уақыты) |
| `status` | Бір күй |
| `externalOrderId` | Нақты тапсырыс нөмірі |
| `search` | Идентификатор, тапсырыс нөмірі, сипаттама, телефон, аты бойынша |
| `limit`, `offset` | Бір сұрауда ең көбі 200 жазба, қалғаны `offset` арқылы |

Жауапта `invoices` тізімі және `total` — сүзгіге сай келетін жалпы сан. `total` сіз алған жазбадан көп болса, `offset` қадамымен келесі беттерді алыңыз.

Мысалы, тамыз айының счёттарын алу:

```bash
curl -s 'https://api.qut.kz/api/v1/invoices?from=2026-08-01T00:00:00%2B05:00&to=2026-08-31T23:59:59%2B05:00&limit=200' \
  -H 'X-API-Key: qp_live_…'
```

Алынған JSON-ды кез келген құралмен CSV-ге айналдырасыз. Файлды **UTF-8** етіп сақтаңыз — бұл қазақша мен орысша әріптердің дұрыс көрінуінің бірден-бір шарты.

Кілт нақты кассирге байланған болса, тізімде тек сол кассирдің нақты счёттары болады: [API кілтті кассирге байлау](/kb/api-key-connection).

## Бағандар нені білдіреді

Бағандар счёттың өрістеріне сай келеді.

| Баған | Мағынасы |
|---|---|
| `id` | Счёттың идентификаторы, `inv_…` |
| `createdAt` | Счёт жасалған уақыт |
| `paidAt` | Төлем расталған уақыт. Төленбесе бос |
| `amount` | Сомасы, теңге |
| `refundedAmount` | Қайтарылған сома, болса |
| `status` | Счёттың күйі |
| `kind` | `qr` немесе `phone` |
| `mode` | `live` немесе `sandbox` |
| `description` | Клиент көретін сипаттама |
| `externalOrderId` | Сіздің тапсырыс нөміріңіз |
| `customer` | Аты, телефоны, email — өзіңіз бергендері ғана |
| `receiptNumber` | Чек нөмірі, төленген счётта |

Күй бағанын оқығанда:

| Күй | Есепте нені білдіреді |
|---|---|
| `new`, `pending` | Ашық счёт, ақша әлі түспеген |
| `paid` | Төленген |
| `cancelled`, `expired` | Жабылған, ақша жоқ |
| `failed` | Төлем өтпеген |
| `refunded` | Төленген, сосын толық қайтарылған |
| `partially_refunded` | Төленген, бір бөлігі қайтарылған |

**Түсімді дұрыс есептеу:** `paid`, `refunded` және `partially_refunded` — үшеуі де төленген счёттар, бірақ соңғы екеуінен қайтарылған соманы шегеру керек. Яғни таза түсім = `amount` қосындысы − `refundedAmount` қосындысы. `new` мен `pending` есепке кірмейді.

## Кодтау және Excel

Файл UTF-8 болады. Excel оны екі рет шерту арқылы ашқанда өз компьютеріңіздің ескі кодтауымен оқуға тырысады — сол себепті әріптердің орнына иероглиф шығады. Файлдың өзінде ешқандай ақау жоқ.

Дұрыс ашу реті:

1. Excel-де бос кітап ашыңыз;
2. **Данные** → **Получить данные** → **Из текста/CSV**;
3. файлды таңдаңыз;
4. **Кодировка файла** (File Origin) өрісін **65001: Юникод (UTF-8)** етіңіз;
5. бөлгішті тексеріп, **Загрузить** басыңыз.

Сол терезеде телефон мен тапсырыс нөмірінің бағанын **Текст** типіне қойыңыз — әйтпесе Excel ұзын сандарды `7,7051E+10` түріне айналдырады немесе басындағы нөлді жоғалтады.

Ең оңай жол — файлды Google Sheets немесе LibreOffice Calc арқылы ашу: екеуі де UTF-8-ті өзі таниды. Толығырақ шешімдер: [Экспорт ашылмайды немесе дұрыс емес](/kb/csv-export-issue).

## Бухгалтерияға беру

- **Кезеңді күнтізбелік айға қойыңыз**, уақыт белдеуі — Алматы.
- **Нақты режимде екеніңізді тексеріңіз.** Sandbox жолдары есепке кірмеуі керек.
- **Файлды XLSX етіп сақтап беріңіз** — бухгалтердің компьютерінде иероглиф қайталанбас үшін.
- **Ақша Kaspi шотына тікелей түсетінін ескертіңіз.** Бұл тізім — счёттар, ал банк үзіндісі — ақша қозғалысы: [Ақша қашан және қайда түседі](/kb/money-arrival).

Бірнеше ұйым жүргізсеңіз, әр ұйымның есебі бөлек: [Бір аккаунтта бірнеше ұйым](/kb/multiple-organizations).

## Kaspi Pay есебімен салыстыру

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

| Себебі | Түсіндірмесі |
|---|---|
| Kaspi өз ұстап қалатын сомасын өзі анықтайды | Kaspi есебінде түскен сома біздегі счёт сомасынан аз болуы мүмкін |
| Qut Pay-ден тыс төлемдер | Қолма-қол ақша, POS, Kaspi қосымшасынан қолмен шығарылған счёт — Kaspi-де бар, бізде жоқ |
| Кеш келген төлемдер | Счёт жабылған соң ақша кейін келуі мүмкін: [Кеш келген төлем](/kb/late-payment) |
| Қайтарулар | Қайтару Kaspi үзіндісінде бөлек жолмен өтеді, бізде счёттың ішінде көрінеді |
| Кезеңнің шекарасы | Түн ортасында жасалған счёт бір күні, төленуі келесі күні болуы мүмкін |
| Sandbox жолдары | Kaspi-де мүлде жоқ |
| Бірнеше кассир | Кілт бір кассирге байланған болса, тізімде тек соның счёттары |

Сверканы дұрыс жүргізу реті: кезеңді екі жерде де бірдей қойыңыз → біздің тізімнен тек `paid`, `refunded`, `partially_refunded` күйлерін алыңыз → қайтарылған сомаларды шегеріңіз → Kaspi үзіндісіндегі осы кезеңдегі түсіммен салыстырыңыз → айырма қалса, оны Qut Pay-ден тыс өткен төлемдерден іздеңіз.

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

**Тізімде тиын неге жоқ?** QR счётта сома ең көбі екі ондық болады, телефонға жіберілетін счёт бүтін теңгемен жүреді. Сондықтан кейбір жолдарда ондық бөлік болмайды.

**Бір сұрауда бүкіл жылды алуға бола ма?** Жоқ, бір сұрауда ең көбі 200 жазба. `offset` арқылы беттеп алыңыз немесе кезеңді айларға бөліңіз.

**Тізімде клиенттің қосымша деректері бола ма?** Тек счёт жасағанда өзіңіз берген деректер. Біз клиент туралы бөлек ақпарат жинамаймыз.

**Есеп бұрынғыдан аз жол қайтарды.** Күйлер өзгерген болуы мүмкін (мысалы қайтару жасалған), бірақ жолдың өзі жоғалмайды. Күй сүзгісін алып тастап қайта қараңыз.

**Sandbox счёттары тарифтік лимитке кіре ме?** Жоқ, кірмейді және есепке де кірмеуі керек.