API интеграции служб доставки в МойСклад

У МойСклад нет отдельного «Delivery API» — интеграция службы доставки собирается из общих сущностей JSON API 1.2 и вебхуков. Разработчику нужно связать заказ покупателя, отгрузку и статусы доставки с личным кабинетом перевозчика, обеспечив двусторонний обмен трек-номерами и состояниями.

Модель интеграции доставки

Отправной точкой служит заказ покупателя customerorder: в нём фиксируются позиции, адрес и выбранная служба доставки. Факт передачи товара перевозчику отражается отгрузкой demand, а статусы заказа моделируются состояниями (state) и дополнительными полями (attributes).

Связка «МойСклад ⇄ перевозчик» обычно строится как коннектор, который:

• читает новые заказы в статусе «готов к отправке» через JSON API или вебхук;
• создаёт отправление в API службы доставки (СДЭК, Boxberry, Почта России и т. п.);
• записывает трек-номер обратно в заказ МойСклад в дополнительное поле;
• принимает статусы от перевозчика и обновляет состояние заказа.

Дополнительные поля для логистики

Стандартной модели заказа не хватает реквизитов доставки, поэтому их выносят в пользовательские атрибуты. Атрибуты создаются в метаданных сущности и доступны через GET /entity/customerorder/metadata/attributes.

Практичный набор доп. полей заказа для доставки:

Значение атрибута обновляется через PUT /entity/customerorder/{id} с массивом attributes, где каждый элемент ссылается на meta атрибута и несёт value.

Вебхуки вместо опроса

Постоянно опрашивать API невыгодно из-за лимита 45 запросов за 3 секунды. Правильнее подписаться на вебхуки: МойСклад сам уведомит коннектор об изменениях. Вебхук регистрируется через POST /entity/webhook.

Пример подписки на обновление заказа покупателя:

{ "url": "https://connector.example.ru/ms/hook", "action": "UPDATE", "entityType": "customerorder" }

• CREATE — появился новый заказ, можно резервировать слот доставки;
• UPDATE — сменился статус или доп. поле;
• DELETE — заказ удалён/отменён, отменяем отправление.

Синхронизация статусов

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

1. Получить список состояний: GET /entity/customerorder/metadata → блок states;
2. Построить таблицу соответствия «статус перевозчика → href состояния»;
3. При событии от перевозчика вызвать PUT /entity/customerorder/{id} с новым state.

Пример типового соответствия статусов:

Отгрузка и списание остатков

Когда товар физически уходит перевозчику, создаётся отгрузка demand на основании заказа. Отгрузка списывает остатки со склада и связывается с заказом через поле customerOrder. Это фиксирует движение товара и корректирует резерв.

Порядок действий коннектора при передаче в доставку:

• создать отправление в API перевозчика и получить трек-номер;
• записать трек в доп. поле заказа;
• создать demand по позициям заказа (или его части при частичной отгрузке);
• перевести заказ в состояние «Передан в доставку».

Отказоустойчивость коннектора

Логистические API нестабильны: перевозчик может ответить таймаутом или 5xx, а лимиты МойСклад блокируют всплески. Устойчивый коннектор строится на очереди и повторных попытках.

• Очередь заданий — вебхук лишь ставит задачу, обработка идёт асинхронно;
• Ретраи с backoff — на ответы 429 и 5xx повторяем с растущей паузой;
• Журнал операций — фиксируем каждое обращение к обоим API для разбора;
• Дедупликация — по внешнему ключу «заказ + перевозчик».

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

Итог

Подключение службы доставки к МойСклад — это связка customerorder, demand, пользовательских атрибутов и вебхуков. Провайдер логистики остаётся внешним сервисом, а коннектор синхронизирует трек-номера, статусы и отгрузки, соблюдая идемпотентность и лимиты API.

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