Интеграция МойСклад с сайтом через API: товары, остатки, цены и заказы

Когда товары, остатки и заказы живут одновременно на сайте и в МоемСкладе, ручное обновление быстро становится источником ошибок. Менеджер меняет цену в одной системе, склад — остаток в другой, а интернет-магазин продолжает показывать старые данные.

Эта статья полезна владельцам интернет-магазинов и компаниям, которым нужна интеграция МойСклад с сайтом через API. Разберём, какие данные лучше синхронизировать, где хранить соответствия ID, как избежать дублей и почему двусторонний обмен нужно проектировать как несколько независимых потоков, а не как один большой cron-скрипт.

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

Что можно автоматизировать между сайтом и МоимСкладом

Официальный сайт для разработчиков МоегоСклада приводит типовые примеры JSON API: выгружать заказы с самописного сайта, обновлять каталог, цены и остатки. На практике интеграцию лучше разделять на конкретные потоки.

Сначала определяем источник истины

У каждой сущности должен быть хозяин. Например, карточка товара и остаток редактируются в МоемСкладе, описание для SEO — в WordPress, а заказ создаётся на сайте и затем передаётся в учётную систему.

• название и артикул — МойСклад;
• цена — МойСклад;
• остаток — МойСклад;
• SEO-текст и контент — WordPress;
• первичный заказ — сайт;
• статус исполнения — МойСклад.

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

Авторизация в JSON API

Для работы с API секреты должны храниться на сервере. В официальной документации для решений МойСклад показан доступ к JSON API 1.2 с Bearer-токеном в заголовке Authorization. Точный способ выдачи доступа зависит от сценария интеграции и типа решения, но правило безопасности одинаковое: токен не должен попадать в frontend-код, публичный репозиторий или URL.

curl --request GET   "https://api.moysklad.ru/api/remap/1.2/entity/product"   --header "Authorization: Bearer ACCESS_TOKEN"   --header "Accept: application/json"

На сайте такой запрос выполняется серверной частью: WordPress-плагином, отдельным backend или worker-сервисом. Браузер пользователя не должен напрямую обращаться к МоемСкладу с постоянным токеном.

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

Название меняется. Артикул тоже может меняться, а иногда вообще не уникален. Поэтому интеграции нужен устойчивый идентификатор соответствия между объектом сайта и объектом МоегоСклада.

После первого сопоставления удобно сохранять внешний ID рядом с товаром сайта. При следующей синхронизации алгоритм уже не ищет «такой же товар», а обновляет конкретную связанную запись.

{
  "site_product_id": 1254,
  "moysklad_id": "EXTERNAL_ENTITY_ID",
  "last_sync_at": "2026-09-05T12:00:00Z"
}

Если импорт может запускаться повторно, такая связка становится основой идемпотентности: один и тот же объект обновляется, а не создаётся заново.

Как синхронизировать каталог без дублей

1. получить порцию товаров из API;
2. проверить таблицу соответствий ID;
3. если связь есть — обновить разрешённые поля;
4. если связи нет — попытаться безопасно сопоставить товар по заранее определённому ключу;
5. если сопоставление однозначно — сохранить внешний ID;
6. если нет — создать товар или отправить запись на ручную проверку;
7. зафиксировать результат синхронизации.

Опасный подход — при каждом cron-запуске искать товар только по названию и создавать новый при несовпадении. Одно изменение заголовка способно породить дубль.

Остатки: сначала бизнес-правило, потом API

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

• какие склады влияют на интернет-магазин;
• нужно ли суммировать остатки;
• учитывается ли резерв;
• можно ли оформить заказ при нуле;
• нужно ли скрывать товар или менять только статус наличия;
• как быстро изменения должны попадать на сайт.

Только после этого выбирается конкретный ресурс API и формула преобразования данных в состояние товара на сайте.

Цены: не перезаписывайте всё одним числом

У товара могут быть разные типы цен, скидочные сценарии или специальные условия. Интеграция должна знать, какую именно цену считать розничной для сайта и что делать с акционной ценой WordPress или WooCommerce.

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

Передача заказов с сайта в МойСклад

