1С-тен Kaspi счёттарын шығару

Қысқаша

1С-тен счёт шығару үшін конфигурацияға HTTP-сервис арқылы сұрау жіберетін қадам қосылады: сатушы құжатты өткізгенде 1С бізге POST /api/v1/invoices жібереді, жауаптан payUrl мен qrImageUrl алады да, оларды құжаттың баспа пішініне немесе клиентке жіберетін хабарламаға қояды. Төлем түскенін екі жолмен білуге болады: webhook қабылдау немесе күйді өзіңіз сұрау. Құжатты externalOrderId арқылы сәйкестендіресіз. Нұсқаулық: api.qut.kz/docs/guide/1c.

Сценарий

Бухгалтер немесе сатушы 1С-те «Сатып алушыға шот» құжатын жасайды. Бұрын ол шотты PDF қылып жіберетін, клиент банктен аударым жасайтын, ақша екі күннен кейін түсетін, содан кейін біреу қолмен салыстыратын.

Қосылғаннан кейін: құжат өткізілген сәтте Kaspi QR пайда болады, клиент телефонынан бір сканерлеумен төлейді, ақша тіке ұйымның Kaspi шотына түседі, 1С-тегі құжат «төленді» деп белгіленеді.

Жұмыс схемасы қадамдап

1. Баптау. Ақпараттық базаға тұрақтылар қосасыз: API адресі https://api.qut.kz/api/v1, API кілт, режим (sandbox/live).
2. Құжатқа батырма. «Kaspi счётын шығару» деген батырма немесе өткізу кезінде автоматты шақыру.
3. Сұрау жіберу. HTTPСоединение арқылы POST /invoices. Тақырыптар: X-API-Key, Content-Type: application/json, Idempotency-Key. Денесінде amount, description, externalOrderId (құжат нөмірі), customer.phone, metadata.
4. Жауапты сақтау. Құжатқа қосымша реквизиттер қосасыз: invoiceId, payUrl, qrImageUrl, expiresAt, күйі.
5. Клиентке жеткізу. QR суретін баспа пішініне саласыз немесе сілтемені SMS/WhatsApp арқылы жібересіз. kind: "phone" таңдасаңыз, счёт клиенттің Kaspi қосымшасына push болып барады.
6. Күйін білу. Webhook қабылдайсыз немесе регламенттік тапсырма арқылы GET /invoices/{id} сұрайсыз.
7. Құжатты жабу. Күйі paid болғанда 1С-те төлем құжатын жасайсыз, шотты жабасыз.

Қандай API әдісі керек

Топтап жіберу

Ай сайын бір топ контрагентке шот шығаратын болсаңыз (жалдау, абонемент, қызмет көрсету), әрқайсысына бөлек сұрау жіберудің қажеті жоқ. POST /api/v1/invoices/bulk бір сұрауда 1-ден 100-ге дейін счёт қабылдайды.

Маңыздысы: әр элемент бөлек тексеріледі. Біреуінде сома дұрыс емес немесе телефон пішімі бұзылған болса, қалғаны жасалады, ал сол біреуі қате қайтарады. Жауаптағы әр жолды өз элементіңізбен салыстырып, қатесі барларын журналға жазыңыз да, түзеп қайта жіберіңіз. Толығы: Топтап счёт жасау.

Webhook па, әлде күйді сұрау ма

Көп ұйымда 1С сыртқы желіден қолжетімсіз — ондайда күйді сұрау жалғыз нұсқа. Ашық счёттарды (new, pending) ғана сұраңыз, әр минут сайын жеткілікті. Іс жүзінде клиент төлегеннен кейін счёт күйі бірнеше секундта жаңарады.

Екеуін қатар жүргізуге де болады: webhook негізгі жол, регламенттік тапсырма — сақтандырғыш. Толығы: Webhook пен күйді сұрау: қайсысы қашан.

Номенклатураны және құжатты сәйкестендіру

externalOrderId өрісіне 1С-тегі құжат нөмірін жазыңыз — ол webhook-та да, тізімде де, экспортта да қайта келеді. Осы өріс арқылы «бұл төлем қай шотқа» деген сұрақ бір іздеуде шешіледі.

