Этапы интеграции через API: подключение, настройка, синхронизация

Любая интеграция с МойСклад проходит три этапа: подключение, настройка и синхронизация. Пропуск любого из них оборачивается дублями, рассинхроном остатков или блокировкой по лимитам. Разберём этапы с точки зрения разработчика JSON API 1.2.

Этап 1. Подключение и авторизация

Работа начинается с доступа к API по адресу https://api.moysklad.ru/api/remap/1.2. МойСклад поддерживает два способа авторизации:

• Basic-аутентификация — заголовок Authorization: Basic <base64(login:password)>, подходит для быстрых интеграций;
• Bearer-токен — получается через POST /security/token и передаётся как Authorization: Bearer <token>. Предпочтителен: не хранит пароль и легко отзывается.

Обязательно добавляйте заголовки Accept-Encoding: gzip для сжатия и Content-Type: application/json. Первый «здоровый» запрос — GET /entity/organization: он подтверждает, что доступ есть и аккаунт активен.

Этап 2. Настройка и маппинг

Второй этап — согласование моделей данных. У сайта, CRM и МойСклад разные справочники, и их нужно связать. Маппинг строится на устойчивых идентификаторах, а не на названиях.

Что сопоставляем в первую очередь:

Ключевой приём — использовать поле externalCode: в него пишут идентификатор внешней системы, что позволяет находить сущность без хранения href на своей стороне. Для служебных данных подходят пользовательские атрибуты из metadata.

Этап 3. Начальная выгрузка

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

1. Считать справочники: GET /entity/product?limit=1000&offset=0 с перебором offset;
2. Развернуть связанные объекты через expand, например ?expand=productFolder,uom;
3. Создавать/обновлять сущности пакетами через массовый POST /entity/product (до 1000 объектов в теле).

Результат этапа — заполненные справочники и построенная таблица соответствий, на которую опирается дальнейший инкремент.

Этап 4. Инкрементальная синхронизация

Дальше обмен идёт только по изменениям. Есть два подхода, которые обычно комбинируют:

• Вебхуки — реакция в реальном времени через POST /entity/webhook на события CREATE/UPDATE/DELETE;
• Периодическая выборка — фильтр по времени изменения: filter=updated>=2026-07-16 10:00:00 как страховка на случай пропущенных вебхуков.

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

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

Лимиты, ошибки и повторы

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

Тело ошибки содержит массив errors с полями error и code — их полезно логировать целиком. Очередь заданий с повторными попытками превращает разовые сбои в незаметные задержки.

Мониторинг и сопровождение

Интеграция — живой процесс: меняются справочники, тарифы, схемы данных. Чтобы поломки не всплывали как «пропали остатки на сайте», закладывают наблюдаемость:

• журнал каждого обмена с кодом ответа и телом ошибки;
• метрики: лаг синхронизации, доля 429, число повторов;
• алерты при росте ошибок или остановке вебхуков;
• регулярная полная сверка (например, ночью) как страховка инкремента.

На 1С-Битрикс это удобно реализовать через агентов или очередь с логированием в отдельную таблицу — тогда сопровождение опирается на факты, а не на жалобы пользователей.

Итог

Успешная интеграция с МойСклад проходит по этапам: подключение (токен и доступ), настройка (маппинг по externalCode и атрибутам), начальная выгрузка пакетами и инкрементальная синхронизация через вебхуки с обработкой лимитов и ошибок. Пропуск любого этапа возвращается техническим долгом.

Мы в B2Bsite проходим этот путь под ключ: проектируем модель обмена, реализуем устойчивый коннектор на 1С-Битрикс и берём его на поддержку с мониторингом и сверками. Если интеграцию нужно выстроить корректно с первого раза — поможем.