Сначала проверьте
- Полный текст ошибки под рукой? Диагностика идёт по точной строке из JSON-ответа — «не работает» без текста не диагностируется.
- У организации есть каталог (Каспи ОФД)? Если в кабинете есть каталог — он и есть Каспи ОФД: QR-счёт и печатный QR у такой организации создаются только с корзиной; счёт по номеру проходит и одной суммой.
- Песочница или прод? Проверка «каталог ↔ корзина» работает одинаково в обоих режимах; отличие одно — в песочнице флаг каталога организации можно выключить самому, в рабочем режиме его меняет только поддержка.
Ветки диагностики
| Текст ошибки | Причина | Что сделать | Подробнее |
|---|---|---|---|
422 This organization requires cart items |
Подключён каталог (Каспи ОФД), а запрос ушёл на POST /invoices/qr или POST /static-qr — там счёт принимается только с корзиной |
Передавать cart_items[]: каждый элемент — catalog_item_id + count |
«Как выглядит правильный запрос с корзиной?» в «Счетах с корзиной» |
Catalog item has no price set |
selling_price позиции в каталоге пуста |
Задать цену позиции в каталоге. Поле price пустую каталожную цену НЕ спасает — проверка идёт до него, на всех путях |
«Разбор 422-ошибок по строкам корзины» в «Счетах с корзиной» |
| Итог счёта ≠ переданной сумме | Сумма считается по позициям корзины, а не по вашему amount |
Передавать нужную цену полем price в строке cart_items |
Счета с корзиной |
Total discount cannot exceed subtotal. / Amount after discounts must be greater than 0. |
Скидка съедает всю сумму корзины | Уменьшить discount_percentage либо поднять цены строк |
«Скидка и переопределённая цена» ниже |
Organization has no tradepoint RFO code configured (400) |
Код торговой точки Kaspi не определён. Приходит не на создании счёта, а на операциях с каталогом | Написать в поддержку. Причину также видно в поле catalog_block_reason ответа POST /api/v1/connections/{id}/auth/verify-otp — значение no_tradepoint |
— |
Скидка и переопределённая цена
discount_percentage считается на нашей стороне от фактической цены строки: если вы передали price, скидка берётся именно от него, и в Kaspi уходит уже посчитанная сумма скидки по каждой позиции. Сочетать price и discount_percentage можно.
Счёт отбивают только две проверки:
Total discount cannot exceed subtotal.— суммарная скидка больше суммы позиций.Amount after discounts must be greater than 0.— итог после скидок ≤ 0.
Оба ответа — 422, ключ discount или amount в errors{}. Можно пересчитать скидку у себя и слать уже уценённые цены без discount_percentage — итог по деньгам тот же, но покупатель не увидит скидку отдельной строкой в чеке, а в вебхуке не придут subtotal и discount_sum для сверки.
Пустая цена позиции
has no price set возникает, когда selling_price позиции пуста (типично для товаров, приехавших синхронизацией из Kaspi, — там цену вводят на кассе). Проставьте цену в кабинете или через PATCH /catalog/{id} — минимум 0.01, нулевую цену API не примет.
Частые вопросы
Обязательно заводить все товары в каталог?
Позиции — да, но цены можно переопределять в каждом счёте полем price. Минимальный вариант — несколько «служебных» позиций с реальными ценами; в чек ОФД идёт именно название позиции из каталога.