metadata — кез келген JSON. Онда қосымшаны сақтауға болады: контрагент коды, келісімшарт, бөлім, менеджер, номенклатура жолдарының тізімі. Бұл өріс есептеу үшін емес, сәйкестендіру мен есеп үшін.

Егер номенклатураны жолма-жол көрсету керек болса, оны description мәтініне қысқаша жазып, толық құрамын metadata ішінде сақтаңыз: description шектеулі — QR счётта 100 таңба, телефонға счётта 60.

Қайтару

Клиенттен ақша қайтару керек болса, 1С-тен POST /invoices/{id}/refund шақырасыз: { amount?, reason? }. amount бермесеңіз толық қайтарылады, берсеңіз ішінара.

Екі рет қайтарып жібермеу үшін: жауабы белгісіз болса (желі үзілді, таймаут), бірден қайталамаңыз — алдымен GET /invoices/{id} арқылы қайтарулар тізімін оқыңыз. Толығы: Қайтару API.

Sandbox-та алдын ала өткізу

Нақты ақшаға шықпас бұрын бүкіл циклді sandbox кілтімен (qp_test_…) өткізіңіз:

1. Тест кілтін жасап, 1С-тің тұрақтысына қоясыз.
2. Құжаттан счёт шығарасыз — нақты Kaspi шақырылмайды.
3. POST /invoices/{id}/simulate арқылы төлемді, болдырмауды, мерзімі өтуді өзіңіз қоясыз.
4. 1С дұрыс реакция бергенін тексересіз: құжат жабыла ма, webhook өңделе ме, дубль шыға ма.

Sandbox счёттары айлық лимитке кірмейді және сынақ мерзімін бастамайды.

Ерекше ескертулер

• Сома. QR счётта ең көбі екі ондық белгі, телефонға счётта бүтін теңге. 1С-тен жіберер алдында дөңгелектеңіз.
• Телефон пішімі — 7XXXXXXXXXX. 1С-тегі контрагент нөмірлері әртүрлі жазылған болуы мүмкін, жіберер алдында тазалаңыз.
• Кілт серверде. API кілт клиенттік қосымшада емес, сервер жағында сақталсын. Файлдық базада жұмыс істесеңіз, кілтке қол жеткізе алатын адамдар шеңберін ойлаңыз.
• Идемпоттылық. Құжат қайта өткізілсе дубль шықпауы үшін Idempotency-Key тақырыбын беріңіз, мәні құжат нөмірі мен сомадан құралсын.
• Кеш төлем. Мерзімі өткен счётқа ақша кейін келсе, invoice.paid оқиғасы late: true белгісімен келеді. 1С-те ондай жағдайды өңдейтін тармақ болсын.
• Фискалды чек — бөлек мәселе, Kaspi мен ОФД ережелеріне қарайды, оны 1С жағында шешесіз.

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

Дайын өңдеу (обработка) бар ма? Жеке конфигурацияға арналған дайын кеңейту таратпаймыз. Нұсқаулықта HTTP-сұрау мысалдары мен жауап құрылымы берілген, оны өз конфигурацияңызға қосасыз.

Қай конфигурацияларға жарайды? HTTP сұрау жібере алатын кез келгеніне: Бухгалтерия, УТ, УНФ, өз конфигурацияңыз. Талап — HTTPСоединение қолдана алу.

1С сыртқы желіден жабық, webhook қабылдай алмаймын. Не істеймін? Күйді сұрау режимін қолданыңыз: регламенттік тапсырма ашық счёттарды айналып тексереді. Немесе аралық қабат (n8n, өз сервисіңіз) webhook қабылдап, 1С-ке ыңғайлы жолмен жеткізеді.

Бір сұрауда неше счёт жіберуге болады? bulk әдісінде 1-ден 100-ге дейін. Одан көп болса бірнеше пакетке бөліңіз.

Ай сайынғы шоттарды өзі шығаратын етіп қоюға бола ма? Иә, екі жолы бар: 1С-тегі регламенттік тапсырма bulk арқылы жіберсін, немесе біздің жазылым механизмін қолданыңыз. Жазылым — счётты кестеге сай автоматты шығару; ақша клиенттің шотынан өздігінен шешілмейді, әр төлемді клиент өзі растайды.