Қысқаша
Счёттардың тізімін екі жолмен аласыз: кабинеттегі Счёттар бөлімінен (сүзгі қойып, көрініп тұрған тізімді шығарасыз) және 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 қадамымен келесі беттерді алыңыз.
Мысалы, тамыз айының счёттарын алу:
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 кілтті кассирге байлау.
Бағандар нені білдіреді
Бағандар счёттың өрістеріне сай келеді.
| Баған | Мағынасы |
|---|---|
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 оны екі рет шерту арқылы ашқанда өз компьютеріңіздің ескі кодтауымен оқуға тырысады — сол себепті әріптердің орнына иероглиф шығады. Файлдың өзінде ешқандай ақау жоқ.
Дұрыс ашу реті:
- Excel-де бос кітап ашыңыз;
- Данные → Получить данные → Из текста/CSV;
- файлды таңдаңыз;
- Кодировка файла (File Origin) өрісін 65001: Юникод (UTF-8) етіңіз;
- бөлгішті тексеріп, Загрузить басыңыз.
Сол терезеде телефон мен тапсырыс нөмірінің бағанын Текст типіне қойыңыз — әйтпесе Excel ұзын сандарды 7,7051E+10 түріне айналдырады немесе басындағы нөлді жоғалтады.
Ең оңай жол — файлды Google Sheets немесе LibreOffice Calc арқылы ашу: екеуі де UTF-8-ті өзі таниды. Толығырақ шешімдер: Экспорт ашылмайды немесе дұрыс емес.
Бухгалтерияға беру
- Кезеңді күнтізбелік айға қойыңыз, уақыт белдеуі — Алматы.
- Нақты режимде екеніңізді тексеріңіз. Sandbox жолдары есепке кірмеуі керек.
- Файлды XLSX етіп сақтап беріңіз — бухгалтердің компьютерінде иероглиф қайталанбас үшін.
- Ақша Kaspi шотына тікелей түсетінін ескертіңіз. Бұл тізім — счёттар, ал банк үзіндісі — ақша қозғалысы: Ақша қашан және қайда түседі.
Бірнеше ұйым жүргізсеңіз, әр ұйымның есебі бөлек: Бір аккаунтта бірнеше ұйым.
Kaspi Pay есебімен салыстыру
Біздің тізім мен Kaspi Pay кабинетіндегі есеп бір нәрсе туралы емес. Біздікі — біз шығарған счёттар, Kaspi-дікі — сіздің шотыңыздағы қозғалыс. Сондықтан сандар дәл сәйкес келмеуі қалыпты. Себептері:
| Себебі | Түсіндірмесі |
|---|---|
| Kaspi өз ұстап қалатын сомасын өзі анықтайды | Kaspi есебінде түскен сома біздегі счёт сомасынан аз болуы мүмкін |
| Qut Pay-ден тыс төлемдер | Қолма-қол ақша, POS, Kaspi қосымшасынан қолмен шығарылған счёт — Kaspi-де бар, бізде жоқ |
| Кеш келген төлемдер | Счёт жабылған соң ақша кейін келуі мүмкін: Кеш келген төлем |
| Қайтарулар | Қайтару Kaspi үзіндісінде бөлек жолмен өтеді, бізде счёттың ішінде көрінеді |
| Кезеңнің шекарасы | Түн ортасында жасалған счёт бір күні, төленуі келесі күні болуы мүмкін |
| Sandbox жолдары | Kaspi-де мүлде жоқ |
| Бірнеше кассир | Кілт бір кассирге байланған болса, тізімде тек соның счёттары |
Сверканы дұрыс жүргізу реті: кезеңді екі жерде де бірдей қойыңыз → біздің тізімнен тек paid, refunded, partially_refunded күйлерін алыңыз → қайтарылған сомаларды шегеріңіз → Kaspi үзіндісіндегі осы кезеңдегі түсіммен салыстырыңыз → айырма қалса, оны Qut Pay-ден тыс өткен төлемдерден іздеңіз.
Жиі қойылатын сұрақтар
Тізімде тиын неге жоқ? QR счётта сома ең көбі екі ондық болады, телефонға жіберілетін счёт бүтін теңгемен жүреді. Сондықтан кейбір жолдарда ондық бөлік болмайды.
Бір сұрауда бүкіл жылды алуға бола ма? Жоқ, бір сұрауда ең көбі 200 жазба. offset арқылы беттеп алыңыз немесе кезеңді айларға бөліңіз.
Тізімде клиенттің қосымша деректері бола ма? Тек счёт жасағанда өзіңіз берген деректер. Біз клиент туралы бөлек ақпарат жинамаймыз.
Есеп бұрынғыдан аз жол қайтарды. Күйлер өзгерген болуы мүмкін (мысалы қайтару жасалған), бірақ жолдың өзі жоғалмайды. Күй сүзгісін алып тастап қайта қараңыз.
Sandbox счёттары тарифтік лимитке кіре ме? Жоқ, кірмейді және есепке де кірмеуі керек.