Коротко
Чтобы выставлять счета из 1С, в конфигурацию добавляется шаг, который отправляет HTTP-запрос: при проведении документа 1С вызывает POST /api/v1/invoices, получает из ответа payUrl и qrImageUrl и подставляет их в печатную форму или в сообщение клиенту. Узнать об оплате можно двумя способами: принимать вебхук или самому опрашивать статус. Документ сопоставляется по externalOrderId. Инструкция: api.qut.kz/docs/guide/1c.
Сценарий
Бухгалтер или менеджер создаёт в 1С документ «Счёт покупателю». Раньше этот счёт отправляли в PDF, клиент делал перевод из банка, деньги приходили через пару дней, потом кто-то сверял руками.
После подключения: в момент проведения документа появляется Kaspi QR, клиент платит с телефона одним сканированием, деньги приходят напрямую на Kaspi-счёт организации, документ в 1С помечается оплаченным.
Схема работы по шагам
- Настройка. В информационную базу добавляются константы: адрес API
https://api.qut.kz/api/v1, API-ключ, режим (песочница/боевой). - Кнопка в документе. «Выставить счёт Kaspi» или автоматический вызов при проведении.
- Отправка запроса. Через
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", счёт придёт push-уведомлением в приложение Kaspi. - Узнать статус. Принимаете вебхук или регламентным заданием опрашиваете
GET /invoices/{id}. - Закрытие документа. При статусе
paidв 1С создаётся документ оплаты, счёт закрывается.
Какие методы 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 |
Массовая отправка
Если вы раз в месяц выставляете счета группе контрагентов (аренда, абонемент, обслуживание), отправлять отдельный запрос на каждого не нужно. POST /api/v1/invoices/bulk принимает от 1 до 100 счетов за один запрос.
Важно: каждый элемент проверяется отдельно. Если в одном неверная сумма или сломан формат телефона, остальные создадутся, а этот вернёт ошибку. Сопоставьте каждую строку ответа со своим элементом, запишите проблемные в журнал, поправьте и отправьте повторно. Подробнее: Массовое создание счетов.
Вебхук или опрос статуса
| Способ | Когда лучше | Что нужно |
|---|---|---|
| Вебхук | Когда об оплате надо узнать сразу | Доступный извне HTTP-сервис 1С, https, реальный домен |
| Опрос статуса | Когда 1С стоит во внутренней сети и наружу не смотрит | Регламентное задание, обход открытых счетов |
Во многих организациях 1С недоступна из внешней сети — тогда опрос остаётся единственным вариантом. Опрашивайте только открытые счета (new, pending), раз в минуту достаточно. На практике статус обновляется в течение нескольких секунд после оплаты.
Можно вести оба способа сразу: вебхук как основной, регламентное задание как страховка. Подробнее: Вебхук или опрос статуса: что когда.
Сопоставление номенклатуры и документа
В поле externalOrderId запишите номер документа 1С — он вернётся и в вебхуке, и в списке, и в выгрузке. Через это поле вопрос «к какому счёту относится платёж» решается одним поиском.
metadata — произвольный JSON. Туда складывайте всё остальное: код контрагента, договор, подразделение, менеджера, состав номенклатуры. Это поле не для расчётов, а для сопоставления и отчётности.
Если нужно показать номенклатуру построчно, напишите её кратко в description, а полный состав храните в metadata: description ограничен — 100 символов у QR-счёта и 60 у счёта на телефон.
Возвраты
Когда нужно вернуть деньги, из 1С вызывается POST /invoices/{id}/refund с телом { amount?, reason? }. Без amount возврат полный, с amount — частичный.
Чтобы не вернуть дважды: если ответ неизвестен (оборвалась сеть, таймаут), не повторяйте сразу — сначала прочитайте список возвратов через 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С.
Вопросы и ответы
Есть ли готовая обработка? Готового расширения под конкретную конфигурацию мы не распространяем. В инструкции даны примеры HTTP-запросов и структура ответа — их вы встраиваете в свою конфигурацию.
Для каких конфигураций подходит? Для любой, которая умеет отправлять HTTP-запрос: Бухгалтерия, УТ, УНФ, самописная. Требование — доступность HTTPСоединение.
1С закрыта извне, принять вебхук не могу. Что делать? Используйте режим опроса: регламентное задание обходит открытые счета. Либо поставьте промежуточный слой (n8n, собственный сервис), который примет вебхук и доставит его в 1С удобным способом.
Сколько счетов можно отправить одним запросом? В методе bulk — от 1 до 100. Больше разбивайте на пакеты.
Можно ли выставлять ежемесячные счета автоматически? Да, два пути: регламентное задание в 1С отправляет их через bulk, либо используется наш механизм подписок. Подписка — это автоматическое выставление счёта по расписанию; деньги со счёта клиента сами не списываются, каждую оплату клиент подтверждает сам.