Kaspi Магазин

Приложение Kaspi Магазин подключает кабинет продавца к Promto. Агент может читать заказы, состав заказов, точки выдачи, каталог категорий, отзывы и состояние импорта товаров, а после подтверждения — менять этап заказа, завершать выдачу по SMS-коду и запускать импорт карточек.

Подключение

1. Войдите в кабинет продавца Kaspi.
2. Откройте Настройки → API-токен.
3. Создайте токен. В кабинете это доступно пользователю с ролью Первый руководитель.
4. Скопируйте токен.
5. В Promto откройте Kaspi, нажмите Подключить и вставьте токен.
6. Дождитесь безопасной проверки чтением одного заказа.

Официальное описание методов находится в руководстве Kaspi Shop API. Подключать и отключать интеграцию может только владелец рабочего пространства. Токен хранится на сервере и не передаётся агенту.

Интерфейс приложения

На главном экране есть сценарии:

• Новые заказы — список заказов, ожидающих обработки;
• Состав заказа — позиции, товары и точка выдачи;
• Провести выдачу — принять, собрать, отметить прибытие и завершить заказ;
• Подключение — ввод или замена токена.

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

Работа с агентом

Основной агент использует инструмент promto_kaspi. Это встроенный инструмент чата, а не команда терминала.

Область	Действия инструмента
Заказы	list_orders, get_order_by_code
Состав и выдача	list_order_entries, get_entry_product, get_entry_pickup_point
Статусы	update_order_status, complete_order
Справочники	list_categories, list_category_attributes, get_category_attributes
Отзывы	list_reviews
Импорт товаров	get_import_schema, get_import_result, import_products, get_import_status
Дополнительный метод API	request

Суммы в заказах указаны в тенге (KZT). Ответ заказа не содержит полный состав: после заказа агент вызывает list_order_entries, а сведения о каждой позиции получает через get_entry_product.

Практические сценарии

Обработать новые заказы

Агент получает список, затем раскрывает состав каждого заказа отдельными вызовами. Если серверный фильтр статуса сработал неточно, прокси дополнительно фильтрует результат и отмечает это полем client_filtered.

Провести заказ по этапам

Перед каждым переходом агент показывает номер заказа и целевой статус. update_order_status выполняется с подтверждением. Допустимый переход зависит от текущего состояния Kaspi.

Завершить выдачу

complete_order — отдельный двухшаговый процесс:

1. step=send_code просит Kaspi отправить покупателю SMS-код;
2. step=confirm передаёт код, который покупатель продиктовал сотруднику.

Не просите агента угадывать код и не сохраняйте его после завершения операции.

Импортировать карточки

Сначала получите схему и справочники категории, проверьте JSON, затем явно подтвердите import_products. Код загрузки из ответа нужен для get_import_status.

Ограничения и безопасность

• Shop API не изменяет цены и остатки. Для них продавец размещает XML-прайс, который забирает Kaspi.
• Вебхуков для заказов нет: новые данные появляются при очередном опросе, а не мгновенно.
• update_order_status, complete_order и import_products требуют params.confirm=true после явного согласия.
• Статусный фильтр API может быть неточным; проверяйте поле client_filtered и фактические статусы строк.
• SMS-код принадлежит конкретной выдаче и покупателю. Не публикуйте его в общих каналах.
• Не передавайте API-токен в чат, файлы или параметры request.

Если не работает

Симптом	Что проверить
Заказ найден, но позиций нет	Вызвать list_order_entries, затем get_entry_product для каждой позиции
В списке лишние статусы	Ориентироваться на фактический статус и признак client_filtered
Нельзя изменить цену или остаток	Это ограничение Kaspi Shop API; обновите XML-прайс продавца
Завершение не проходит	Выполнены ли оба шага и введён ли SMS-код именно этого заказа
Импорт не виден	Сохранить код загрузки и проверить его через get_import_status
429 или 503	Учесть Retry-After, не запускать частые циклические повторы

Связанные материалы

• Настройки рабочего пространства
• Файлы — подготовка и проверка данных импорта
• Как получать лучший результат

Готовый промпт

Через promto_kaspi найди новые заказы за <ПЕРИОД>. Для каждого вызови list_order_entries и get_entry_product, затем покажи номер, состав, сумму в KZT и текущий статус. Ничего не меняй. Если фильтрация выполнялась на клиенте, явно укажи client_filtered.