B2BPRO.KZ | Рекламное агентство в Алматы

Выгрузка товаров WooCommerce в Kaspi Магазин через XML-прайс: настройка и частые ошибки

Обложка: Остатки на Kaspi без ручных таблиц. Синие коробки с товаром, лист прайса и линия к витрине с зеленой галочкой, выгрузка WooCommerce в Kaspi

Выгрузить товары WooCommerce в Kaspi Магазин можно без ручного Excel: сайт формирует XML-прайс в формате kaspi_catalog, файл лежит по постоянной ссылке, а Kaspi сам забирает его в режиме автоматической загрузки. Чаще всего ломаются три вещи: артикулы, коды складов и устаревший файл, который отдает кэш сайта.

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

Как работает выгрузка WooCommerce в Kaspi через XML-прайс

Схема простая: WooCommerce собирает данные о товарах в XML-файл, файл доступен по ссылке на вашем сервере, а Kaspi периодически его перечитывает. XML-прайс (прайс-лист Kaspi) это файл, в котором продавец передает Kaspi артикул, название, бренд, цену и наличие каждого товара на каждом складе.

По инструкции Kaspi по автоматической загрузке прайс-листа порядок такой:

  1. Подготовить http или https сервер. Для магазина на WordPress это обычно тот же хостинг, где работает сайт.
  2. Разместить на сервере XML-файл и скопировать ссылку на него.
  3. В веб-версии кабинета продавца открыть «Товары → Загрузить прайс-лист → Автоматическая загрузка» и вставить ссылку.
  4. Настроить учетную систему (в нашем случае WooCommerce) так, чтобы она сама обновляла файл.

Дальше Kaspi обращается к ссылке сам: по данным справки, система загружает прайс-лист каждые 60 минут, если в нем есть изменения. Значит, файл на сайте должен обновляться не реже, иначе вы сами создаете задержку между складом и витриной Kaspi.

Excel-шаблон тоже существует, но у него есть ограничения. По описанию прайс-листа в справке Kaspi таблица поддерживает до пяти складов с колонками PP1-PP5 и не подходит, если у вас разные цены или сроки предзаказа по городам. Для магазина, у которого все данные уже живут в WooCommerce, XML удобнее: его можно генерировать автоматически, без участия менеджера.

Чем отличаются способы выгрузки товаров в Kaspi Магазин

Выбор способа зависит от размера каталога и от того, как часто меняются цены и остатки. Ниже сравнение вариантов, которые мы встречаем у магазинов на WooCommerce.

Способ Как обновляются данные Когда подходит Главный риск
Excel-шаблон вручную Менеджер выгружает и загружает файл сам Десятки товаров, редкие изменения Остатки устаревают между загрузками
XML-файл вручную Файл формируется на сайте, загружается через «Загрузить вручную» Проверка формата перед запуском автозагрузки Тот же человеческий фактор
XML по ссылке, универсальный плагин фидов Плагин пересобирает файл по расписанию Простой каталог без вариаций и нескольких складов Шаблон фида приходится подгонять под kaspi_catalog
XML по ссылке, собственный модуль Код на сайте собирает файл из WooCommerce по расписанию Вариации, несколько складов, разные цены по городам Нужна поддержка при обновлениях WooCommerce

Отдельного официального плагина Kaspi для WooCommerce в каталоге WordPress мы не нашли. Встречаются универсальные генераторы XML-фидов и платежные модули для Kaspi Pay, но платежный модуль к прайс-листу отношения не имеет. Если вам нужно именно принимать оплату на сайте, это отдельная задача, о ней мы писали в статье как подключить оплату Kaspi к интернет-магазину на WordPress.

Какая структура у XML-прайса Kaspi

Файл строится вокруг корневого элемента kaspi_catalog, внутри которого лежат данные о компании и список предложений offers. Каждый товар это отдельный элемент offer с атрибутом sku. Подробный пример и XSD-схему Kaspi публикует в разделе «Как загрузить прайс-лист» в Kaspi Гиде, сверяйтесь с ним перед запуском.

