В двух прошлых статьях я разбирал маркировку и работу со складом-подрядчиком вообще. Здесь — конкретный случай: интернет-магазин Ladies Health, склад фулфилмента ООО «Бета ПРО», доставка Яндексом и Честный Знак. Что с чем разговаривает, какими методами и где мы обожглись.
Смысл разбора не в том, чтобы повторить его один в один: у вашего оператора будет своё API. Смысл в том, что грабли у таких связок одинаковые, а найти их можно только на живом заказе.
Кто участвует
Пять систем, и у каждой своя роль:
- Сайт — WooCommerce: витрина, корзина, оформление, оплата.
- CRM Ось Бизнеса — наш корпоративный портал: заказы, статусы, чеки, коды маркировки, работа менеджера. Дальше по тексту — просто «портал».
- Бета ПРО — склад: получает, хранит, собирает и отгружает заказы.
- Яндекс.Доставка — везёт: заявка, штрихкод, трек, возврат.
- Честный Знак — учитывает коды маркированных единиц; чек в него уходит через ОФД.
Ключевое решение: разговаривает со всеми одна система — портал. Раньше между ними стоял отдельный сервис-коннектор, и на бумаге это выглядело правильнее. На практике получилось два места, где живёт правда о заказе, и вопрос «почему статусы разошлись» перестал иметь однозначный ответ. Коннектор убрали.
Путь одного заказа. Каждая стрелка — вызов, который может не пройти, и на каждый нужен ответ на вопрос «что тогда».
Путь заказа
Как это работает на живом заказе:
- Покупатель оформляет заказ на сайте и платит картой.
- Платёжный сервис присылает уведомление, заказ становится оплаченным.
- Портал забирает заказ с сайта и заводит его у себя.
- Портал создаёт заявку в Яндекс.Доставке и получает штрихкод-этикетку.
- Портал ставит складу задание на отгрузку и прикладывает к нему этикетку.
- Склад собирает заказ, сканирует коды маркировки, отгружает курьеру.
- Портал получает коды отгруженных единиц и пробивает чек — код уходит в Честный Знак.
- Дальше портал следит за доставкой и возвратом.
Восемь шагов, и на каждом стыке — чужая система со своими правилами.
Транспорт Бета ПРО: два API вместо одного
Первое, что выясняется на практике: у оператора не одно API, а два поколения, и для корректной работы нужны оба.
REST /grh/api — основной, авторизация Basic. Им делается всё, ради чего интеграция и затевается:
POST /goods— завести товар в номенклатуре склада;POST /indocs— создать задание: что и кому отгрузить;POST /indocs/{id}/files— приложить к заданию файл, у нас это этикетка Яндекса;POST /indocs/{id}/attributes— дополнительные признаки задания;POST /outdocs/list— что склад отгрузил.
XML /wsrv — старый сервис, но без него не обойтись: часть данных живёт только там. Нам нужны два метода — «Остатки» и «Состояние отправления». Авторизация другая: пара «партнёр и пароль» кладётся в тело запроса, а не в заголовки. Ответ — с признаком state: ноль означает успех, минус единица — ошибку, и тогда весь запрос откатывается целиком.
⚠️ Планируя интеграцию, спросите оператора не «есть ли API», а какие методы в каком из API. Мы узнали про два транспорта уже в процессе, и это переписанный клиент вместо запланированного.
Грабли, которые нашлись только на бою
В позиции заказа нет количества
Самая дорогая ошибка. Мы отправляли позицию с количеством: артикул, две штуки. Склад принимал задание, показывал «2 шт», а отгружал одну.
Оказалось, в задании Бета ПРО количества у позиции нет. Данный атрибут игнорируется в связи с тем, что строка всегда означает одну единицу. Подтвердил менеджер оператора: «если заказали четыре штуки, необходимо указывать строку четыре раза».
Что изменили: позиция с количеством больше одного разбивается на нужное число строк по одной штуке. Побочный, но важный эффект — на каждую единицу приходит свой код маркировки, а без этого чек по заказу с двумя одинаковыми товарами не пробить.
⚠️ Диагностика: недоотгрузка выглядит не как ошибка, а как «клиенту приехало меньше». В журнале ошибок ничего нет — обе системы отработали штатно.
Осиротевшая заявка в доставке
Портал создавал заявку в Яндекс.Доставке и не сохранял её номер до того, как продолжить работу. Дальше шаг падал — и следующая попытка создавала вторую заявку на тот же заказ. Первая оставалась висеть ничьей.
Правило, которое из этого выросло: идентификатор чужой системы сохраняется сразу после ответа, до любых следующих действий. Не «в конце процедуры, когда всё получилось», а немедленно.
Возврат со склада никто не присылает
Заказ вернулся на склад, склад оформил его отдельным документом возврата — а в портале заказ так и висел доставленным. Нашли это не по уведомлению, а по расследованию: два кода маркировки числились на складе, хотя в Честном Знаке были списаны.
Вывод простой: документы склада надо опрашивать, а не ждать, что о них сообщат. Возврат — это не статус, который придёт сам, а документ, который появляется в списке отгрузок и возвратов.
Кто хозяин статуса
Отдельная история — доставка. Любой возвратный статус Яндекса портал переводит в «Возвращается». А вот терминальное «Возврат» автоматика не ставит.
Причина из практики: клиент отказался от посылки, менеджер решил не принимать её на склад и отправить замену за свой счёт. Заказ должен спокойно стоять в «Возвращается», пока человек не решит иначе, — а автоматика упрямо сбрасывала его в «Возврат», перебивая ручное решение.
Отсюда правило: у каждого статуса один хозяин. Промежуточные ведёт автоматика по данным перевозчика, терминальные ставит человек. Смешение этих ролей выглядит как «система живёт своей жизнью».
Оплата, которой не было
Первый заказ завис в ожидании оплаты, хотя деньги списались. Причина оказалась не в коде: на боевом терминале платёжного сервиса не были заполнены адреса уведомлений. Тестовый терминал был настроен, боевой — нет.
⚠️ При переезде на боевые ключи проверяйте не только сами ключи, но и настройки уведомлений: платёж пройдёт, а ваша система об этом не узнает.
Маркировка в этой схеме
Коды приходят от склада вместе с отгрузкой — по одному на единицу. Портал проверяет их полноту, кладёт в заказ и передаёт в чек отдельным реквизитом, откуда они уходят в Честный Знак через ОФД.
Здесь же — правило про количество из раздела выше: одна единица, одна строка, один код. Заказ с двумя одинаковыми позициями без этого не пробивается.
Что ещё важно знать про коды при работе через чужой склад — в отдельной статье про Честный Знак при отгрузке со склада: там про то, почему коды приезжают неполными и что проверять до отгрузки.
Что из этого следует для вашей интеграции
Перечислю то, что я бы выяснял на месте заказчика до начала работ:
- Какие методы в каком API — и нет ли второго, старого, без которого не обойтись.
- Поддерживается ли количество в позиции — необходимый для уточнения вопрос. Чтобы избежать недоотгрузок, важно уточнить, как построен учёт количества в системе.
- Как приходят коды маркировки: файлом, ответом метода, из личного кабинета руками.
- Как узнать о возврате на склад: приходит уведомление или надо опрашивать документы.
- Кто ставит статусы доставки и что делать, если человек решил иначе.
- Что происходит при повторной попытке: создастся вторая заявка или вернётся та же.
Общий принцип, который вывели за эти месяцы: интеграция ломается не там, где сложная логика, а там, где две системы по-разному понимают простое слово — «количество», «возврат», «доставлено». Выясняется это на первом же живом заказе, поэтому его стоит провести как можно раньше и смотреть на него в четыре глаза.
Как выбирать оператора и что должно ходить между вами автоматически — в статье про фулфилмент для интернет-магазина.
Если ваш склад — Бета ПРО
Всё описанное выше — не разовая история под один магазин. Особенности API, разбиение позиций, работа с этикетками Яндекса, коды маркировки и статусы возвратов уже пройдены на боевом проекте, и эти наработки применимы к интеграции у любого клиента Бета ПРО: склад тот же, методы те же, грабли те же. Проходить их заново не нужно.
Что обычно входит в такую работу:
- разбор вашей схемы: сайт или учётная система, перевозчики, маркированный товар;
- подключение к складу: номенклатура, задания на отгрузку, этикетки, документы возврата;
- статусы и остатки в обе стороны — с правилом, кто из систем ими распоряжается;
- маркировка: коды от склада до чека, с проверками до отгрузки;
- то, о чём вспоминают последним: куда придёт сигнал, когда обмен сломается.
Сроки зависят от вашей стороны: склад со своей стороны готов, и то, что обычно занимает недели на выяснение особенностей, здесь уже выяснено.
Хотите такую же связку у себя — расскажите о задаче.