Что такое каталог простыми словами
Каталог — это ваши товары, заведённые в ApiPay. Он нужен там, где покупателю выбивается фискальный чек: чтобы в чеке было видно, что именно купили, система должна знать состав покупки, а не только итоговую сумму.
Фискальные чеки выбивает Kaspi Касса (ОФД). Поэтому каталог и Kaspi Касса ходят парой: есть касса — нужен каталог. Как подключить Kaspi Кассу, описано в справке Kaspi; в приложении Kaspi Pay это раздел Сервисы → Kaspi Касса.
Если вы продаёте услуги, работы или сдаёте в аренду и чеков не выбиваете — каталог вам не нужен, счета выставляются одной суммой.
Что меняется в чеке
Пока каталог выключен, а Kaspi Касса у вас работает, фискальный чек уходит без состава покупки. Последствия два:
- покупатель не видит в чеке, что именно он купил;
- не проходит маркировка товаров (
ntin) — маркированный товар в чеке не идентифицируется как маркированный.
После включения каталога чек собирается по позициям корзины: наименование, количество, цена, коды Нацкаталога.
Что меняется в кабинете
После включения каталога QR-счёт в кабинете собирается из позиций каталога, а не вводом одной суммы. Значит, каталог должен быть заполнен до включения: с пустым каталогом QR-счёт выставить будет нечем. Как заполнить — Заполнение каталога.
Счёт по номеру телефона в кабинете по-прежнему выставляется одной суммой.
Вместе с каталогом в меню появляется раздел «Касса» — кассовые смены Kaspi, наличные, отчёт по смене и сверка со счетами. Пока Kaspi Кассы нет, раздела нет тоже: смен не существует, показывать в нём нечего. Что там внутри — «Отчёт по кассовой смене Kaspi».
Что нужно сделать разработчику
Работы немного, и почти вся она — про то, где брать идентификаторы товаров.
- Завести каталог. Товары заливаются пакетно, до 100 позиций за запрос; ответ асинхронный, а по завершении батча приходит один вебхук
catalog.batch_processedс итогами и списком неудавшихся позиций. Порядок и разбор ошибок — Массовая заливка каталога из 1С. - Держать у себя соответствие «ваш товар → позиция каталога». Ключом удобно взять
external_ref— это ваш собственный идентификатор, вы задаёте его при заливке и потом ищете позицию по нему, не храня наши id. Как синхронизировать без дублей — Каталог для 1С. - Научить код собирать
cart_itemsдля QR-счетов. Состав полей и режимы чтения каталога — Каталог, корзина и Нацкаталог; разбор отказов вокруг корзины — Ошибка 422 cart_items. - Проверить автоплатежи, если вы создаёте их через API. После включения каталога
POST /subscriptionsпринимается только сcart_items. ⚠️ Ошибка там приходит обычной валидацией по полюcart_items, безerror_code— обработайте её отдельно от QR-веток. Уже созданные подписки продолжают списываться: списание выставляется счётом по номеру телефона, а он корзины не требует. - Отладить на песочнице. Заведите тестовую организацию с ответом «касса есть» — там каталог и QR-счета с корзиной проходят целиком. Учтите одно отличие: в песочнице позиция активируется сразу в ответе, каталожных вебхуков там нет — обработчик
catalog.batch_processedпроверяется уже на боевой заливке. - Написать нам, что готовы. Дальше состояние каталога пересверяется, и вы проверяете боевой QR-счёт с корзиной.
Пока каталог у вас выключен, боевой запрос с корзиной отвечает 422 catalog_not_supported — это ожидаемо, отлаживайтесь в песочнице.
⚠️ Разбирайте error_code, а не текст ответа: коды стабильны, тексты — нет.
Печатные QR-листы: сказать до включения
Печатный QR-лист превращается в счёт в момент, когда покупатель его сканирует, — по тем же правилам, что и обычный QR-счёт. Значит лист, выпущенный без состава покупки, после включения каталога перестанет работать, а переиздать уже напечатанный лист нельзя.
Если у вас есть напечатанные листы — скажите нам об этом до включения каталога, чтобы спланировать замену. После включения этот разговор будет уже поздним.
Почему нельзя включить сначала, а править потом
Включение каталога меняет правила проверки входящих запросов сразу для всей организации. Если интеграция ещё шлёт QR-счета одной суммой, каждый такой запрос начнёт получать отказ — приём оплат по QR встанет в тот же момент.
Обратный порядок безопасен: код, уже умеющий передавать состав, до включения работает на песочнице, а после включения — на бою.
⚠️ Отсюда же практическое правило: пересверка состояния — это действие, а не справка. И подключение кассира, и кнопка «Обновить информацию об организации» в настройках могут включить каталог прямо в момент нажатия. Держите их напоследок.
Частые вопросы
Мои счета на номер телефона перестанут работать?
Нет. На POST /invoices корзина остаётся необязательной даже с включённым каталогом. Если ваш код выставляет счета по номеру телефона и работает — не трогайте его.
Можно включить каталог самому в кабинете?
В песочнице — да, там это ответ на вопрос «есть ли у вас касса». В рабочем режиме отдельной кнопки «включить каталог» нет: состояние определяется тем, есть ли у вашей организации Kaspi Касса, и пересверяется в двух случаях — когда вы подключаете или переподключаете кассира и когда нажимаете в настройках «Обновить информацию об организации».
Как отличить эти отказы в коде?
Запрос без корзины у организации с каталогом отвечает 422 catalog_requires_cart_items на POST /invoices/qr и POST /static-qr; запрос с корзиной у организации без каталога — 422 catalog_not_supported. В теле этих отказов нет ключа errors: отказ описывает состояние организации, а не поле формы. Создание подписки корзину тоже требует, но отвечает обычной ошибкой валидации по полю cart_items, без error_code.
Что с суммами и копейками?
На QR-счетах суммы с тиынами допустимы. На счетах по номеру телефона — только целые тенге; это касается и итога корзины после скидок.
Товара нет в каталоге, что делать?
Залить его вместе с остальными и дождаться подтверждения обработки — выставлять счёт позицией, которая ещё не обработалась, нельзя. Подробности — в статье про массовую заливку.
Что дальше
- Трек M: Счета с корзиной и ОФД
- Трек D: Каталог, корзина и Нацкаталог, Каталог для 1С