Сначала проверьте
- Полный текст ошибки под рукой? Диагностика идёт по точной строке из JSON-ответа — «не работает» без текста не диагностируется.
- У организации есть каталог (Каспи ОФД)? Если в кабинете есть каталог — он и есть Каспи ОФД: счета без корзины не пройдут, отключить её нельзя (только в песочнице).
- Песочница или прод? В песочнице требования каталога мягче — ошибка может проявиться только после перехода в рабочий режим.
Ветки диагностики
| Текст ошибки | Причина (частота по данным поддержки) | Что сделать | Подробнее |
|---|---|---|---|
422 This organization requires cart items |
Подключена Каспи ОФД — счета только с корзиной; первая ступень цепочки, почти всегда | Передавать cart_items[]: каждый элемент — catalog_item_id + count |
«Как выглядит правильный запрос с корзиной?» в «Счетах с корзиной» |
Catalog item has no price set |
Цена позиции в каталоге не задана или равна 0 — вторая ступень, почти всегда после первой | Задать цену позиции в каталоге; в счёте цену можно переопределить полем price |
«Разбор 422-ошибок по строкам корзины» в «Счетах с корзиной» |
| Итог счёта ≠ переданной сумме | Сумма считается по позициям каталога, а не по вашему amount — часто |
Передавать price в cart_items или пересчитывать на своей стороне |
Счета с корзиной |
| Ошибка при скидке против переопределённой цены | Kaspi валидирует скидку против зарегистрированной цены каталога, а не переданной — редко, но больно | Решение ниже — у этой ветки нет своей статьи | — |
Organization has no tradepoint RFO code configured |
Не настроен RFO-код торговой точки — редко | Написать в поддержку — настраивается на стороне ApiPay | — |
Скидка + переопределённая цена: почему ломается
Грабля, на которую наступают со скидками: если передать discount_percentage и одновременно переопределить price (отличную от зарегистрированной в каталоге), Kaspi проверяет скидку против цены из каталога — и отклоняет счёт.
Надёжное правило: считайте скидку на своей стороне и передавайте уже итоговые переопределённые цены позиций, без discount_percentage. Если скидка нужна «как скидка» (видимая покупателю строка) — передавайте discount_percentage один на весь счёт (1–99, только вместе с cart_items) и не переопределяйте цены.
Цена «0» — это отсутствие цены
Если в каталоге у позиции цена 0, для Kaspi это эквивалентно «цена не задана» — получите тот же has no price set. Проставьте позициям реальные цены (переопределить в счёте всё равно можно) — это 2 минуты в кабинете или через PATCH /catalog/{id}.
Для вашего ИИ-агента
Разбирайте errors{} из 422-ответа по строкам корзины (cart_items.N.catalog_item_id); catalog_item_id берите из GET /catalog; помните: цена 0 = цены нет; discount_percentage несовместим с переопределённой price (валидация против цены каталога).
Частые вопросы
Можно отключить каталог, чтобы слать счета одной суммой?
Нет: каталог — это Каспи ОФД. Если у организации есть Kaspi-касса, корзина обязательна; отключение возможно только в песочнице. В чек ОФД идёт именно название позиции из каталога.
Обязательно заводить все товары в каталог?
Позиции — да, но цены можно переопределять в каждом счёте полем price. Минимальный вариант — несколько «служебных» позиций с реальными ценами.
Почему цена 0 в каталоге не работает?
Для Kaspi ноль эквивалентен отсутствию цены — та же ошибка has no price set. Проставьте позициям ненулевые цены.
Как правильно передать скидку?
discount_percentage от 1 до 99 — один на весь счёт и только вместе с cart_items. Не сочетайте его с переопределёнными ценами: Kaspi проверит скидку против цен каталога и отклонит счёт.
Что такое RFO-код и почему из-за него ошибка?
Реквизит торговой точки для фискализации. Если Kaspi его требует, а он не настроен — напишите в поддержку, настройка на нашей стороне.