Упрощенный пример для одного товара с двумя складами (значения условные, только для иллюстрации):

<?xml version="1.0" encoding="utf-8"?>
<!-- атрибуты xmlns:xsi и xsi:schemaLocation скопируйте из примера Kaspi -->
<kaspi_catalog date="string" xmlns="kaspiShopping">
  <company>Название магазина</company>
  <merchantid>ВАШ_ID</merchantid>
  <offers>
    <offer sku="KT1001BLK">
      <model>Чайник электрический 1,7 л черный</model>
      <brand>BrandName</brand>
      <availabilities>
        <availability available="yes" storeId="PP1" stockCount="12"/>
        <availability available="no" storeId="PP2"/>
      </availabilities>
      <price>15990</price>
    </offer>
  </offers>
</kaspi_catalog>

Что означают ключевые поля по справке Kaspi:

  • sku: артикул товара в системе продавца. Допустимы цифры и латинские буквы, длина до 20 символов, артикул должен быть уникальным в пределах прайс-листа.
  • model и brand: название и бренд товара.
  • availability: наличие на конкретном складе. Атрибут available принимает yes или no, storeId это код склада из раздела «Склады и магазины» в кабинете, stockCount передает остаток.
  • preOrder: срок предзаказа в днях, максимум 30. Если предзаказ не нужен, атрибут не передают.
  • price: цена, одинаковая для всех городов. Если цены различаются, вместо нее используют блок cityprices с элементами cityprice и атрибутом cityId (код города).

Цена указывается с НДС, целым числом, без пробелов, десятичных знаков и символа валюты. Запись вида «15 990 тг» или «15990.00» файл испортит.

Как сопоставить поля WooCommerce с полями Kaspi

Почти все данные для прайса в WooCommerce уже есть, их нужно правильно разложить по элементам XML. Ниже соответствие, которое мы используем как отправную точку на проектах.

Элемент Kaspi Откуда брать в WooCommerce На что обратить внимание
offer sku Поле «Артикул» на вкладке «Запасы» Только латиница и цифры, до 20 символов, без пустых значений
model Название товара или вариации Для вариаций добавлять цвет или размер, иначе карточки совпадут
brand Атрибут или таксономия бренда В WooCommerce бренд часто не заполнен, это нужно проверить заранее
price Обычная цена или цена распродажи Решить, какую цену отдавать на Kaspi, и округлить до целого
availability stockCount Количество на складе при включенном управлении запасами Без управления запасами остаток не передать
storeId В стандартном WooCommerce такого поля нет Код склада задается в настройках выгрузки или в мета-поле

Артикул, цена и остатки в WooCommerce задаются в блоке «Данные товара», это описано в документации WooCommerce по управлению товарами. У вариативного товара у каждой вариации свой артикул и свой остаток, и в прайс Kaspi должна уходить именно вариация, а не родительский товар. Родитель без цены и остатка в файле только создаст лишнюю нераспознанную позицию.

Отдельный вопрос это цена. Многие магазины держат на Kaspi цену выше, чем на сайте, чтобы покрыть комиссию площадки. Тогда цену для Kaspi удобнее хранить в отдельном поле товара или считать по формуле при генерации файла. Главное, чтобы правило было записано и одинаково работало для всего каталога, иначе через месяц никто не вспомнит, почему чайник на Kaspi стоит дороже на 7%.

Как настроить генерацию файла на сайте

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

Порядок настройки на проектах B2BPRO.KZ обычно такой:

  1. Привести в порядок артикулы: найти пустые, дубли, кириллицу, пробелы, дефисы и значения длиннее 20 символов.
  2. Включить управление запасами для товаров, которые продаются на Kaspi, и проверить остатки.
  3. Создать склады в кабинете Kaspi и выписать их коды из раздела «Склады и магазины».
  4. Решить, какие товары уходят на Kaspi: весь каталог, отдельные категории или товары с отметкой. Удобно завести для этого отдельный флажок в карточке.
  5. Настроить плагин фидов под формат kaspi_catalog или написать собственный модуль выгрузки.
  6. Сохранить файл по постоянному адресу, например /kaspi/price.xml, и проверить его в браузере.
  7. Один раз загрузить файл вручную через «Товары → Загрузить прайс-лист → Загрузить вручную» и разобрать замечания.
  8. Только после этого вставить ссылку в раздел «Автоматическая загрузка».