Для заказов важнее всего защита от повторной отправки. Платёжный webhook, повтор cron или ручной запуск не должны создавать два Заказа покупателя для одного заказа сайта.

1. заказ на сайте получает стабильный внутренний ID;
2. перед отправкой проверяется, есть ли уже ID объекта МоегоСклада;
3. если нет — создаётся объект через API;
4. полученный внешний ID сохраняется в заказе сайта;
5. повторная задача при наличии ID выполняет обновление или завершается без создания дубля.

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

Polling или webhooks

Не все данные нужно опрашивать каждую минуту. Где API и права конкретного сценария позволяют использовать webhooks, событие может запускать точечную обработку. Для периодической сверки каталога или восстановления после пропущенных событий всё равно полезен плановый процесс.

Для бизнес-критичной синхронизации гибрид часто надёжнее: webhook ускоряет реакцию, а плановая сверка исправляет расхождения, если событие было пропущено или временно не обработалось.

Лимиты API и повторные попытки

Официальная документация указывает, что у JSON API есть ограничения на количество запросов, а в ответах API используются служебные заголовки rate limit и retry. Поэтому интеграция не должна бесконечно отправлять запросы в цикле.

• валидационная ошибка — запись отправляется на разбор, бессмысленный retry не делается;
• ошибка авторизации — синхронизация останавливается до исправления доступа;
• временная ошибка или ограничение частоты — задача повторяется позже;
• сетевой timeout — повтор допускается только для идемпотентной операции или после проверки результата.

Интервал повтора лучше определять по ответу API и backoff, а не фиксированным бесконечным циклом.

Нужна ли очередь

Для маленького каталога иногда достаточно cron. Но если одновременно обновляется много объектов или передаются заказы, очередь делает систему устойчивее: каждая задача имеет статус, число попыток и последнюю ошибку.

• нужно продолжить после временного падения API;
• важно не блокировать оформление заказа долгим внешним запросом;
• есть несколько типов синхронизации;
• нужен журнал, что реально ушло и что не ушло;
• нужно безопасно повторять задачи.

В более сложных процессах такая интеграция становится частью автоматизации бизнес-процессов, где сайт, склад, CRM и уведомления работают как одна цепочка.

Что логировать

• тип операции;
• ID объекта сайта;
• ID объекта МоегоСклада;
• время начала и окончания;
• HTTP status;
• код или краткое сообщение ошибки;
• номер попытки;
• результат: created, updated, skipped или failed.

Токены, пароли и полные заголовки Authorization в логах хранить нельзя.

Как интегрировать МойСклад с WooCommerce

Для WooCommerce удобно разделить слой магазина и слой интеграции. WooCommerce отвечает за карточки, корзину и заказ, а интеграционный модуль — за соответствие внешних ID, очередь и обмен с API.

1. товар в МоемСкладе изменился;
2. задача синхронизации получает товар по внешнему ID;
3. обновляет разрешённые поля товара WooCommerce;
4. покупатель оформляет заказ;
5. после нужного события заказ ставится в очередь на передачу;
6. МойСклад возвращает внешний ID созданного объекта;
7. этот ID сохраняется в WooCommerce и используется дальше.

Если вместе с интеграцией требуется доработка каталога, карточек или логики заказа, имеет смысл рассматривать задачу как единый проект разработки WooCommerce, а не как изолированный скрипт.

Когда готовый коннектор лучше кастомной интеграции

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

• особое сопоставление товаров;
• несколько складов с собственной формулой доступности;
• нестандартный набор цен;
• фильтрация заказов перед отправкой;
• обмен с дополнительной CRM или сервисом;
• собственная очередь и контроль ошибок;
• специальная логика статусов.

Когда лучше выбрать другой вариант

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

Также не стоит писать собственный слой API, если бизнес-процесс полностью покрывается готовым поддерживаемым решением и нет требований, которые заставят постоянно обходить его ограничения.

С чего начать интеграцию

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

Если нужно связать сайт с МоимСкладом под конкретный процесс, можно описать задачу A.S Groups: какая CMS используется, какие данные должны идти в каждую сторону и что сейчас обновляется вручную.

Официальные источники

• МойСклад для разработчиков
• Документация JSON API 1.2
• Vendor API и доступ решений к JSON API