API МоегоСклада для производства: что автоматизировать и как не сломать учет

API МоегоСклада для производства: что автоматизировать и как не сломать учет

Интеграция нужна не потому, что системы умеют обмениваться JSON. Она нужна, когда одно и то же событие сотрудники повторно вводят в сайт, CRM, складскую и производственную систему. Заказ копируют вручную, остатки отправляют дилеру в таблице, статус производства уточняют в чате, а плановую дату обещают без проверки материалов.

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

Что такое API в практическом смысле

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

API не является отдельной базой, куда можно бездумно отправить всё. Каждый запрос меняет или читает рабочий учет. Ошибка в логике интегратора может создать повторный заказ, неверно зарезервировать товар или переписать поле, которое уже исправил сотрудник.

Начните с карты систем

Владельцем называют систему, где значение создаётся и исправляется. Другие системы получают копию для работы или просмотра. Двустороннее редактирование одного поля допустимо только при явном правиле конфликта.

Сценарий 1: заказ с сайта или B2B-портала

После подтверждения клиентом интеграция создаёт заказ покупателя с контрагентом, организацией, складом, ценами, позициями, количеством, каналом и внешним идентификатором. В ответ сохраняется идентификатор объекта МоегоСклада. Повторная отправка того же события должна найти существующий документ, а не создать новый.

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

Сценарий 2: остатки и резервы

Внешнему каналу обычно не нужна полная копия всех складских движений. Ему нужны доступность и правила продажи: доступно сейчас, ожидается, минимальная партия, срок изготовления. Публичный остаток может отличаться от физического из-за резервов, страхового запаса, карантина и товаров, предназначенных для других каналов.

Правило публикации фиксируется отдельно. Например: доступно для портала равно физическому остатку минус резерв минус страховой запас. Нельзя считать формулу в каждом канале по-разному.

Сценарий 3: статусы производства

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

Статус должен строиться из факта, а не из намерения. «В производстве» ставится после создания и запуска задания, «готов» — после завершения и контроля, «отгружен» — по соответствующему учетному документу. Тогда клиентский интерфейс не спорит с цехом.

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

Вебхук уведомляет внешнюю систему об изменении и позволяет не опрашивать API каждую минуту. Но его нельзя считать единственной гарантией доставки бизнес-события. Получатель должен быстро принять уведомление, положить его в очередь и обработать повторяемо. После сбоя нужна плановая сверка по времени обновления.

Надёжная схема сочетает три механизма:

1. Событие: вебхук сообщает, что объект изменён.
2. Очередь: обработчик повторяет временно неуспешные операции.
3. Сверка: регламентное задание находит пропущенные и расходящиеся записи.

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

Идемпотентность: защита от дублей

Сеть может вернуть тайм-аут после успешной записи. Отправитель не знает, создался ли документ, и повторяет запрос. Если интеграция не хранит соответствие, появляется дубль. Поэтому каждое бизнес-событие имеет стабильный внешний ключ, а таблица связей хранит идентификаторы обеих систем.

Идемпотентная обработка означает: повтор одного события приводит к тому же результату, а не к новому заказу. Проверка только по номеру ненадёжна — номера могут меняться или совпадать между каналами.

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

Не отправляйте полную старую копию объекта, если меняется одно поле. За время между чтением и записью менеджер мог уточнить дату, склад или комментарий. Интегратор должен передавать только поля своей ответственности и перед записью проверять актуальное состояние.

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

Лимиты и постраничная загрузка

Официальные общие сведения API указывают ограничения выборок и массовых операций. В документации приведены HTTP 429 при превышении лимита, заголовки остатка запросов и времени повтора, а также ограничения для expand. Значит, интеграция должна читать заголовки, ограничивать параллелизм, применять задержку и разбивать данные на страницы.

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

Обработка ошибок

Число повторов ограничивается. После лимита операция попадает в карантин, где сотрудник видит исходные данные, понятное сообщение и кнопку безопасного перезапуска. Ошибка не должна бесконечно занимать очередь.

Безопасность

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

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

Что не стоит автоматизировать первым

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

Также опасно автоматически запускать производство из любого заказа сайта. Перед запуском могут требоваться оплата, проверка технологии, согласование макета, подтверждение материала и кредитного лимита.

План запуска

1. Описать события, владельцев данных и допустимые статусы.
2. Составить таблицу соответствий сущностей и полей.
3. Выбрать один маршрут, например заказ сайта → черновик заказа покупателя.
4. Реализовать внешний ключ, журнал и безопасные повторы.
5. Проверить положительные и отрицательные сценарии на тестовых данных.
6. Запустить пилот на одном канале и ограниченной номенклатуре.
7. Ежедневно сверять дубли, пропуски, суммы и статусы.
8. После стабильности добавить остатки, производство и аналитику.

Как внедряет KULPS

KULPS проектирует интеграцию от бизнес-события до контроля результата. Мы определяем систему-источник, правила данных, соответствия, права и сценарии сбоев; реализуем обмен, журнал, мониторинг и сверку; обучаем сотрудника, который разбирает исключения. Цель — не максимальное количество соединений, а предсказуемый учет без ручных дублей.

Источники и официальная документация

• МойСклад: общие сведения JSON API 1.2.
• МойСклад: вебхуки в JSON API.
• МойСклад: заказ покупателя в JSON API.
• МойСклад: отчет остатков в JSON API.
• МойСклад: производственное задание.

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