Собственный модуль обычно занимает несколько десятков строк кода. Товары выбираются штатной функцией WooCommerce wc_get_products, вариации разворачиваются, тексты экранируются для XML, и результат записывается во временный файл, который затем подменяет рабочий. Подмена через временный файл важна: если Kaspi придет за прайсом в момент записи, он получит либо старую полную версию, либо новую, а не обрывок.

Перед тем как отдавать ссылку в кабинет, проверьте сам файл. Откройте его в браузере: если в XML есть синтаксическая ошибка, браузер покажет сообщение с номером строки вместо дерева элементов. Затем пройдитесь по нескольким товарам выборочно и сравните цену и остаток в файле с карточкой в админке WooCommerce. На этом этапе обычно и всплывают вариации без артикула, товары с ценой распродажи, которая закончилась месяц назад, и категории, которые попали в выгрузку случайно.

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

Расписание в WordPress чаще всего строят на WP-Cron. По документации WordPress о WP-Cron задачи запускаются при посещении сайта, а не строго по часам. Ночью, когда посетителей мало, файл может не обновляться часами. Для выгрузки в Kaspi лучше отключить запуск по посещениям и вызывать задачу системным cron хостинга, например раз в 30 минут.

Если вы не хотите собирать это сами, наша команда разработки сайтов делает выгрузку WooCommerce в Kaspi под ключ: от чистки артикулов до проверки первой автоматической загрузки.

Почему товары не появляются на Kaspi после загрузки

Чаще всего товар загружен, но Kaspi не смог сопоставить его с карточкой каталога. По справке Kaspi такие позиции попадают в «Нераспознанные товары → Без привязки», и вывести их на продажу нужно вручную. При первом запуске так бывает почти всегда, и с самой выгрузкой это обычно не связано.

Остальные причины по нашему опыту распределяются так:

  • Неверный storeId. В файле стоит код склада, которого нет в кабинете, или склад переименовали после настройки выгрузки.
  • Цена в неправильном формате. Копейки, пробелы, символ валюты или пустое значение у вариации без цены.
  • Нет ни одного склада со значением yes. Остаток на сайте ноль или управление запасами выключено, и модуль ставит available=»no» везде.
  • Неэкранированные символы. Амперсанд или кавычки в названии ломают XML, и файл не читается целиком.
  • Слишком длинный или кириллический артикул. WooCommerce принимает почти любой артикул, Kaspi нет.

Есть и обратная ситуация. По справке, товар, который раньше загружался или добавлялся вручную, нужно включать в прайс-лист, иначе он будет снят с продажи. Поэтому фильтр «выгружать только категорию X» стоит проверять особенно внимательно: случайно исключенная категория быстро исчезнет с витрины.

Частые ошибки автоматической загрузки и как их найти

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

  1. Ссылка открывается снаружи. Откройте адрес файла в браузере в режиме инкогнито и с мобильного интернета. Если требуется вход, пароль на каталог или срабатывает заглушка режима обслуживания, Kaspi файл не получит.
  2. Защита не блокирует робота. Плагины безопасности, файрвол хостинга и сервисы защиты от ботов иногда отдают автоматическим запросам страницу проверки вместо XML. Адрес прайса лучше добавить в исключения.
  3. Кэш не отдает старую версию. Плагины кэширования и CDN могут сохранить XML как страницу и раздавать вчерашние остатки. Исключите путь к файлу из кэша.
  4. Файл действительно обновляется. Посмотрите дату изменения файла на сервере и атрибут date в kaspi_catalog. Если время не меняется, не работает расписание.
  5. Сертификат в порядке. Для https-ссылки истекший или неполный SSL-сертификат может помешать загрузке, хотя браузер иногда показывает такой сайт без предупреждений.
  6. Кодировка UTF-8. Файл в другой кодировке превращает русские названия в набор символов.

