> Источник: https://apipay.kz/guides/perehod-na-katalog-tovarov · Обновлено: 2026-08-12 · apipay.kz
> ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay.

# Переход на каталог товаров: порядок и что поменять

**TL;DR.** Каталог товаров в ApiPay включается вместе с Kaspi Кассой (ОФД). Пока каталог выключен, счета уходят одной суммой и в фискальном чеке не видно состава покупки. После включения QR-счета выставляются только с составом — запрос с одной суммой отвечает `422 catalog_requires_cart_items`. Поэтому порядок один: **сначала интеграция учится передавать состав, и только потом каталог включается.** До этого не нажимайте в настройках «Обновить информацию об организации» и не переподключайте кассира — именно это и включает каталог. Отдельно: печатные QR-листы, выпущенные без состава, после включения работать перестают.

## Коротко

| Вопрос | Ответ |
|---|---|
| Что такое каталог | Список ваших товаров в ApiPay. Появляется у тех, у кого включена Kaspi Касса (ОФД) |
| Кто его включает | Никто вручную: состояние определяется тем, есть ли у организации Kaspi Касса, и пересверяется при подключении кассира и по кнопке «Обновить информацию об организации» |
| Что меняется в чеке | Покупатель видит наименования, количество и цены вместо строки «Оплата N ₸»; работает маркировка (`ntin`) |
| Что меняется в API | На QR-счетах `cart_items[]` становится обязательным, `amount` игнорируется |
| Счёт по номеру телефона | Продолжает работать одной суммой — корзина там остаётся необязательной |
| Порядок | Правите интеграцию и заполняете каталог → и только потом пересверяете состояние. Не наоборот |
| Печатные QR-листы | Выпущенные без состава после включения перестают работать, переиздать их нельзя |

## Что такое каталог простыми словами

Каталог — это ваши товары, заведённые в ApiPay. Он нужен там, где покупателю выбивается **фискальный чек**: чтобы в чеке было видно, что именно купили, система должна знать состав покупки, а не только итоговую сумму.

