Kaspi и 1С: как выставлять счета Kaspi из 1С
Связать Kaspi и 1С через Qut Pay можно обычным HTTP-запросом из конфигурации: при проведении документа, например «Счёт покупателю», 1С вызывает POST /api/v1/invoices, получает в ответ ссылку на оплату payUrl и картинку QR qrImageUrl и подставляет их в печатную форму или сообщение клиенту. Об оплате 1С узнаёт вебхуком или регламентным заданием, которое опрашивает статус, а документ находится по externalOrderId. Готового расширения или обработки для 1С нет: есть инструкция с примерами кода, которые программист 1С встраивает в вашу конфигурацию.
Qut Pay работает через роль «Кассир» в вашем собственном Kaspi Pay, деньги поступают напрямую на Kaspi-счёт организации. Нужен бизнес-аккаунт Kaspi Pay (ИП или ТОО) и подключённый кассир — как подключить.
Что есть и чего нет
| Есть | Нет |
|---|---|
| REST API: создание счёта, статус, список, отмена, возврат, массовое создание | Готового расширения или обработки под конкретную конфигурацию |
| Инструкция для 1С: общий модуль на встроенном языке, приём вебхука через HTTP-сервис с проверкой подписи, регламентное задание для опроса статуса, возвраты, проверка в песочнице | Установки «в один клик»: код нужно встроить в свою конфигурацию |
| Песочница: счета без реальных денег и без обращения к Kaspi | Фискального чека от Qut Pay: он определяется правилами Kaspi и ОФД и решается на стороне 1С |
Примеры в инструкции рассчитаны на платформу 8.3.10 и новее и обходятся без внешних компонент и БСП. Код написан по документации платформы, и в конце инструкции перечислены места, которые нужно сверить с синтакс-помощником вашей версии. Поэтому сначала прогоните его на копии базы с ключом песочницы.
Как это работает
- Настройка. В базу добавляются константы: адрес API
https://api.qut.kz/api/v1, API-ключ, режим (песочница или боевой). - Кнопка в документе. «Выставить счёт Kaspi» или автоматический вызов при проведении.
- Запрос. Через
HTTPСоединение1С отправляет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 клиента. - Статус. Вебхук на HTTP-сервис 1С или регламентное задание, которое опрашивает
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 и интеграция с сайтом.
Вебхук или опрос статуса
| Способ | Когда лучше | Что нужно |
|---|---|---|
| Вебхук | Об оплате надо узнать сразу | HTTP-сервис 1С, доступный извне, https, настоящий домен |
| Опрос статуса | 1С стоит во внутренней сети и наружу не смотрит | Регламентное задание, которое обходит открытые счета |
Во многих организациях 1С недоступна из внешней сети — тогда опрос остаётся единственным вариантом. Опрашивайте только открытые счета (new, pending), раз в минуту достаточно: на практике статус обновляется в течение нескольких секунд после оплаты. Можно вести оба способа сразу: вебхук как основной, регламентное задание как страховка.
Каждый вебхук подписан: X-Webhook-Signature = sha256= + HMAC-SHA256 от секрета и строки timestamp + "." + тело запроса. Встроенного HMAC в 1С нет, но в инструкции есть его реализация через ХешированиеДанных (SHA-256) и самопроверка по тестовому вектору RFC 4231. Qut Pay отправляет вебхук без логина и пароля, поэтому для него делают отдельную публикацию HTTP-сервиса — как именно, тоже описано в инструкции. Подробнее: вебхук или опрос статуса, безопасность вебхуков.
Сопоставление с документом и номенклатура
В поле externalOrderId запишите номер документа 1С — он вернётся и в вебхуке, и в списке, и в выгрузке. Вопрос «к какому счёту относится платёж» решается одним поиском.
metadata — произвольный JSON: код контрагента, договор, подразделение, менеджер, состав номенклатуры. Это поле не для расчётов, а для сопоставления и отчётности; покупатель его не видит. Номенклатуру построчно коротко пишите в description, а полный состав храните в metadata: description ограничен — 100 символов у QR-счёта и 60 у счёта на телефон. Metadata и номер заказа.
Массовая отправка
Если раз в месяц вы выставляете счета группе контрагентов — аренда, абонемент, обслуживание, — отдельный запрос на каждого не нужен: POST /api/v1/invoices/bulk принимает от 1 до 100 счетов за запрос. Каждый элемент проверяется отдельно: если в одном неверная сумма или сломан телефон, остальные создадутся, а этот вернёт ошибку. Сопоставьте каждую строку ответа со своим элементом, запишите проблемные в журнал, поправьте и отправьте повторно. Массовое создание счетов.
Возвраты
Чтобы вернуть деньги, 1С вызывает POST /invoices/{id}/refund с телом { amount?, reason? }: без amount возврат полный, с amount — частичный. Ключу нужно право refunds:write. Чтобы не вернуть дважды: если ответ неизвестен (оборвалась сеть, тайм-аут), не повторяйте сразу — сначала прочитайте список возвратов через GET /invoices/{id}. API возвратов.
Прогон в песочнице
Прежде чем выходить на реальные деньги, прогоните весь цикл на ключе песочницы (qp_test_…):
- Создайте тестовый ключ и пропишите его в константу 1С.
- Выставьте счёт из документа — реальный Kaspi не вызывается.
- Через
POST /invoices/{id}/simulateсами поставьте оплату, отмену или истечение срока. - Проверьте реакцию 1С: закрывается ли документ, обрабатывается ли вебхук, не появляются ли дубли.
Счета из песочницы не входят в месячный лимит и не запускают пробный период.
Особые замечания
- Сумма. У QR-счёта не более двух знаков после запятой, у счёта на телефон — целые тенге. Округляйте перед отправкой из 1С.
- Телефон — в формате
7XXXXXXXXXX. В 1С номера контрагентов часто записаны по-разному, приводите их к одному виду перед отправкой; функция нормализации есть в инструкции. - Ключ на сервере. API-ключ хранится на серверной стороне, а не в клиентском приложении. В файловой базе продумайте, у кого есть доступ к ключу.
- Идемпотентность. Чтобы повторное проведение документа не создало дубль, передавайте
Idempotency-Key, собранный из номера документа и суммы. - Поздняя оплата. Если деньги придут по просроченному счёту,
invoice.paidпридёт с признакомlate: true. Предусмотрите в 1С обработку этого случая. - Фискальный чек определяется правилами Kaspi и ОФД и решается на стороне 1С.
Частые вопросы
Есть ли готовый модуль или обработка Kaspi для 1С?
Нет. Готового расширения под конкретную конфигурацию мы не распространяем. Есть инструкция с примерами HTTP-запросов, кодом общего модуля, HTTP-сервиса для вебхука и регламентного задания — программист 1С встраивает их в вашу конфигурацию.
Для каких конфигураций подходит?
Для любой, которая умеет отправлять HTTP-запрос: Бухгалтерия, УТ, УНФ, самописная. Требование — доступность HTTPСоединение. Примеры в инструкции рассчитаны на платформу 8.3.10 и новее.
1С закрыта извне, вебхук принять не могу. Что делать?
Используйте опрос статуса: регламентное задание обходит открытые счета. Либо поставьте промежуточный слой — n8n или собственный сервис, — который примет вебхук и доставит его в 1С удобным способом.
Сколько счетов можно отправить одним запросом?
В методе bulk — от 1 до 100. Больше разбивайте на пакеты.
Можно ли выставлять ежемесячные счета автоматически?
Да, двумя путями: регламентное задание в 1С отправляет их через bulk, либо используются подписки Qut Pay. Подписка — это автоматическое выставление счёта по расписанию; деньги со счёта клиента сами не уходят, каждую оплату клиент подтверждает в Kaspi сам.
Сколько это стоит?
Qut Pay — подписка без процента с платежей: «Бесплатный» тариф — 20 оплат в месяц, «Старт» — 4 990 ₸ в месяц за 800 оплат; API, вебхуки и возвраты есть на любом тарифе. Комиссию Kaspi удерживает сам Kaspi по своим условиям. Встраивание в конфигурацию — работа вашего программиста 1С. Подробнее: тарифы.
Ещё по теме: Kaspi Pay API для сайта, счёт Kaspi по номеру телефона, оплата Kaspi в Telegram и WhatsApp, сравнение сервисов для приёма Kaspi.
Подключите Kaspi к 1С
Зарегистрируйтесь, создайте тестовый ключ и прогоните цикл из 1С в песочнице.
Qut Pay — независимый сервис, не партнёр Kaspi и не аффилирован с АО «Kaspi Bank». Сервис работает через роль «Кассир» в вашем Kaspi Pay, деньги поступают напрямую на ваш счёт Kaspi Pay. Смотрите также: счёт Kaspi по номеру телефона, Kaspi API для сайта, статья о 1С в базе знаний, тарифы, центр доверия.