Как импортировать платежи Kaspi Pay в 1С

Ручной путь: выгрузка из Kaspi Pay

Общий порядок такой:

1. Зайти в кабинет Kaspi Pay для предпринимателей под своей учётной записью.
2. Открыть раздел с операциями (выпиской) и задать нужный период — обычно вчерашний день или смену.
3. Выгрузить файл с операциями.
4. Загрузить файл в 1С — тем механизмом, который для этого предусмотрен в вашей конфигурации (загрузка выписки, обработка загрузки платежей).
5. Сопоставить строки файла с заказами и документами и провести поступления.

Названия разделов и кнопок задаёт Kaspi и время от времени меняет — актуальные инструкции по операциям и выписке смотрите в справке Kaspi. Вопросы про сами деньги — сроки зачисления, комиссию за приём платежа, реквизиты — тоже туда: это отношения между вами и Kaspi, ApiPay в них не участвует.

Что у этого пути неудобно:

• Данные появляются не в момент оплаты, а когда сотрудник сядет выгружать файл: раз в смену, раз в день, а на выходных — в понедельник. Всё это время менеджер не знает, оплачен заказ или нет, и отгрузка ждёт.
• В файле деньги, а не заказы. Связь «платёж ↔ документ 1С» держится на сумме, времени и памяти человека. Два заказа на одинаковую сумму в один день — и сопоставление становится гаданием.
• Один и тот же файл легко загрузить дважды, и в 1С появляются задвоенные поступления. Ловится это уже на закрытии периода.
• Ошибка обнаруживается поздно. Расхождение видно, когда бухгалтер сводит период, а не когда оно произошло.

Пока платежей десятки в месяц, этот путь работает. Дальше он начинает стоить дороже, чем автоматизация.

Какие данные о платеже даёт ApiPay

Если счёт выставлен через ApiPay, платёж не нужно опознавать — он с самого начала связан с вашим документом. Данные доступны тремя способами.

Объект счёта — GET /api/v1/invoices/{id}. Что в нём для 1С:

Вебхук invoice.status_changed — приходит на ваш адрес, когда счёт сменил статус (pending, paid, cancelled, expired, error, partially_refunded). В теле: event, timestamp и объект invoice с теми же id, external_order_id, amount, status, а при status: "paid" — ещё и paid_at. Настройка адреса, проверка подписи и повторные доставки — в статье «Вебхуки ApiPay: настройка и проверка подписи».

Список счетов за период — GET /api/v1/invoices. Границы окна date_from и date_to задаются в зоне мерчанта (Asia/Almaty) и включительны; голая дата означает календарные сутки целиком. Для «что оплачено за вчера» берут date_field=paid_at — так же операции раскладывает по сменам терминал. Фильтр по статусам множественный, и для «оплаченного» их два: status[]=paid&status[]=partially_refunded — счёт с частичным возвратом деньги принял, без него выборка неполна. Пагинация плоская: {current_page, data, total}, до 100 записей на страницу.

Чек Kaspi по оплаченному счёту забирается отдельно — GET /api/v1/invoices/{id}/receipt. Ответ асинхронный: первый вызов отдаёт 202 со status: "pending", повторите запрос через poll_after секунд — готовый чек придёт с 200. Ссылки из ответа открываются без API-ключа: не публикуйте их и не пишите в логи.

Когда сверка руками перестаёт сходиться

Признаки, по которым видно, что пора менять порядок:

• платежей за день десятки, и «непонятное поступление на 12 400 ₸» ищут по всей базе;
• отгрузку задерживают до вечерней выгрузки, потому что раньше оплату не подтвердить;
• в 1С уже находили задвоенные поступления после повторной загрузки файла;
• клиент пишет «я оплатил», а в 1С заказ висит неоплаченным, и приходится верить на слово.

Через ApiPay порядок переворачивается: не платёж ищет документ, а документ сам выставляет счёт и потом узнаёт о своей оплате.

1. 1С создаёт счёт. POST /api/v1/invoices с phone_number покупателя, amount в целых тенге и external_order_id = номер документа 1С. Туда же кладут external_order_id_idempotency с тем же значением (до 191 символа): пока счёт по документу жив, повторное проведение второй счёт не создаст — придёт 409 duplicate_idempotency_key с invoice_id и status уже существующего. Если прежний счёт истёк, отменён или ушёл в error, тот же ключ выпускает новый счёт — это перевыставление, а не дубль.
2. Покупатель платит в приложении Kaspi — на свой телефон, как обычно.
3. 1С узнаёт об оплате. Если 1С опубликована в интернет — вебхуком invoice.status_changed со status: "paid". Если нет (а чаще всего нет) — поллингом GET /api/v1/invoices/{id}, у него отдельный лимит 1000 запросов в минуту как раз под такие регламентные задания.
4. Обработка находит документ по external_order_id и проводит платёж. Дубли отсекаются дедупом по паре (invoice.id, invoice.status).
5. Раз в сутки — сверка. GET /api/v1/invoices за вчерашние сутки с date_field=paid_at и origin=apipay: то, что не доехало вебхуком, догоняется здесь. Фильтр origin обязателен — без него в выборку попадут и продажи, проведённые в приложении Kaspi Pay мимо ApiPay: у них нет external_order_id, документа в 1С им не найти. Такие продажи подтягиваются из истории Kaspi не сразу и датируются временем самой операции, поэтому уже пройденное окно при повторной сверке может пополниться — перезапрашивайте окно целиком, а не только новые записи.

Это тот же самый Kaspi Pay и та же организация: деньги идут напрямую на ваш Kaspi-счёт, кабинет Kaspi остаётся у вас и работает как раньше. ApiPay выставляет счета через штатную роль «Кассир» и к вашим деньгам доступа не имеет. Одно условие: ApiPay подключается отдельным номером сотрудника с ролью «Кассир», и под этим номером входить в приложение Kaspi Pay нельзя — привязка разорвётся. Выписку и всё остальное в кабинете вы смотрите под своим обычным номером, как раньше — «Требования к номеру кассира».

Готового модуля для 1С у ApiPay нет — это доработка вашей конфигурации: HTTP-запросы из 1С к REST API. Рецепт запросов, маппинг документов и чек-лист запуска разобраны в статье «Как выставлять Kaspi-счета из 1С через API ApiPay», короткая витрина — ApiPay для 1С, справочник методов — документация API. Код при этом может написать ваш ИИ-агент: дайте ему страницу apipay.kz/for-ai.

Выгрузка файлом или ApiPay: что меняется

Есть и промежуточный вариант, без доработки 1С: выставлять счета в кабинете ApiPay руками и выгружать их за период в Excel, CSV или PDF по тем же фильтрам, что видны на экране. Данные при этом всё равно появляются не в момент оплаты, но у каждой строки уже есть ваша ссылка на документ.

Частые вопросы