Как подключить Kaspi.kz к порталу: токен, заказы, прайс-лист остатковБета

Интеграция в бета-версии: работает по официальной документации площадки, возможны ошибки — проверяйте заказы и остатки в кабинете площадки.

Kaspi.kz подключается по токену API кабинета продавца. Портал забирает заказы в канбан в тенге, принимает и отменяет их в Kaspi, печатает накладную Kaspi Доставки и завершает заказ кодом покупателя. Остатки и цены Kaspi принимает не по API, а прайс-листом: портал отдаёт ссылку на XML-файл, Kaspi забирает его сам раз в час.

1. Что умеет интеграция

Интеграция сделана по официальному руководству Kaspi. Живой кабинет ещё проверяется: формат прайс-листа сверен только с примером из руководства.

2. Что нужно заранее

• Кабинет продавца Kaspi (Kaspi Магазин) с действующим договором.
• Токен API: его выпускает Kaspi.
• Коды точек продаж (storeId) из кабинета: раздел «Склады и магазины».
• Артикулы товаров в кабинете Kaspi должны совпадать с артикулами ваших товаров в портале: латинские буквы и цифры, до 20 символов.
• Тариф Web Plus: раздел «Маркетплейсы» доступен на нём (сейчас в бете).
• Право «Подключения к площадкам» у вашей роли в мастерской.

3. Как получить токен

1. Откройте кабинет продавца Kaspi.
2. Перейдите в «Настройки» → «Токен API» и создайте токен.
3. Скопируйте токен. Если Kaspi попросит оформить доступ к API, следуйте шагам руководства: guide.kaspi.kz.

Токен отдавайте только порталу. Если токен утёк, выпустите новый и замените его в подключении.

4. Подключение у нас

1. Откройте раздел «Маркетплейсы» → «Подключения» и нажмите «Подключить» у Kaspi.kz.
2. Вставьте токен. Валюта магазина — тенге, часовой пояс — Алматы: подставляются сами.
3. Портал проверит связь. Токен сохранится только после успешной проверки.
4. В «Настройках подключения» заполните «Точки продаж (storeId)»: коды из кабинета Kaspi, несколько через запятую. Без них прайс-лист не собрать.
5. Включите нужные виды записи: «Действия с заказами» (принять, отменить, «Выдан»), «Остатки» (нужен для прайс-листа), «Цены» (в прайс-лист пойдёт наша цена).

Выбора склада у Kaspi нет: остатки привязаны к точкам продаж в прайс-листе.

5. Остатки и цены: прайс-лист

У Kaspi нет API остатков и цен. Вместо него Kaspi забирает XML-файл по ссылке и обновляет остатки и цены раз в час, если файл изменился. Поэтому изменения доходят не мгновенно.

1. В настройках подключения Kaspi найдите блок «Ссылка прайс-листа для кабинета Kaspi».
2. Убедитесь, что у блока статус «Прайс-лист готов». Если нет, рядом написана причина: обычно не включён переключатель «Остатки» или не указаны точки продаж.
3. Нажмите «Копировать».
4. В кабинете Kaspi: «Товары» → «Загрузить прайс-лист» → «Автоматическая загрузка». Вставьте ссылку.

Что попадает в файл:

• остаток товара: количество изделия на складе готовой продукции, либо число, которое вы задали (режимы «Со склада», «Под заказ», «Вручную», как у других площадок). «Под заказ» с сроком изготовления превращается в предзаказ до 30 дней;
• цена в целых тенге: наша цена при включённом «Цены», иначе цена, которая сейчас стоит на площадке;
• точки продаж из настроек.

Что в файл не попадает: товары без остатка, без цены, с артикулом, не подходящим под правила Kaspi (латиница и цифры до 20 символов), и дубли артикулов. Список пропущенных с причиной виден под ссылкой: откройте «Не попали в файл».

«Новая ссылка». Ссылка содержит секрет. Если она попала не туда, нажмите «Новая ссылка»: старая ссылка и адрес уведомлений этого подключения сразу перестанут работать, а новую нужно будет заново вставить в кабинете Kaspi.

Если «Остатки» выключить, файл перестанет отдаваться (Kaspi получит «не найдено»), и остатки в Kaspi перестанут обновляться.

6. Заказы

• Валюта. Заказы Kaspi всегда в тенге. Если валюта вашей мастерской тоже тенге, курс равен 1 и суммы не пересчитываются. Иначе сумма пересчитывается в валюту мастерской по курсу, зафиксированному при первой загрузке заказа.
• Склад. Если позиция связана с изделием склада и его хватает, заказ встаёт в «Сборку заказа», остаток списывается один раз. При отмене остаток возвращается один раз. Заказ, пришедший уже выполненным, склад не списывает.
• Срок. Дата, до которой нужно передать заказ, попадает в карточку заказа, календарь и «Дела».

Действия на странице заказа

Все действия идут через очередь, результат и понятная подсказка при ошибке видны в «Журнале».

• «Собрать»: принимает заказ в Kaspi. Для Kaspi Доставки портал следом отмечает заказ собранным и передаёт число мест.
• Накладная: PDF накладной Kaspi Доставки.
• Отмена: причина выбирается из списка Kaspi («Отказ покупателя», «Не удалось связаться с покупателем», «Товара нет в наличии»), комментарий необязателен. Kaspi разрешает отмену только для принятого заказа, иначе вернёт ошибку, и её текст будет в журнале.

«Выдан»: завершение заказа в два шага

Kaspi закрывает заказ только по коду, который называет покупатель. Кнопка «Выдан» видна, когда заказ ждёт передачи или уже в доставке.

1. Шаг 1. Нажмите «Выдан», затем «Отправить код покупателю»: Kaspi отправит покупателю код в приложении. Появится сообщение «Код отправлен покупателю». Код можно отправить повторно.
2. Шаг 2. Покупатель называет код. Введите его (от 1 до 16 символов) и нажмите «Завершить заказ». Заказ закроется в Kaspi, а карточка перейдёт в «Выполнен» после очередной синхронизации.

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

7. Ограничения

• Остатки и цены обновляются раз в час, быстрее Kaspi не забирает.
• Списка ваших товаров у Kaspi получить нельзя: товары в портале связываются с изделиями вручную.
• Создать или изменить карточку товара нельзя: только в кабинете Kaspi.
• Завершить заказ можно только кодом покупателя.
• Отменить заказ можно только после того, как он принят.
• Живой кабинет Kaspi пока проверяется, первые заказы просматривайте внимательно.

8. Частые ошибки

9. Безопасность

• Токен хранится в зашифрованном виде и не показывается после сохранения.
• Ссылка прайс-листа содержит секрет: никому её не показывайте. «Новая ссылка» отзывает прежнюю.
• Код покупателя не сохраняется: после выполнения он стирается из записи журнала.
• Запись в Kaspi включается отдельно: по умолчанию портал только читает.
• Подключение можно поставить на паузу.
• Права: «Заказы площадок», «Товары на площадках», «Финансы площадок».

10. Изменения

• 26.10.2026 — первая версия инструкции.