Какие поля есть у товара и на что влияют
| Поле | Обязательно | На что влияет |
|---|---|---|
| Имя | да | Наименование позиции в чеке Kaspi. До 255 символов |
| Цена | да | Цена за единицу (от 0.01 ₸). В счёте её можно переопределить для конкретной продажи |
| Единица измерения | да | Штука, кг, литр и т.п. — как считается количество в чеке |
| Штрихкод | нет | Идентификатор товара. До 32 символов. Позволяет находить товар сканером и в Нацкаталоге |
| НТИН | нет | Код Нацкаталога. Если задан — попадёт в фискальный чек Kaspi как маркировка |
| GTIN | нет | Международный код GS1 (приходит вместе с НТИН при сканировании штрихкода) |
| external_ref | нет | Ваша ссылка на товар в 1С/CRM. Нужна, если каталог ведёт интегратор (см. ниже) |
Имя, цену и единицу вы задаёте всегда. Штрихкод, НТИН и GTIN — только для маркированных товаров и для тех, кого удобно искать по штрихкоду.
Правило «один штрихкод = один товар»
Kaspi разрешает ровно один товар на штрихкод и на НТИН. Это ключевое ограничение, и из него растут почти все вопросы «почему товар не добавляется» или «откуда дубли».
- Разные размеры/фасовки под одним штрихкодом — это ОДИН товар. Если у вас, например, «Ручка гелевая синяя 0.5» и «Ручка гелевая синяя 0.7» помечены одним и тем же штрихкодом, для Kaspi это один товар. Заводить их как две позиции с одинаковым штрихкодом нельзя — вторая не пройдёт.
- Что делать. Либо дайте каждому варианту свой штрихкод, либо ведите их как один товар. Если штрихкода нет — оставьте поле пустым, товар заведётся по имени и цене.
- ApiPay больше не плодит «мёртвые» дубли. При попытке завести товар с уже занятым штрихкодом система теперь находит существующий товар и дополняет его (например, проставит пустой НТИН), а не создаёт битую строку. Вы получаете живой товар, а не ошибку.
Когда НТИН попадает в чек Kaspi
Простое правило:
Если НТИН задан у товара в каталоге ApiPay (вписали вручную, получили сканированием штрихкода или его прислал ваш интегратор) — он попадёт в фискальный чек Kaspi. Если поле НТИН пустое — в чек он не попадёт.
Чтобы вы не пропустили такие товары, в каталоге есть подсветка: у позиции, где штрихкод есть, а НТИН пустой, стоит пометка «НТИН не указан» (в API это флаг ntin_missing). Это не блокирует продажу — товар продаётся и без НТИН, просто в чеке не будет кода маркировки.
Как дорезолвить НТИН сканированием штрихкода
Если товар маркированный, а НТИН пустой — не вписывайте код руками наугад. Дайте системе найти его по штрихкоду:
- В карточке товара нажмите «Найти НТИН» (сканирование штрихкода в Нацкаталоге Kaspi).
- Система вернёт кандидатов из Нацкаталога с готовыми НТИН и GTIN. Иногда кандидатов несколько (общий GTIN, разные НТИН) — выберите нужный.
- Сохраните — НТИН и GTIN проставятся, и дальше товар пойдёт в чек с маркировкой.
Если штрихкод в Нацкаталоге не нашёлся — это нормально: значит товар немаркированный, оставьте НТИН пустым. Пустой результат поиска — не ошибка.
Не вписывайте случайные цифры в поле НТИН, чтобы «убрать» пометку. Неверный НТИН хуже пустого: он уйдёт в чек и в систему маркировки как чужой код.
Зачем `external_ref`, если каталог ведёт интегратор
Если товары в ApiPay заливаете не вы руками, а программа (1С, ваша CRM, интегратор), попросите их проставлять у каждого товара external_ref — вашу ссылку на этот товар в их системе (код номенклатуры, GUID, артикул).
external_ref— это «якорь», по которому интегратор потом однозначно находит товар при обновлении цены или сверке остатков.- Без него интегратор вынужден сопоставлять товары по штрихкоду или имени, а по одному штрихкоду у вас может быть несколько связанных позиций — легко перепутать.
- Вам как владельцу делать ничего не нужно, кроме одного: сказать интегратору использовать
external_ref. Детали — в статье Каталог для 1С.
Частые вопросы
Товар не добавляется — пишет, что уже есть. Почему?
У товара занят штрихкод или НТИН — Kaspi разрешает один товар на штрихкод. Скорее всего такой товар уже заведён (возможно, под другим названием — например, другой размер). Найдите его в каталоге поиском по штрихкоду и правьте существующую позицию, а не создавайте новую.
Разные размеры одного изделия под одним штрихкодом — как завести?
Для Kaspi это один товар. Либо присвойте каждому размеру свой штрихкод, либо ведите как одну позицию. Два товара с одинаковым штрихкодом система не пропустит.
Почему у товара пометка «НТИН не указан»?
У него заполнен штрихкод, но пустой НТИН — значит в чек Kaspi код маркировки не уйдёт. Если товар маркированный, нажмите «Найти НТИН» и дорезолвите его сканированием штрихкода. Если немаркированный — пометку можно игнорировать.
Обязательно ли заполнять НТИН и штрихкод?
Нет. Обязательны только имя, цена и единица измерения. Штрихкод и НТИН нужны для маркированных товаров и удобного поиска.
Я не вижу в каталоге товары со статусом «ошибка» или «в обработке». Куда они делись?
По умолчанию каталог показывает только активные товары. Остальные статусы (в обработке, ошибка, удалён) включаются отдельным фильтром статусов в поиске — «потыкайте» фильтр, чтобы посмотреть их.
Что дальше
- Трек M: ведёте каталог руками и что-то не сходится — напишите в поддержку ApiPay, разберём вашу конкретную позицию.
- Трек D: каталог заливает 1С или ваша CRM — отдайте разработчику статью Каталог для 1С: синк без дублей и ссылку apipay.kz/for-ai.