Шаг 1. Найти смену
GET /api/v1/cashbox/shifts?date_from=2026-08-09&date_to=2026-08-09
Обе границы обязательны, окно — не длиннее 31 дня, иначе придёт 422. В ответе список смен и состояние автозакрытия:
| Поле | Что в нём |
|---|---|
id |
Идентификатор смены — он же нужен для отчёта и сверки |
shift_number |
Номер смены, который видно на кассе |
start_date |
Дата открытия |
is_current |
true у открытой смены |
total_income |
Итог смены суммой "N.NN" |
total_income_raw |
Тот же итог в готовом виде от Kaspi — для показа человеку |
transactions_count |
Сколько операций в смене |
Запрос идёт в кассу Kaspi, поэтому отвечает не мгновенно — закладывайте в свой клиент таймаут с запасом.
Шаг 2. Забрать отчёт
GET /api/v1/cashbox/shifts/118275707/report
→ { "url": "https://…", "expires_at": "2026-08-10T09:15:00+05:00" }
Скачайте файл по url до expires_at. Понадобится позже — запросите ссылку заново; действует общий кассовый лимит: 30 запросов в минуту на ключ.
Утренний отчёт за вчера без ручной работы
Типичный сценарий — раз в сутки складывать PDF во внутреннее хранилище или присылать бухгалтеру:
- По расписанию (например, в 9 утра) запросить смены за вчерашний день.
- Для каждой смены получить ссылку и сразу скачать файл.
- Положить файл к себе и разослать, кому нужно.
Отдельного «отчёта за период» в кассе нет: отчёт всегда по конкретной смене. Если точек несколько, разложите смены по кассам — «Разделить счета по точкам».
Чего в отчёте нет
Отчёт по смене — это цифры кассы Kaspi. Он не знает, какие из ваших счетов ApiPay оплачены: чтобы увидеть обе стороны рядом, есть сверка — «Сверка кассы со счетами ApiPay».
Для вашего ИИ-агента
Смотрите: GET /cashbox/shifts?date_from&date_to — обе границы обязательны, окно ≤ 31 дня, иначе 422; GET /cashbox/shifts/{id}/report отдаёт {url, expires_at}, а не файл — скачивать сразу, ссылку не хранить; total_income — сумма строкой "N.NN", total_income_raw — готовое форматирование для показа, не парсить; при недоступности отчёта приходит cashbox_report_unavailable (503) — повторить позже; лимит кассовых запросов 30 в минуту на ключ.
Частые вопросы
Можно получить отчёт по открытой смене?
Отчёт запрашивается по любой смене из списка, но у открытой смены цифры продолжают меняться.
Ссылка перестала открываться — что делать?
Запросить отчёт заново: срок жизни ссылки истёк, файл никуда не делся.
Нужен ли для отчёта подключённый кассир?
Да, весь раздел «Касса» работает через подключённого кассира Kaspi — «Как подключить кассира».