Kaspi және 1С: 1С-тен Kaspi шотын қалай шығару керек
Kaspi мен 1С-ті Qut Pay арқылы конфигурациядан жіберілетін кәдімгі HTTP сұраныспен байланыстырасыз: құжатты, мысалы «Сатып алушыға шот» құжатын өткізгенде 1С POST /api/v1/invoices шақырады, жауаптан payUrl төлем сілтемесі мен qrImageUrl QR суретін алып, оларды баспа пішініне не клиентке жіберетін хабарламаға қояды. Төлем түскенін 1С webhook арқылы не күйді сұрайтын регламенттік тапсырма арқылы біледі, ал құжатты externalOrderId бойынша табады. 1С-ке арналған дайын кеңейту не өңдеу (обработка) жоқ: код мысалдары бар нұсқаулық бар (орысша), оны 1С бағдарламашысы сіздің конфигурацияңызға қосады.
Qut Pay сіздің өз Kaspi Pay-іңіздегі «Кассир» рөлі арқылы жұмыс істейді, ақша тікелей ұйымның Kaspi Pay шотына түседі. Kaspi Pay бизнес-аккаунты (ЖК не ЖШС) және қосылған кассир керек — қалай қосу керек.
Не бар, не жоқ
| Бар | Жоқ |
|---|---|
| REST API: шот жасау, күйі, тізім, болдырмау, қайтару, топтап жасау | Белгілі бір конфигурацияға арналған дайын кеңейту не өңдеу |
| 1С нұсқаулығы: кірістірілген тілдегі жалпы модуль, қолтаңбасын тексеріп webhook қабылдайтын HTTP-сервис, күйді сұрайтын регламенттік тапсырма, қайтару, sandbox-та тексеру | «Бір басумен» орнату: кодты өз конфигурацияңызға қосу керек |
| Sandbox: нақты ақшасыз, Kaspi-ге жүгінбейтін шоттар | Qut Pay-ден фискалды чек: ол Kaspi мен ОФД ережесіне қарайды, оны 1С жағында шешесіз |
Нұсқаулықтағы мысалдар 8.3.10 және одан жаңа платформаға арналған, сыртқы компонентсіз және БСП-сыз жазылған. Код платформа құжаттамасы бойынша жазылған, ал нұсқаулықтың соңында өз нұсқаңыздың синтакс-помощнигімен салыстыратын жерлер тізіліп берілген. Сондықтан алдымен оны базаның көшірмесінде sandbox кілтімен өткізіп көріңіз.
Қалай жұмыс істейді
- Баптау. Базаға тұрақтылар қосасыз: API адресі
https://api.qut.kz/api/v1, API кілт, режим (sandbox не live). - Құжаттағы батырма. «Kaspi шотын шығару» батырмасы не құжатты өткізгенде автоматты шақыру.
- Сұраныс. 1С
HTTPСоединениеарқылыPOST /invoicesжібереді, тақырыптары:X-API-Key,Content-Type: application/json,Idempotency-Key. Денесінде —amount,description,externalOrderId(құжат нөмірі),customer.phone,metadata. - Жауап. Құжаттың қосымша реквизиттеріне
invoiceId,payUrl,qrImageUrl,expiresAtжәне күйі жазылады. - Клиентке. QR суреті — баспа пішініне, сілтеме — SMS не WhatsApp-қа.
kind: "phone"болса, шот клиенттің Kaspi қосымшасына хабарлама болып барады. - Күйі. 1С HTTP-сервисіне келетін webhook не
GET /invoices/{id}сұрайтын регламенттік тапсырма. - Жабу. Күйі
paidболғанда 1С-те төлем құжаты жасалып, шот жабылады.
1С жіберетін сұраныстың өзі:
POST https://api.qut.kz/api/v1/invoices
X-API-Key: qp_live_…
Content-Type: application/json
Idempotency-Key: 1c-00142
{ "amount": 148000, "kind": "qr", "description": "№ 00142 шот бойынша төлем",
"externalOrderId": "00142", "metadata": { "source": "1c" } }
Нұсқаулықта ол жалпы модульдің функциясына оралған, ал тасымалы — платформаның стандартты объектілері:
Соединение = Новый HTTPСоединение("api.qut.kz", 443, , , , 30, Новый OpenSSLЗащищенноеСоединение());
Запрос = Новый HTTPЗапрос("/api/v1/invoices", Заголовки);
Запрос.УстановитьТелоИзСтроки(ТелоJSON, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
Ответ = Соединение.ОтправитьДляОбработки(Запрос);
Қандай API әдісі керек
| Не істейді | Әдіс |
|---|---|
| Бір құжаттан шот | POST /api/v1/invoices |
| Тізім бойынша топтап | POST /api/v1/invoices/bulk, 1–100 элемент |
| Бір шоттың күйі мен оқиғалары | GET /api/v1/invoices/{id} |
| Кезең бойынша тізім | GET /api/v1/invoices |
| Болдырмау | POST /api/v1/invoices/{id}/cancel |
| Қайтару | POST /api/v1/invoices/{id}/refund |
| Қызмет күйі (мониторингке) | GET /api/v1/status |
Толық сипаттама: OpenAPI және сайтқа интеграция.
Webhook па, күйді сұрау ма
| Жол | Қашан жақсы | Не керек |
|---|---|---|
| Webhook | Төлемді бірден білу керек болса | 1С-тің сырттан ашық HTTP-сервисі, https, нақты домен |
| Күйді сұрау | 1С ішкі желіде тұрып, сыртқа ашылмаса | Ашық шоттарды айналып шығатын регламенттік тапсырма |
Көп ұйымда 1С-ке сыртқы желіден кіру мүмкін емес — ондайда күйді сұрау жалғыз жол болып қалады. Тек ашық шоттарды (new, pending) сұраңыз, минутына бір рет жеткілікті: іс жүзінде клиент төлегеннен кейін күйі бірнеше секундта жаңарады. Екеуін қатар ұстауға да болады: webhook — негізгі жол, регламенттік тапсырма — сақтандырғыш.
Әр webhook қолтаңбамен келеді: X-Webhook-Signature = sha256= + құпия кілт пен timestamp + "." + сұраныс денесі жолынан алынған HMAC-SHA256. 1С-те дайын HMAC жоқ, бірақ нұсқаулықта оның ХешированиеДанных (SHA-256) арқылы жазылған нұсқасы және RFC 4231 тест векторымен өзін-өзі тексеру бар. Qut Pay webhook-ты логин-парольсіз жібереді, сондықтан ол үшін HTTP-сервисті бөлек жариялайды — қалай жасалатыны да нұсқаулықта бар. Толығы: webhook па, күйді сұрау ма, webhook қауіпсіздігі.
Құжатпен және номенклатурамен сәйкестендіру
externalOrderId өрісіне 1С құжатының нөмірін жазыңыз — ол webhook-та да, тізімде де, экспортта да қайта келеді. «Бұл төлем қай шотқа» деген сұрақ бір іздеумен шешіледі.
metadata — кез келген JSON: контрагент коды, келісімшарт, бөлім, менеджер, номенклатура құрамы. Бұл өріс есептеу үшін емес, сәйкестендіру мен есеп үшін, оны клиент көрмейді. Номенклатураны жолма-жол көрсету керек болса, description-ға қысқаша жазып, толық құрамын metadata ішінде сақтаңыз: description шектеулі — QR шотта 100 таңба, телефонға шотта 60. Metadata және тапсырыс нөмірі.
Топтап жіберу
Ай сайын бір топ контрагентке шот шығарсаңыз — жалдау, абонемент, қызмет көрсету, — әрқайсысына бөлек сұраныс жіберудің қажеті жоқ: POST /api/v1/invoices/bulk бір сұраныста 1-ден 100-ге дейін шот қабылдайды. Әр элемент бөлек тексеріледі: біреуінде сома қате не телефон бұзық болса, қалғаны жасалады да, сол біреуі ғана қате қайтарады. Жауаптағы әр жолды өз элементіңізбен салыстырып, қателерін журналға жазыңыз, түзеп, қайта жіберіңіз. Топтап шот жасау.
Қайтару
Ақшаны қайтару үшін 1С POST /invoices/{id}/refund шақырады, денесі { amount?, reason? }: amount бермесеңіз — толық қайтару, берсеңіз — ішінара. Кілтте refunds:write құқығы болуы керек. Екі рет қайтарып жібермеу үшін: жауабы белгісіз болса (желі үзілді, таймаут), бірден қайталамаңыз — алдымен GET /invoices/{id} арқылы қайтарулар тізімін оқыңыз. Қайтару API.
Sandbox-та алдын ала өткізу
Нақты ақшаға шықпас бұрын бүкіл циклді sandbox кілтімен (qp_test_…) өткізіңіз:
- Тест кілтін жасап, 1С тұрақтысына жазыңыз.
- Құжаттан шот шығарыңыз — нақты Kaspi шақырылмайды.
POST /invoices/{id}/simulateарқылы төлемді, болдырмауды не мерзімнің өтуін өзіңіз қойыңыз.- 1С-тің реакциясын тексеріңіз: құжат жабыла ма, webhook өңделе ме, дубль шықпай ма.
Sandbox шоттары айлық лимитке кірмейді және сынақ мерзімін бастамайды.
Ерекше ескертулер
- Сома. QR шотта ең көбі екі ондық белгі, телефонға шотта бүтін теңге. 1С-тен жібермес бұрын дөңгелектеңіз.
- Телефон —
7XXXXXXXXXXпішімінде. 1С-тегі контрагент нөмірлері әртүрлі жазылуы мүмкін, жібермес бұрын бір түрге келтіріңіз; оған арналған функция нұсқаулықта бар. - Кілт серверде. API кілт клиенттік қосымшада емес, сервер жағында сақталады. Файлдық базада кілтке кімнің қолы жететінін ойластырыңыз.
- Идемпоттылық. Құжат қайта өткізілгенде дубль шықпауы үшін құжат нөмірі мен сомадан құралған
Idempotency-Keyберіңіз. - Кеш төлем. Мерзімі өткен шотқа ақша кейін келсе,
invoice.paidоқиғасыlate: trueбелгісімен келеді. 1С-те бұл жағдайды өңдейтін тармақ болсын. - Фискалды чек Kaspi мен ОФД ережесіне қарайды, оны 1С жағында шешесіз.
Жиі қойылатын сұрақтар
1С-ке арналған дайын Kaspi модулі не өңдеу бар ма?
Жоқ. Белгілі бір конфигурацияға арналған дайын кеңейтуді таратпаймыз. HTTP сұраныс мысалдары, жалпы модуль, webhook-қа арналған HTTP-сервис пен регламенттік тапсырма коды бар нұсқаулық бар — оларды 1С бағдарламашысы сіздің конфигурацияңызға қосады.
Қай конфигурацияларға жарайды?
HTTP сұраныс жібере алатын кез келгеніне: Бухгалтерия, УТ, УНФ, өз конфигурацияңыз. Талап — HTTPСоединение қолдана алу. Нұсқаулықтағы мысалдар 8.3.10 және одан жаңа платформаға арналған.
1С сырттан жабық, webhook қабылдай алмаймын. Не істеймін?
Күйді сұрау режимін қолданыңыз: регламенттік тапсырма ашық шоттарды айналып тексереді. Немесе аралық қабат қойыңыз — n8n не өз сервисіңіз, — ол webhook-ты қабылдап, 1С-ке ыңғайлы жолмен жеткізеді.
Бір сұраныста неше шот жіберуге болады?
bulk әдісінде 1-ден 100-ге дейін. Одан көп болса, бірнеше пакетке бөліңіз.
Ай сайынғы шоттарды өзі шығаратын етуге бола ма?
Иә, екі жолы бар: 1С-тегі регламенттік тапсырма оларды bulk арқылы жібереді, не Qut Pay жазылымын қолданасыз. Жазылым — шотты кесте бойынша автоматты шығару; ақша клиенттің шотынан өздігінен шешілмейді, әр төлемді клиент Kaspi-де өзі растайды.
Бұл қанша тұрады?
Qut Pay — төлемнен пайыз алмайтын жазылым: «Тегін» тариф — айына 20 төлем, «Бастау» — айына 4 990 ₸, 800 төлем; API, webhook және қайтару кез келген тарифте бар. Kaspi өз комиссиясын өз шартымен ұстайды. Конфигурацияға қосу — 1С бағдарламашыңыздың жұмысы. Толығырақ: тарифтер.
Тақырып бойынша тағы: Kaspi Pay API сайтқа, Kaspi шотын нөмірге жіберу, Telegram мен WhatsApp-та Kaspi төлем, Kaspi сервистерін салыстыру.
Kaspi-ді 1С-ке қосыңыз
Тіркеліп, тест кілтін жасаңыз да, 1С-тен бүкіл циклді sandbox-та өткізіп көріңіз.
Qut Pay — тәуелсіз сервис, Kaspi-дің серіктесі емес және «Kaspi Bank» АҚ-мен аффилирленбеген. Сервис сіздің Kaspi Pay-дегі «Кассир» рөлі арқылы жұмыс істейді, ақша тікелей Kaspi Pay шотыңызға түседі. Тағы қараңыз: Kaspi шотын нөмірге жіберу, сайтқа Kaspi API, білім базасындағы 1С туралы мақала, тарифтер, сенім орталығы.