Автозакрытие кассовой смены Kaspi: как включить

Что нужно до начала

1. К аккаунту Kaspi Pay подключена Kaspi Касса (ОФД). Смены, отчёты и сверку мы получаем от неё — это та же связка, что включает каталог товаров.

   Если продажи идут через Kaspi Pos без ОФД, кассовых смен у организации не существует: раздела «Касса» в кабинете нет, кассовые запросы отвечают отказом. Подробнее — «Переход на каталог товаров».

2. Подключён кассир Kaspi. Раздел «Касса» работает через сотрудника с ролью «Кассир» — см. «Как подключить кассира Kaspi».

3. Настройки кассы меняет владелец организации. Остальным сотрудникам они видны только для чтения; по API-ключу организации тумблеры доступны без этого ограничения.

4. Настроены вебхуки, если результат закрытия нужен вашей системе, — «Настройка вебхуков».

Если Kaspi Касса у вас подключена, а раздела «Касса» нет — нажмите в настройках «Обновить информацию об организации»: состояние пересверяется в этот момент.

⚠️ Этим же действием включается каталог товаров: после него QR-счета выставляются только с составом покупки, а уже напечатанные QR-листы без состава перестают работать — переиздать их нельзя. Сначала убедитесь, что ваша интеграция умеет передавать состав, — «Переход на каталог товаров».

В песочнице кассовые запросы отвечают всегда — тестовыми данными и независимо от того, есть ли касса в бою. Раздел «Касса» в кабинете тестовой организации появляется, если вы ответили, что касса есть; ответ меняется в настройках. Интеграцию, прошедшую в песочнице, обязательно проверьте на боевой организации.

Тумблер автозакрытия

Ответ на переключение содержит два поля:

{ "changed": true, "new_value": true }

changed: false — не ошибка: на кассе уже стояло запрошенное значение, менять было нечего. Это удобно для скриптов — можно спокойно «доводить» настройку до нужного состояния при каждом запуске.

Отдельно стоит знать про два отказа:

• 503 cashbox_toggle_in_progress — эту же настройку прямо сейчас меняет другой запрос. Повторите через минуту.
• 503 cashbox_toggle_unavailable — проверить текущее значение на кассе не удалось, изменение не применено.

Рядом живёт второй тумблер — автоизъятие наличных при закрытии смены (PUT /cashbox/settings/auto-withdrawal): когда он включён, наличные изымаются из кассы при закрытии смены автоматически. Контракт ответа и отказы у него те же.

Закрытие смены через API

POST /api/v1/cashbox/shifts/close
{ "client_operation_id": "close-2026-08-10-01", "shift_number": 106 }

Ответ — 202 с идентификатором операции и poll_url. Дальше два пути:

• Поллинг: GET /cashbox/operations/{id} до статуса completed или failed.
• Вебхук: cashbox.shift_closed при успехе, cashbox.shift_close_failed при отказе.

client_operation_id уникален в пределах организации: повторный запрос с тем же значением вернёт 409 cashbox_duplicate_operation и в теле — идентификатор уже идущей операции. Это защита от двойного нажатия, а не ошибка.

Если закрытие не удалось

У операции есть поле resolution.safe_to_retry. Оно равно true только у операции в статусе failed — у pending, sending и completed там false.

Отказ не означает, что смена точно осталась открытой: если ответ Kaspi не дошёл, она могла и закрыться. Повторить закрытие после failed безопасно — уже закрытую смену Kaspi отдаёт как «смена уже закрыта», и операция завершается успехом.

Повтор всегда с новым client_operation_id: прежний после отказа не освобождается.

Хотите убедиться в фактическом состоянии до повтора — смотрите список GET /cashbox/shifts и приложение Kaspi Pos.

Для вашего ИИ-агента

Смотрите: кассовые ручки требуют подключённой Kaspi Кассы (ОФД) — без неё GET /cashbox/shifts и POST /cashbox/shifts/close отвечают 409 cashbox_kkm_unknown, а GET /cashbox/summary и оба тумблера — 409 rfo_missing; PUT /cashbox/settings/auto-close с {enabled} → {changed,new_value}, changed:false — норма; POST /cashbox/shifts/close отвечает 202, результат читать поллингом GET /cashbox/operations/{id} или вебхуком cashbox.shift_closed/cashbox.shift_close_failed; при failed повторять новым client_operation_id (повтор безопасен: уже закрытая смена считается успехом), resolution.safe_to_retry равен true ровно у статуса failed; у кассовых ручек отдельный минутный лимит — 30 запросов в минуту на ключ.

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