Результат ручной загрузки Excel-файла справка предлагает смотреть в разделе «Товары → История загрузок» на вкладке «Обработано». Для XML удобнее всего начинать с той же ручной загрузки: так вы сразу видите, принял ли Kaspi файл, прежде чем подключать автоматику.

Отдельная история связана с обновлениями. После обновления WooCommerce, темы или плагина фидов выгрузка может тихо перестать работать, а Kaspi продолжит показывать последний успешно загруженный прайс. Помогает простой контроль, например скрипт, который раз в сутки проверяет дату изменения файла и шлет уведомление, если она старше двух часов.

Несколько складов и разные цены по городам

Если у магазина склады в разных городах, XML дает больше возможностей, чем Excel. По справке Kaspi разные цены и сроки предзаказа для складов задаются только в XML, причем такие склады должны находиться в разных городах. Для складов в одном городе действуют единая цена и единый срок предзаказа.

На практике это означает, что в WooCommerce нужно хранить остатки по каждому складу отдельно. Стандартный WooCommerce ведет один общий остаток, поэтому для нескольких складов используют плагин складского учета или получают остатки из учетной системы. Если остатки ведутся в 1С, иногда проще формировать прайс прямо там: справка Kaspi прямо упоминает, что Excel и XML можно формировать в 1С. Тогда сайт и Kaspi получают данные из одного источника и не спорят между собой.

Цены по городам задаются блоком cityprices, где у каждого элемента cityprice указан код города cityId. Коды городов можно получить через API Kaspi. Ошибка в коде города не всегда очевидна: товар загрузится, но цена будет действовать не там, где вы ожидали.

Что делать с заказами Kaspi после настройки выгрузки

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

Для таких магазинов мы связываем Kaspi с CRM, чтобы заказы с площадки и с сайта попадали в одну воронку с ответственным менеджером. Что делать, если такая связка перестала работать, мы разбирали в статье о том, почему заказы Kaspi перестали попадать в Битрикс24. Когда работают и прайс, и CRM, остатки на сайте и на Kaspi совпадают, и руководитель видит каждый заказ.

Перед запуском полезно сделать короткую проверку на 10-20 товарах из разных категорий, включая вариативные. Загрузите их файлом вручную, убедитесь, что карточки привязались, цены совпали, а остатки списываются. Только потом расширяйте выгрузку на весь каталог и включайте автоматическую загрузку. Так ошибки в формате всплывают на десятке позиций, а не на всей витрине магазина.

Частые вопросы

Есть ли готовый плагин для выгрузки WooCommerce в Kaspi?

Официального плагина Kaspi для WooCommerce в каталоге WordPress мы не нашли. Можно настроить универсальный плагин XML-фидов под формат kaspi_catalog или написать собственный модуль выгрузки. Для простого каталога подойдет первый вариант, для вариаций, нескольких складов и разных цен по городам надежнее собственный модуль.

Как часто Kaspi обновляет товары из XML-прайса по ссылке?

По справке Kaspi при автоматической загрузке система забирает прайс-лист каждые 60 минут, если в нем есть изменения. Поэтому файл на сайте должен пересобираться не реже раза в час, лучше чаще. Если расписание построено на WP-Cron, ночью оно может срабатывать с задержками, и системный cron хостинга работает стабильнее.

Почему товар загрузился, но не продается на Kaspi?

Чаще всего Kaspi не смог привязать товар к карточке каталога, и позиция попала в раздел «Нераспознанные товары → Без привязки». Ее нужно вывести на продажу вручную. Также проверьте код склада storeId, формат цены без копеек и пробелов и то, что хотя бы на одном складе стоит available=»yes».

Можно ли использовать артикулы WooCommerce как sku для Kaspi?

Можно, если они соответствуют требованиям Kaspi: только цифры и латинские буквы, длина до 20 символов, уникальность в пределах прайс-листа. WooCommerce принимает почти любые артикулы, поэтому перед запуском стоит найти пустые, дублирующиеся, кириллические и слишком длинные значения и исправить их.

Прокрутить вверх