Коротко
Официальная документация по Kaspi API живёт на guide.kaspi.kz в формате разрозненных вопросов-ответов: отдельная страница про токен, отдельная про список заказов, отдельная про статус. Собрать из этого рабочую картину интеграции с первого раза почти нельзя, поэтому здесь я свёл всё в один гайд: что реально умеет Merchant API, где у него дыры, чем закрывать остатки, какие есть опенсорс-библиотеки и как отдельно устроен приём денег через Kaspi Pay.
Сразу оговорка про терминологию. Под «Kaspi API» люди понимают две разные вещи. Первая — Merchant API маркетплейса: заказы, товары, цены в магазине на Kaspi.kz. Вторая — приём платежей через Kaspi Pay: QR, оплата по номеру, рассрочка. Это два разных контура с разной авторизацией и разными правилами. Путаница между ними — источник половины вопросов на форумах.
Merchant API: авторизация и формат запросов
Токен берётся в веб-кабинете продавца: Настройки → Токен API → Сформировать. Он не меняется сам по себе, его можно копировать повторно, и это удобно — не надо гонять OAuth-танцы. Токен уходит в заголовок X-Auth-Token. Дальше два обязательных заголовка: Accept: application/vnd.api+json и Content-Type: application/vnd.api+json. API построен по спецификации JSON:API, поэтому ответы приходят обёрнутыми в data, attributes, relationships — если вы привыкли к плоскому REST, первое время будете разворачивать эту матрёшку.
Источник: официальный guide.kaspi.kz по API магазина, снимок публичной страницы: июль 2026.
Тут прячется первая ловушка, о которой в гиде не пишут прямо. У Kaspi Pay токены живут час, у Merchant API токен постоянный. Не перепутайте: код, написанный под часовой токен с автообновлением, для магазина не нужен, а обратная ситуация — постоянный токен для платежей — просто не сработает.
Тестового окружения у Merchant API долгое время не было вообще. Команды, которые интегрировались в 2023–2024, отлаживались прямо на живых заказах реальных покупателей — об этом откровенно пишут на Habr в разборе интеграции интернет-магазина. Прежде чем открывать метод в прод, стоит хотя бы прогнать запросы через Postman или Insomnia и убедиться, что приходит 200, а не молчаливый 400 из-за забытого заголовка Content-Type.
Заказы: как это работает на самом деле
Основной поток — заказы. GET-запрос к списку принимает фильтры: состояние (state), статус, дата создания, тип доставки, пагинация. Дальше по коду конкретного заказа можно достать детали, позиции и адрес. Звучит просто, но на практике один заказ — это не один запрос.
Чтобы собрать полную карточку заказа, нужно 4+ обращения: сам заказ, его позиции (entries), коды товаров внутри позиций, адрес доставки. JSON:API вроде бы позволяет тянуть связанные сущности, но на деле приходится ходить по relationships руками. При потоке в сотни заказов это превращается в заметную нагрузку, и тут всплывает второй сюрприз — лимиты.
Изначально лимит был жёстким: 100 запросов в час. Для магазина с нормальными продажами это мгновенно упирается в потолок. Позже Kaspi поднял планку, но привычка «ходить в API экономно» осталась правильной: кешируйте справочники, не дёргайте статусы в цикле, разносите синхронизацию во времени. На больших распродажах таймауты стоит поднимать до 15–20 секунд — под пиковой нагрузкой Kaspi отвечает медленнее.
Отдельная боль — фильтр по статусу иногда врёт. Запрос заказов в статусе APPROVED_BY_BANK может вернуть заказы в ACCEPTED_BY_MERCHANT. Поэтому статус, пришедший в ответе, надо перепроверять на своей стороне, а не доверять фильтру вслепую. И ещё: в ответе по заказу нет вашего внутреннего SKU или артикула. Сопоставление «код Kaspi → товар в вашей системе» вы держите у себя, маппинг придётся вести самостоятельно.
Товары, цены и главная дыра — остатки
С товарами и ценами API работает: можно добавлять позиции, обновлять цены, обрабатывать карточки. А вот отдельного метода «изменить остаток на складе» в Kaspi Merchant API нет. Это не баг конкретной версии — это архитектурное решение, и оно ломает интуицию всем, кто приходил с других маркетплейсов.
Остатки и цены Kaspi забирает через фид — XML-файл по вашему URL, который платформа опрашивает раз в час. То есть остаток нельзя выставить точечным вызовом API; вы обновляете фид, а Kaspi подхватит изменения на следующем цикле. Час задержки создаёт классическую гонку: на сайте уже ноль, а маркетплейс ещё час принимает заказы на позицию, которой нет.
Что с этим делают на практике. Когда товар кончился, а обновление фида ещё не прошло, единственный рычаг — отменить заказ. Но отмены со стороны продавца Kaspi считает строго: если доля отмен переваливает за 5%, включаются санкции. Первое нарушение — блокировка продаж на 7 дней, второе — снова 7 дней, третье может закончиться разрывом партнёрства. Поэтому «отменять всё, чего нет» — прямой путь под блок. Правильнее держать буфер остатка, снимать позицию с продажи заранее (при остатке в 2–3 штуки), а не в ноль, и синхронизировать фид чаще внутренними средствами, чем раз в час.
Ещё нюанс: цена и остаток в фиде идут вместе. Обновить только остаток, не трогая цену, штатно не выйдет — они едут в одном файле. Мелочь, но она влияет на то, как вы строите выгрузку из учётной системы.
Опенсорс: не писать HTTP-клиент с нуля
Если пишете на Go, посмотрите на библиотеку abdymazhit/kaspi-merchant-api — MIT-лицензия, без внешних зависимостей, обёрнуты заказы, позиции, товары, атрибуты, отзывы, точки выдачи и города. Это не «весь Kaspi», а именно Merchant API маркетплейса, поэтому относиться к ней стоит как к community-реализации публичной поверхности. Даже если Go не ваш язык, README и структура файлов дают быструю карту эндпоинтов — видно, какие сущности вообще есть, и подтверждается, что метода на остатки среди них нет.
Ценность таких библиотек не в экономии пары дней. Они фиксируют форму ответов JSON:API и граничные случаи, на которые вы иначе наступите сами. Разворачивать data.attributes.relationships руками на каждый эндпоинт — скучно и легко ошибиться; готовая обёртка снимает эту рутину. Только не берите её как чёрный ящик: Kaspi меняет поля без громких анонсов, и слой между вами и API всё равно придётся иногда чинить.
Kaspi Pay: отдельная история про деньги
Merchant API — про заказы. Приём денег — это Kaspi Pay, и устроен он иначе. Прямое партнёрство с Kaspi по webpay даёт эквайринг, QR и оплату по номеру, но требует договора с банком, БИН/ИИН, расчётного счёта в казахстанском банке и верификации. Для крупного магазина это нормальный путь. Для небольшого проекта, где надо «принять оплату на сайте завтра», порог входа высокий.
Поэтому в Казахстане выросла прослойка сервисов-посредников, которые дают REST-обёртку над Kaspi Pay: выставить счёт по номеру телефона, получить вебхук об оплате, вернуть чек. Из тех, что на слуху, — apipay.kz, aipay.kz, kpayapp.kz; последний ещё умеет заводить оплату прямо из Bitrix24 и amoCRM. Смотрите на них как на отдельный договорный слой: до production-потока проверьте комиссии, сроки зачисления, стабильность вебхуков и юридическую модель.
Важная граница рынка: Kaspi Pay работает с картами и счетами казахстанских резидентов. Если у вас есть иностранные покупатели, один Kaspi Pay их не закроет — под международные карты нужен отдельный шлюз. Об этом стоит подумать на этапе архитектуры, а не когда первый зарубежный клиент упрётся в форму оплаты.
Связка с учётной системой: 1С, МойСклад, CRM
В реальном магазине Kaspi API редко живёт сам по себе. Он висит на учётной системе: 1С, МойСклад, или CRM вроде Bitrix24 и amoCRM. Логика простая: заказы из Kaspi падают в учёт, остатки и цены выгружаются из учёта в фид, статусы обновляются в обе стороны. Готовые модули под 1С и МойСклад существуют, и если ваш случай стандартный — коробка справится.
Кастом нужен там, где стандартная выгрузка ломается. Несколько кабинетов Kaspi на одно юрлицо, склады с разной логикой резерва, свои правила снятия с продажи, уведомления менеджеру в WhatsApp при низком остатке, сопоставление кодов Kaspi с внутренними артикулами — всё это коробочные модули тянут плохо. Здесь и начинается интеграционная разработка под Казахстан: аккуратный слой между Kaspi, учётной системой и мессенджерами, который учитывает и часовой фид, и лимит отмен, и вранье фильтра по статусу.
Если поверх заказов хочется автоматики — например, чтобы бот отвечал покупателю в WhatsApp по статусу заказа или подсказывал менеджеру, что позиция вот-вот кончится, — это уже GPT-интеграция поверх Kaspi API. В нашем проекте SellerBox AI как раз связывали данные маркетплейса с диалоговым слоем для продавцов, и там львиная доля работы ушла не в модель, а в укрощение этих самых API-нюансов.
С чего начать интеграцию
Не пытайтесь закрыть весь Kaspi API разом. Разумный порядок такой. Сначала — токен и один GET на список заказов, просто чтобы увидеть форму ответа JSON:API живьём. Потом — сбор полной карточки заказа со всеми 4+ вызовами и маппинг кодов на ваши товары. Дальше — выгрузка фида с ценами и остатками и проверка, что Kaspi его подхватывает. И только когда это стабильно — статусы, отмены с учётом лимита 5% и синхронизация в обе стороны.
Приём денег через Kaspi Pay ведите отдельным треком, не смешивая с Merchant API. Решите на старте: прямой договор эквайринга или сервис-посредник. От этого зависит и сложность, и сроки, и кто отвечает за фискализацию.
Если магазин уже теряет заказы из-за часовой задержки фида или ловит блокировки за отмены, начните с одного узкого места. Обычно самая быстрая польза — не «переписать всю интеграцию», а поставить буфер остатка и нормальную синхронизацию фида. Хотите, чтобы этот слой построили под вашу учётную систему и правила магазина — напишите нам про интеграцию под ключ, разберём ваш конкретный кабинет.
FAQ
Где взять токен для Kaspi Merchant API?
В веб-кабинете продавца: Настройки → Токен API → Сформировать. Токен постоянный, обновлять по расписанию его не нужно — он уходит в заголовок X-Auth-Token. Не путайте с токенами Kaspi Pay, которые живут час.
Почему в Kaspi API нет метода для остатков?
Так устроена платформа: остатки и цены Kaspi забирает из фида — XML-файла, который опрашивает раз в час, а не через прямой вызов API. Точечно выставить остаток нельзя, поэтому магазины держат буфер и снимают позицию с продажи заранее.
Можно ли отменять заказы, если товара нет?
Технически да, но осторожно. Отмены со стороны продавца Kaspi ограничивает: при доле выше 5% — блокировка продаж на 7 дней, при повторах вплоть до разрыва партнёрства. Лучше не доводить остаток до нуля, чем отменять постфактум.
Чем Kaspi Pay отличается от Merchant API?
Merchant API — про заказы, товары и цены на маркетплейсе. Kaspi Pay — про приём денег: QR, оплата по номеру, рассрочка. Разная авторизация, разные правила, разные договоры. Их часто путают, но интегрировать нужно как два отдельных контура.
Есть ли готовые библиотеки под Kaspi API?
Да. Для Go есть опенсорс abdymazhit/kaspi-merchant-api (MIT), покрывающий заказы, товары, атрибуты и справочники Merchant API. Для приёма платежей есть сервисы-посредники вроде apipay.kz, aipay.kz, kpayapp.kz с REST-обёрткой над Kaspi Pay.