Порядок вызова
Сверка идёт по смене, которую вы уже получили списком. Поэтому порядок такой:
GET /cashbox/shifts?date_from=…&date_to=…— получить смены и ихid.GET /cashbox/reconciliation?shift_id={id}— сверка по нужной смене.
Если пропустить первый шаг, придёт 404 cashbox_shift_not_found: для сверки такой смены ещё не существует. Активная сессия кассира на самой сверке при этом не требуется — она работает по уже полученным данным.
Что в ответе
ours — ваша половина. Оплаты по счетам ApiPay за окно смены: sales (оплачено), refunds (возвраты), net_amount (разность) и sales.refunded_later — сколько из оплаченного вернули позже. Окно считается по дате оплаты счёта, а не по дате выставления: счёт, выставленный до полуночи и оплаченный после, попадёт в смену оплаты.
При нескольких кассах учтите: продажи считаются по кассиру этой смены, а возвраты — по всей организации. Поэтому смотрите sales и refunds по отдельности, а net_amount в такой конфигурации сравнивать с одной кассой нельзя.
kaspi — половина кассы. Итог смены (total_income), число операций и признак открытой смены. У блока есть snapshot.stale: снимок старше 15 минут — обновите список смен, чтобы освежить цифры.
discrepancies[] — причины расхождения. Это не дефекты, а свойства данных:
| Код | О чём |
|---|---|
kaspi_income_includes_offline_sales |
В итоге кассы есть продажи, оформленные мимо ApiPay |
shift_not_calendar_day |
Границы смены не совпадают с календарными сутками |
open_shift_moving_target |
Смена ещё открыта, цифры меняются прямо сейчас |
paid_at_timezone_boundary |
Часть оплат пришлась на границу суток |
invoices_without_connection |
Часть счетов не привязана к конкретной кассе (в поле count — сколько) |
kaspi_snapshot_stale |
Данные кассы получены давно |
Почему разница не считается
Итог смены в кассе — единая сумма: продажи наличными и продажи, оформленные мимо ApiPay, в ней не выделены. Ваши счета ApiPay — только их часть. Вычесть одно из другого можно, но полученное число не будет означать «недостачу»: продажа мимо сервиса — не ошибка.
Поэтому сервис показывает обе цифры как есть и перечисляет причины, а вывод делает человек. Полей с разницей, вердиктом и «объяснённой частью» в ответе нет.
Что с этим делать на практике
- Разошлось сильно и без офлайн-продаж — посмотрите
invoices_without_connection: при нескольких кассах часть счетов могла не привязаться к точке. - Смена открыта — сверять имеет смысл после закрытия, иначе цифра кассы догоняет.
- Нужны суммы по вашим счетам без кассы вовсе — берите обычный список счетов с фильтром по дате оплаты, см. «Жизненный цикл счёта».
Для вашего ИИ-агента
Смотрите: GET /cashbox/reconciliation требует shift_id, режима «за сутки» нет — дневные наличные отдаёт GET /cashbox/summary; перед сверкой обязателен GET /cashbox/shifts, иначе 404 cashbox_shift_not_found; в ответе нет полей verdict, comparable, delta — разница не вычисляется; ours считается по paid_at; discrepancies[].amount всегда null — причины не квантифицируются; count есть только у invoices_without_connection.
Частые вопросы
Почему сверка не говорит «всё сошлось»?
Потому что для такого вывода нужна сопоставимая часть выручки кассы отдельной цифрой, а итог смены приходит одной суммой.
Можно сверить сразу за день, а не за смену?
Сверка работает по смене. Наличные за день показывает GET /cashbox/summary и блок «Наличные в кассе» в кабинете.
Возвраты попадают в сверку?
Да, в блок refunds — по времени самой операции возврата, даже если счёт оплачивался раньше.