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

Авторизация: токен вместо пароля

Официальная документация поддерживает Basic Auth и токен доступа. Для рабочей интеграции безопаснее использовать Bearer-токен, хранить его только в серверном секрет-хранилище и не передавать в браузер, логи или сообщения об ошибках.

GET https://api.moysklad.ru/api/remap/1.2/entity/product
Authorization: Bearer <access-token>
Accept-Encoding: gzip

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

Как читать большие объемы данных

Pagination

Коллекции возвращаются с метаданными size, limit и offset. Максимальный размер стандартной выборки — 1000 элементов. Надежный клиент должен переходить по nextHref или увеличивать offset до окончания выдачи.

Фильтрация

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

Expand и fields

expand заменяет ссылки связанными объектами, но разрешен только при размере выборки не более 100 и имеет максимальную глубину 3. Параметр fields также имеет ограничения; например, остатки в позициях документов можно запросить через fields=stock.

Лимиты и ошибка 429

Клиент должен читать служебные заголовки X-RateLimit-Limit, X-RateLimit-Remaining, X-Lognex-Reset и X-Lognex-Retry-After. При превышении лимита API возвращает HTTP 429. Ограничение параллельных запросов может вернуть код ошибки 1073.

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

Архитектура надежной синхронизации

1. Первичная загрузка. Постранично получить нужные сущности и сохранить их ID.
2. Инкрементальный цикл. Запрашивать изменения после последней подтвержденной контрольной точки.
3. Вебхуки. Использовать как быстрый сигнал, но не как единственный журнал истины.
4. Периодическая сверка. Повторно проверять измененные диапазоны, чтобы закрыть потерянные события.
5. Очередь обработки. Отделить получение события от медленных обращений во внешние системы.

Храните таблицу соответствий moysklad_id ↔ external_id. Поиск только по названию ненадежен: наименования меняются и могут повторяться.

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

• Перед созданием проверяйте сохраненное соответствие ID.
• Назначайте внешнему событию уникальный ключ идемпотентности в своей системе.
• Разделяйте retry для GET и POST: повтор POST без проверки результата способен создать дубль.
• При обновлении позиций документа учитывайте, что непереданные существующие позиции могут быть удалены.
• Логируйте HTTP-код, endpoint, внутренний correlation ID и код ошибки, но не токен и персональные данные.

Безопасность и эксплуатация

• Отдельный пользователь МойСклад с минимальными правами.
• Токен в secret manager или защищенной переменной окружения.
• Таймауты на соединение и ответ.
• Ограниченный retry с экспоненциальной задержкой.
• Очередь ошибок и возможность ручного повтора.
• Метрики 2xx/4xx/5xx, 429, длительности и отставания синхронизации.
• Тестовый контур до записи в рабочий аккаунт.

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

Вывод

Устойчивая интеграция — это контролируемый поток данных, а не набор вызовов API. Она знает, где остановилась, умеет безопасно повторить запрос, соблюдает лимиты и позволяет объяснить происхождение каждого документа.