Фискальные чеки выбивает **Kaspi Касса (ОФД)**. Поэтому каталог и Kaspi Касса ходят парой: есть касса — нужен каталог. Как подключить Kaspi Кассу, описано в [справке Kaspi](https://guide.kaspi.kz/partner/ru/cashier/connection/q2479); в приложении Kaspi Pay это раздел **Сервисы → Kaspi Касса**.

Если вы продаёте услуги, работы или сдаёте в аренду и чеков не выбиваете — каталог вам не нужен, счета выставляются одной суммой.

## Что меняется в чеке

Пока каталог выключен, а Kaspi Касса у вас работает, фискальный чек уходит **без состава покупки**. Последствия два:

- покупатель не видит в чеке, что именно он купил;
- не проходит маркировка товаров (`ntin`) — маркированный товар в чеке не идентифицируется как маркированный.

После включения каталога чек собирается по позициям корзины: наименование, количество, цена, коды Нацкаталога.

## Что меняется в кабинете

После включения каталога QR-счёт в кабинете собирается из позиций каталога, а не вводом одной суммы. Значит, каталог должен быть **заполнен до включения**: с пустым каталогом QR-счёт выставить будет нечем. Как заполнить — [Заполнение каталога](/guides/zapolnenie-kataloga-apipay).

Счёт по номеру телефона в кабинете по-прежнему выставляется одной суммой.

Вместе с каталогом в меню появляется раздел **«Касса»** — кассовые смены Kaspi, наличные, отчёт по смене и сверка со счетами. Пока Kaspi Кассы нет, раздела нет тоже: смен не существует, показывать в нём нечего. Что там внутри — «[Отчёт по кассовой смене Kaspi](/guides/otchet-po-kassovoy-smene-kaspi)».

## Что нужно сделать разработчику

Работы немного, и почти вся она — про то, где брать идентификаторы товаров.

1. **Завести каталог.** Товары заливаются пакетно, до 100 позиций за запрос; ответ асинхронный, а по завершении батча приходит один вебхук `catalog.batch_processed` с итогами и списком неудавшихся позиций. Порядок и разбор ошибок — [Массовая заливка каталога из 1С](/guides/massovaya-zagruzka-kataloga-iz-1c).
2. **Держать у себя соответствие «ваш товар → позиция каталога».** Ключом удобно взять `external_ref` — это ваш собственный идентификатор, вы задаёте его при заливке и потом ищете позицию по нему, не храня наши id. Как синхронизировать без дублей — [Каталог для 1С](/guides/katalog-dlya-integratorov-1c).
3. **Научить код собирать `cart_items` для QR-счетов.** Состав полей и режимы чтения каталога — [Каталог, корзина и Нацкаталог](/guides/katalog-korzina-nackatalog); разбор отказов вокруг корзины — [Ошибка 422 cart_items](/guides/oshibka-422-cart-items).
4. **Проверить автоплатежи, если вы создаёте их через API.** После включения каталога `POST /subscriptions` принимается только с `cart_items`. ⚠️ Ошибка там приходит обычной валидацией по полю `cart_items`, **без** `error_code` — обработайте её отдельно от QR-веток. Уже созданные подписки продолжают списываться: списание выставляется счётом по номеру телефона, а он корзины не требует.
5. **Отладить на песочнице.** Заведите тестовую организацию с ответом «касса есть» — там каталог и QR-счета с корзиной проходят целиком. Учтите одно отличие: в песочнице позиция активируется сразу в ответе, каталожных вебхуков там нет — обработчик `catalog.batch_processed` проверяется уже на боевой заливке.
6. **Написать нам, что готовы.** Дальше состояние каталога пересверяется, и вы проверяете боевой QR-счёт с корзиной.

Пока каталог у вас выключен, боевой запрос с корзиной отвечает `422 catalog_not_supported` — это ожидаемо, отлаживайтесь в песочнице.

⚠️ Разбирайте `error_code`, а не текст ответа: коды стабильны, тексты — нет.

## Печатные QR-листы: сказать до включения

Печатный QR-лист превращается в счёт в момент, когда покупатель его сканирует, — по тем же правилам, что и обычный QR-счёт. Значит **лист, выпущенный без состава покупки, после включения каталога перестанет работать**, а переиздать уже напечатанный лист нельзя.

Если у вас есть напечатанные листы — скажите нам об этом **до** включения каталога, чтобы спланировать замену. После включения этот разговор будет уже поздним.

## Почему нельзя включить сначала, а править потом

Включение каталога меняет правила проверки входящих запросов сразу для всей организации. Если интеграция ещё шлёт QR-счета одной суммой, каждый такой запрос начнёт получать отказ — приём оплат по QR встанет в тот же момент.

Обратный порядок безопасен: код, уже умеющий передавать состав, до включения работает на песочнице, а после включения — на бою.

⚠️ Отсюда же практическое правило: **пересверка состояния — это действие, а не справка.** И подключение кассира, и кнопка «Обновить информацию об организации» в настройках могут включить каталог прямо в момент нажатия. Держите их напоследок.

## Частые вопросы

**Мои счета на номер телефона перестанут работать?**
Нет. На `POST /invoices` корзина остаётся необязательной даже с включённым каталогом. Если ваш код выставляет счета по номеру телефона и работает — не трогайте его.

**Можно включить каталог самому в кабинете?**
В песочнице — да, там это ответ на вопрос «есть ли у вас касса». В рабочем режиме отдельной кнопки «включить каталог» нет: состояние определяется тем, есть ли у вашей организации Kaspi Касса, и пересверяется в двух случаях — когда вы подключаете или переподключаете кассира и когда нажимаете в настройках «Обновить информацию об организации».

⚠️ Поэтому, пока интеграция не умеет передавать состав покупки, эту кнопку не нажимайте и кассира не переподключайте: если Kaspi Касса у вас уже есть, каталог включится в тот же момент и QR-счета одной суммой начнут отбиваться.

**Как отличить эти отказы в коде?**
Запрос без корзины у организации с каталогом отвечает `422 catalog_requires_cart_items` на `POST /invoices/qr` и `POST /static-qr`; запрос с корзиной у организации без каталога — `422 catalog_not_supported`. В теле этих отказов **нет** ключа `errors`: отказ описывает состояние организации, а не поле формы. Создание подписки корзину тоже требует, но отвечает обычной ошибкой валидации по полю `cart_items`, без `error_code`.

**Что с суммами и копейками?**
На QR-счетах суммы с тиынами допустимы. На счетах по номеру телефона — только целые тенге; это касается и итога корзины после скидок.

**Товара нет в каталоге, что делать?**
Залить его вместе с остальными и дождаться подтверждения обработки — выставлять счёт позицией, которая ещё не обработалась, нельзя. Подробности — в [статье про массовую заливку](/guides/massovaya-zagruzka-kataloga-iz-1c).

## Что дальше

- Трек M: [Счета с корзиной и ОФД](/guides/scheta-s-korzinoy-cart-items-ofd)
- Трек D: [Каталог, корзина и Нацкаталог](/guides/katalog-korzina-nackatalog), [Каталог для 1С](/guides/katalog-dlya-integratorov-1c)

---

ApiPay — независимый сервис и не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки их правообладателя.
База знаний: https://apipay.kz/guides