Интеграция МойСклад с B2B-порталом: API, вебхуки и что передаётся
Содержание
МойСклад выбирают компании, которым нужен облачный товарный учёт без тяжёлой инфраструктуры. У него открытый API, поэтому подключить к нему B2B-портал заметно проще, чем к закрытой локальной базе. Но «проще» не значит «тривиально»: у API есть ограничения, у вебхуков свои особенности, а у оптовой логики свои требования, которых в МойСклад может не быть.
Разберём, как устроена интеграция, что передаётся и как сделать её надёжной.
Что даёт МойСклад для интеграции
- JSON API для работы с товарами, модификациями, контрагентами, заказами, документами, складами и отчётами;
- вебхуки: МойСклад сам сообщает внешней системе о создании, изменении или удалении объектов;
- отчёты об остатках по складам;
- типы цен и скидки, включая условия для отдельных контрагентов;
- печатные формы документов.
Актуальный перечень сущностей, параметров и ограничений описан в официальной документации API МойСклад. Перед проектированием стоит свериться с её текущей версией.
Что передаётся
| Данные | Направление | Механизм |
|---|---|---|
| Товары, модификации, комплекты | МойСклад → портал | API, вебхуки на изменения |
| Группы товаров и характеристики | МойСклад → портал | API |
| Типы цен и скидки | МойСклад → портал | API |
| Остатки по складам | МойСклад → портал | отчёт об остатках по расписанию и при изменениях |
| Контрагенты и договоры | МойСклад ↔ портал | API, вебхуки |
| Заказы покупателей | портал → МойСклад | API |
| Статусы заказов | МойСклад → портал | вебхуки |
| Отгрузки, счета | МойСклад → портал | API, печатные формы |
Вебхуки вместо постоянного опроса
Без вебхуков портал вынужден регулярно спрашивать МойСклад «что изменилось?». Это расходует лимиты API и даёт задержку. С вебхуками МойСклад сам отправляет уведомление, а портал забирает только изменённый объект.
Нюансы, которые нужно учесть:
- уведомление может прийти повторно или не прийти совсем, поэтому нужна защита от дублей и периодическая сверка;
- уведомление сообщает о факте изменения, а данные нужно запросить отдельно;
- обработчик вебхуков должен быть доступен постоянно и отвечать быстро, а тяжёлую обработку делать в фоне.
Лимиты API
У API МойСклад есть ограничения на количество запросов за период и на параллельные запросы. Все интеграции одного аккаунта делят общий лимит. Поэтому:
- портал не должен обращаться к МойСклад при каждом действии пользователя, он работает со своей копией данных;
- полная выгрузка каталога нужна только при первой загрузке и сверке;
- запросы приоритизируются: создание заказа важнее обновления описаний;
- при ошибке превышения лимита запрос повторяется с паузой.
Подробно эти ограничения разбираем в отдельной статье.
Персональные цены и условия дилеров
В МойСклад есть типы цен и механизмы скидок для контрагентов. Для портала важно:
- определить, какой тип цены и какие скидки применяются к каждому дилеру;
- рассчитывать цену на портале по тем же правилам или получать итог из МойСклад;
- проверять совпадение на реальных заказах до запуска.
Если правила сложнее, чем позволяет МойСклад (например, кредитные лимиты с согласованием или многоуровневые бонусы), эту часть логики реализуют в портале или интеграционном слое.
Остатки
Остатки по складам получают из отчётов. Для портала обычно нужно:
- показывать доступный остаток с учётом резервов;
- учитывать только склады, с которых идёт отгрузка дилерам;
- обновлять данные часто, но в пределах лимитов API;
- для дефицитных позиций проверять остаток в момент отправки заказа.
Заказ с портала в МойСклад
- Портал создаёт заказ покупателя с привязкой к контрагенту, договору и складу.
- Каждой операции присваивается уникальный ключ, чтобы повтор не создал дубль.
- МойСклад резервирует товар по своим правилам.
- Статусы заказа возвращаются на портал через вебхуки.
- Документы отгрузки и счета становятся доступны дилеру в кабинете.
- Ежедневная сверка проверяет, что все заказы портала есть в МойСклад с правильными суммами.
Связь с Битрикс24 и 1С
- Битрикс24: заказ с портала создаёт событие или сделку у менеджера, статусы из МойСклад обновляют CRM.
- 1С:Бухгалтерия: документы из МойСклад передаются в бухгалтерию, а взаиморасчёты для кабинета дилера берутся из 1С.
Если систем больше двух, все обмены лучше вести через один интеграционный слой, а не связывать каждую с каждой.
Сроки
| Этап | Ориентир |
|---|---|
| Каталог, цены, остатки на портале | несколько недель |
| Заказы и статусы | плюс несколько недель |
| Документы, лимиты, роли | 1-2 месяца |
| Связь с Битрикс24 и 1С | зависит от схемы |
Типовые ошибки интеграций с МойСклад
- портал запрашивает цены и остатки у МойСклад при каждом открытии страницы и упирается в лимиты;
- вебхуки обрабатываются синхронно, обработчик не успевает ответить, и уведомления теряются;
- нет сверки, и пропущенные изменения копятся неделями;
- контрагенты создаются и на портале, и в МойСклад без сопоставления;
- несколько сервисов подключены к аккаунту независимо и мешают друг другу.
Частые вопросы
Есть ли готовые модули для связки МойСклад и сайта?
Есть готовые интеграции для типовых интернет-магазинов. Для дилерского кабинета с персональными ценами, лимитами и документами обычно нужна своя интеграция.
Можно ли работать только через вебхуки?
Нет, нужна ещё регулярная сверка, потому что отдельные уведомления могут теряться.
Сколько времени занимает интеграция?
Базовый обмен каталогом, ценами, остатками и заказами занимает несколько недель. Полный контур с документами, лимитами и CRM дольше.
Что если каталог очень большой?
Нужна своя копия данных на стороне портала, обновление изменениями и планировщик запросов с учётом лимитов.
Можно ли показывать дилеру документы из МойСклад?
Да, через печатные формы документов, которые портал получает по API и показывает в кабинете.
