Kaspi.kz через API и MCP: без спецификации, с двухшаговым подтверждением и ценами, которые API не трогает

Обзор

У Kaspi Магазина есть API для продавца, и получить к нему доступ можно за одну минуту: кабинет продавца → Настройки → Токен API → «Сформировать». Никакой заявки, никакого ожидания — токен готов сразу и подставляется в каждый запрос заголовком X-Auth-Token.

А вот с документацией не всё так просто. У Kaspi нет OpenAPI-спецификации, нет Swagger, нет машиночитаемого контракта вообще. Есть guide.kaspi.kz — набор из полутора десятков страниц вида «Как с помощью API получить список моих заказов?», каждая с одним примером запроса и одним примером ответа. Собрать из этого полную картину пришлось постранично — и перепроверить независимым источником: рабочим Go-клиентом с открытым кодом, у которого случайно совпали все пути и параметры.

Mira подключает этот API целиком — 30 методов в шести разделах — и отдаёт его в Claude через MCP.

Что доступно продавцу

Ловушки, которые стоит знать заранее

Выдать заказ покупателю — это ДВА вызова, не один

У большинства статусов заказ переводится одним запросом: принять, скомплектовать, отметить прибытие. А вот «выдан» — особый случай. Первый вызов без кода отправляет покупателю код подтверждения прямо в приложение Kaspi.kz. Второй вызов, уже с этим кодом от покупателя, переводит заказ в статус «Выдан». Одностадийная логика, написанная по аналогии с остальными шестью статусами, здесь просто не сработает — заказ останется в подвешенном состоянии до звонка в поддержку.

Один и тот же адрес — шесть разных действий

Принять заказ, скомплектовать его, отметить возврат прибывшим, отменить — всё это один и тот же запрос, POST /v2/orders. Разница только в значении поля status внутри тела. Спутать здесь легче, чем кажется: опечатка в статусе не даст ошибку адреса, она молча переведёт заказ не туда.

Цену и остатки через API поменять нельзя

Это не пробел документации, а устройство площадки. Продавец публикует у себя XML- или YML-файл с ценами и остатками, указывает на него ссылку в кабинете — и Kaspi сам, раз в 30–60 минут, приходит и забирает файл. Push-метода, которым можно было бы отправить новую цену запросом, у Kaspi нет вовсе. Загрузка нового товара (product_import) публикует карточку — название, бренд, категорию, характеристики, — но без цены в фиде эта карточка не появится в продаже.

Нумерация страниц не одна на весь API

Список заказов нумеруется с нуля (page[number]=0 — первая страница), список отзывов — с единицы. Ни разу не названо явно рядом друг с другом — только сравнением двух страниц документации.

Модерация товара — не мгновенная

Загруженный товар не появляется в продаже сразу: до трёх рабочих дней на проверку. Узнать промежуточный статус можно отдельным запросом по коду загрузки — торопить нечем, только спрашивать снова.

Пять процентов отмен — граница, а не пожелание

Правила площадки жёстко связывают долю отменённых заказов с самой возможностью продавать: превышение отметки в 5% грозит приостановкой на неделю. Отмена через API — тот же счётчик, что и отмена руками в кабинете.

Как это выглядит через MCP

MCP — открытый протокол, по которому Claude подключается к внешним данным и действиям. Вместо написания клиента с нуля вы подключаете Kaspi в кабинете Mira одним токеном и спрашиваете обычными словами.

Какие новые заказы пришли за сегодня и что в них?

Claude сам сходит за списком заказов и, если нужно, за составом каждого — товар, количество, пункт выдачи.

Собрал заказ №12345 в три коробки, оформи накладную

Действие меняет статус заказа и требует явного разрешения на запись у источника — без него запрос к Kaspi не уйдёт вовсе, даже если модель попытается его составить.

Есть новые отзывы с низкой оценкой?

Список отзывов приходит с оценкой и текстом — без захода в кабинет.

Что защищено от случайного действия

Из 30 методов 11 меняют данные — статусы заказа, накладная, списание позиции, IMEI устройства, штрихкод товара, отмена, загрузка товара. Ни один из них не тратит деньги напрямую: комиссия Kaspi считается с суммы продажи, а не с обращения к API. Но это не делает их менее опасными — отмена заказа необратима и видна покупателю, а превышение доли отмен грозит приостановкой продаж. Барьер записи хранится не отдельным списком, а прямо в таблице вызовов рядом с адресом метода: разойтись им негде.

Что это даёт на практике

Продавцу. Обзор новых заказов и отзывов без захода в кабинет, обработка заказа без переключения между вкладками.

Разработчику. Готовый клиент вместо разбора трёх десятков FAQ-страниц вручную: собранные в одну таблицу 30 методов, разобранное двухшаговое подтверждение выдачи, известная граница с фидом цен.

Как подключить

1. Кабинет продавца Kaspi.kz → Настройки → Токен API → «Сформировать».
2. Скопировать токен.
3. В Mira: проект → источники → Kaspi Магазин → вставить токен.

Дальше Kaspi доступен и в чате Mira, и через MCP-сервер в Claude, Cursor или другом клиенте с поддержкой протокола.