# Выставление счетов Kaspi из 1С

> Как выставлять Kaspi QR-счета прямо из документа 1С: подключение через HTTP-сервис, массовая отправка, опрос статуса или приём вебхука, сопоставление по externalOrderId и возвраты.

## Коротко

Чтобы выставлять счета из 1С, в конфигурацию добавляется шаг, который отправляет HTTP-запрос: при проведении документа 1С вызывает `POST /api/v1/invoices`, получает из ответа `payUrl` и `qrImageUrl` и подставляет их в печатную форму или в сообщение клиенту. Узнать об оплате можно двумя способами: принимать вебхук или самому опрашивать статус. Документ сопоставляется по `externalOrderId`. Инструкция: [api.qut.kz/docs/guide/1c](https://api.qut.kz/docs/guide/1c).

## Сценарий

Бухгалтер или менеджер создаёт в 1С документ «Счёт покупателю». Раньше этот счёт отправляли в PDF, клиент делал перевод из банка, деньги приходили через пару дней, потом кто-то сверял руками.

После подключения: в момент проведения документа появляется Kaspi QR, клиент платит с телефона одним сканированием, деньги приходят напрямую на Kaspi-счёт организации, документ в 1С помечается оплаченным.

## Схема работы по шагам

1. **Настройка.** В информационную базу добавляются константы: адрес API `https://api.qut.kz/api/v1`, API-ключ, режим (песочница/боевой).
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"`, счёт придёт push-уведомлением в приложение Kaspi.
6. **Узнать статус.** Принимаете вебхук или регламентным заданием опрашиваете `GET /invoices/{id}`.
7. **Закрытие документа.** При статусе `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 счетов за один запрос.

Важно: **каждый элемент проверяется отдельно**. Если в одном неверная сумма или сломан формат телефона, остальные создадутся, а этот вернёт ошибку. Сопоставьте каждую строку ответа со своим элементом, запишите проблемные в журнал, поправьте и отправьте повторно. Подробнее: [Массовое создание счетов](/kb/ru/bulk-invoices).

## Вебхук или опрос статуса

| Способ | Когда лучше | Что нужно |
|---|---|---|
| Вебхук | Когда об оплате надо узнать сразу | Доступный извне HTTP-сервис 1С, `https`, реальный домен |
| Опрос статуса | Когда 1С стоит во внутренней сети и наружу не смотрит | Регламентное задание, обход открытых счетов |

Во многих организациях 1С недоступна из внешней сети — тогда опрос остаётся единственным вариантом. Опрашивайте только открытые счета (`new`, `pending`), раз в минуту достаточно. На практике статус обновляется в течение нескольких секунд после оплаты.

Можно вести оба способа сразу: вебхук как основной, регламентное задание как страховка. Подробнее: [Вебхук или опрос статуса: что когда](/kb/ru/polling-vs-webhook).

## Сопоставление номенклатуры и документа

В поле `externalOrderId` запишите номер документа 1С — он вернётся и в вебхуке, и в списке, и в выгрузке. Через это поле вопрос «к какому счёту относится платёж» решается одним поиском.

`metadata` — произвольный JSON. Туда складывайте всё остальное: код контрагента, договор, подразделение, менеджера, состав номенклатуры. Это поле не для расчётов, а для сопоставления и отчётности.

Если нужно показать номенклатуру построчно, напишите её кратко в `description`, а полный состав храните в `metadata`: `description` ограничен — 100 символов у QR-счёта и 60 у счёта на телефон.

## Возвраты

Когда нужно вернуть деньги, из 1С вызывается `POST /invoices/{id}/refund` с телом `{ amount?, reason? }`. Без `amount` возврат полный, с `amount` — частичный.

Чтобы не вернуть дважды: если ответ неизвестен (оборвалась сеть, таймаут), не повторяйте сразу — сначала прочитайте список возвратов через `GET /invoices/{id}`. Подробнее: [API возвратов](/kb/ru/refunds-api).

## Прогон в песочнице

Прежде чем выходить на реальные деньги, прогоните весь цикл на ключе песочницы (`qp_test_…`):

1. Создаёте тестовый ключ и прописываете его в константу 1С.
2. Выставляете счёт из документа — реальный Kaspi не вызывается.
3. Через `POST /invoices/{id}/simulate` сами ставите оплату, отмену, истечение срока.
4. Проверяете реакцию 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`, либо используется наш механизм подписок. Подписка — это автоматическое выставление счёта по расписанию; деньги со счёта клиента сами не списываются, каждую оплату клиент подтверждает сам.