> Источник: https://apipay.kz/n8n-integration · apipay.kz
> ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay. Не официальная интеграция Kaspi и не партнёр Kaspi.

# Интеграция ApiPay с n8n — автоматизация платежей Kaspi Pay без кода

**TL;DR.** Узел `n8n-nodes-apipay` ставится в n8n как community node и даёт 68 операций в 12 группах плюс триггер на 22 события вебхуков. Счета по номеру и по QR, печатные QR-листы, возвраты, возврат по ссылке, подписки, фискальные чеки, касса и смены, каталог — из визуального конструктора, без написания кода.

## Что нужно для работы

- Аккаунт ApiPay.kz с подключённым кассиром Kaspi Pay. Подключение проходит человек в кабинете: оно требует SMS-кода на телефон сотрудника, автоматизировать его нельзя.
- API-ключ из кабинета: Настройки → «Подключение».
- Секрет подписи вебхуков — там же, рядом с адресом уведомлений. Показывается один раз.
- n8n своей установки (self-hosted). На n8n Cloud устанавливаются только верифицированные community nodes; наш узел пока не верифицирован.

## Установка

1. В n8n: **Settings → Community Nodes → Install**.
2. Имя пакета: `n8n-nodes-apipay`.
3. Создайте учётные данные **ApiPay API** и вставьте API-ключ. Секрет подписи нужен только триггеру.

Выбора «песочница или рабочий режим» в узле нет намеренно: режим — свойство организации за API-ключом, он виден и переключается в кабинете. Поле `is_sandbox` у счёта и в корне тела вебхука относится к самому объекту, а не к текущему режиму организации: свой режим ваша система знает сама.

## Что умеет узел

| Группа | Операций | Что закрывает |
|---|---|---|
| Счета | 11 | по номеру, по QR, пачкой до 100, отмена, статусы, статистика, чек Kaspi, внутренняя заметка |
| Подписки | 11 | создание, пауза, возобновление, отмена, счета подписки, симуляции песочницы |
| Каталог | 11 | позиции, массовое снятие, поиск по штрихкоду в Нацкаталоге, очередь и ошибки приёма |
| Касса | 9 | сводка по наличным, смены, сверка с кассой Kaspi, PDF-отчёт, автозакрытие и автоизъятие |
| QR-возвраты | 7 | ссылка покупателю, отзыв ссылки, возвратные операции, проведение возврата |
| Возвраты | 4 | полный и частичный, список, возвраты по счёту |
| Фискальные чеки | 4 | выбить, превью, получить, история |
| Печатные QR | 4 | выпуск листа под сделку, список, карточка, отключение |
| Аккаунт и тариф | 3 | состояние аккаунта, своя подписка, каталог тарифов |
| Логи вебхуков | 2 | список доставок и одна доставка целиком |
| Проверка номера | 1 | зарегистрирован ли номер в Kaspi |
| Health check | 1 | доступность API |

Подключение кассира (`/connections`) в узел не входит: SMS-код приходит владельцу номера, а не в workflow.

## Триггер и подпись

Узел сверяет HMAC-SHA256 по сырому телу запроса сам. Проверка включена по умолчанию, и события, которые проверить нельзя, отклоняются: адрес вебхука в n8n публичный, и без подписи «оплачено» мог бы прислать кто угодно.

Адрес уведомлений ApiPay нигде не регистрирует через API — он принадлежит API-ключу. Поэтому порядок такой: активируйте workflow, скопируйте выданный n8n webhook URL и вставьте его в кабинете (Настройки → «Подключение»), там же сгенерируйте секрет подписи. В кабинет вписывается **production**-адрес триггера — он появляется у активированного workflow; тестовый живёт только пока открыт режим прослушивания.

Четыре вещи, о которых стоит знать заранее:

- статус счёта ставит Kaspi, и последовательности вроде `cancelled → paid` законны — не закрывайте заказ по локальному таймауту;
- `invoice.qr_scanned` сообщает о скане, статус счёта не меняет и может прийти уже **после** `paid` — не откатывайте оплаченный заказ;
- `qr_refund.execution_uncertain` означает, что исход возврата не доказан: повторять нельзя, такие случаи разбираются через поддержку;
- в рабочем режиме события с `is_sandbox: true` в корне тела отсекайте узлом IF сразу за триггером: ответ `2xx` триггер уже дал сам, а workflow их исполнять не должен — событие по песочному объекту, отправленное до перевода организации в рабочий режим, может прийти уже после него.

## Идемпотентность

Если workflow может выполниться повторно, передавайте ключ идемпотентности (`Idempotency Key` в Additional Fields у создания счёта, у каждой строки пачки — свой). Без него повтор выставляет второй счёт тому же человеку.

## Ссылки

- Пакет в npm: https://www.npmjs.com/package/n8n-nodes-apipay
- Исходный код: https://github.com/bazarbaykz/n8n-nodes-apipay
- Документация API: https://apipay.kz/docs
- Инструкция для ИИ-помощника: https://apipay.kz/for-ai
- Каталог ошибок: https://apipay.kz/errors
- Другие интеграции: https://apipay.kz/moysklad · https://apipay.kz/kaspi-pay-1c · https://apipay.kz/lovable-integration