Интеграции

1. Описание

Данный раздел содержит документацию по интеграции WMS с внешними системами через REST API. Описаны основные сценарии, структура обмена, перечень команд и детальное описание методов.

---

2. Типовая схема взаимодействия

---

3. Вызов сервиса WebAPI

3.1. Адрес сервиса и формат обмена

• Базовый URL:
  http://wms-api.dev.sigmation.ai/
• Формат обмена:
  Все методы используют HTTP(S) и формат JSON для передачи данных.
• Авторизация:
  Для всех методов требуется передача заголовка
  Authorization: Bearer <merchant_token>
• Документация API: Документация API доступна по ссылке

---

3.2. Перечень команд

Группа	Метод/Описание	HTTP	URL
Склады	Получить список складов	GET	/merchant-api/warehouses
Контрагенты	Получить список контрагентов	GET	/merchant-api/counterparties
	Создать/изменить контрагента	POST	/merchant-api/counterparties
Службы доставки	Получить список служб	GET	/merchant-api/delivery-companies
Контракты	Получить список контрактов	GET	/merchant-api/delivery-contracts
	Создать/изменить контракт	POST	/merchant-api/delivery-contracts
Товары	Получить типы серийных номеров	GET	/merchant-api/skus/serial-number-types
	Получить список товаров	GET	/merchant-api/skus
	Создать/изменить товары	POST	/merchant-api/skus
Поставки	Получить список поставок	GET	/merchant-api/supplies
	Создать/изменить поставку	POST	/merchant-api/supplies
Заказы	Получить список заказов	GET	/merchant-api/orders
	Создать/изменить заказ	POST	/merchant-api/orders

---

4. Описание методов

4.1. Склады

4.1.1. Получить список складов

• URL: /merchant-api/warehouses
• HTTP: GET
• Бизнес-описание: Получение перечня всех складских площадок, доступных для работы организации. Позволяет получить перечень всех складов, используемых в компании. Необходим для выбора склада при создании заказов, поставок, перемещений и других операций. Актуально для компаний с несколькими складами или распределённой логистикой.
• Особые требования: Метод доступен только при наличии действующего merchant-токена, выданного для организации. Все операции выполняются в рамках организации, к которой привязан токен. Доступ к складам ограничен правами пользователя и организацией.

---

4.2. Контрагенты

4.2.1. Получить список контрагентов

• URL: /merchant-api/counterparties
• HTTP: GET
• Бизнес-описание: Получение списка всех контрагентов (поставщиков, клиентов, партнёров), зарегистрированных в системе. Используется для автоматизации документооборота, формирования заказов, поставок, контрактов и отслеживания истории взаимодействий.
• Особые требования: Возвращаются только контрагенты, принадлежащие организации, к которой привязан merchant-токен. Доступ к данным других организаций невозможен. Организация определяется по токену авторизации.

4.2.2. Создать/изменить контрагента

• URL: /merchant-api/counterparties
• HTTP: POST
• Бизнес-описание: Добавление нового контрагента или обновление данных существующего. Важно для поддержания актуальности справочника контрагентов, интеграции с внешними CRM/ERP, автоматизации заведения новых партнёров.
• Особые требования: Разрешено создавать и изменять только контрагентов своей организации. Для изменении информации о контрагенте, такой как адрес или банковские реквизиты, необходимо использовать его ID.

---

4.3. Службы доставки

4.3.1. Получить список служб доставки

• URL: /merchant-api/delivery-companies
• HTTP: GET
• Бизнес-описание: Получение перечня всех курьерских и транспортных компаний, с которыми интегрирована WMS. Используется для выбора службы при оформлении заказов, расчёте стоимости и сроков доставки, автоматизации логистики.
• Особые требования: Метод доступен только авторизованным пользователям. Нет дополнительных ограничений.

---

4.4. Контракты доставки

4.4.1. Получить список контрактов

• URL: /merchant-api/delivery-contracts
• HTTP: GET
• Бизнес-описание: Получение списка всех действующих договоров с транспортными и курьерскими компаниями. Важно для контроля условий сотрудничества, автоматизации выбора тарифа и маршрута доставки.
• Особые требования: Метод доступен только авторизованным пользователям. Данные возвращаются в разрезе организации, к которой привязан merchant-токен. Нет дополнительных ограничений.

4.4.2. Создать/изменить контракт

• URL: /merchant-api/delivery-contracts
• HTTP: POST
• Бизнес-описание: Добавление нового контракта или обновление параметров существующего. Используется для гибкого управления логистическими соглашениями и интеграции с внешними системами учёта.
• Особые требования: Для создания или изменения контракта требуется указать уникальный код контракта и идентификатор продукта службы доставки. Редактирование контракта возможно только в том случае, если по данному контракту ещё не было создано ни одного заказа на отгрузку. После появления связанных заказов контракт становится неизменяемым.

---

4.5. Товары

4.5.1. Получить список типов серийных номеров

• URL: /merchant-api/skus/serial-number-types
• HTTP: GET
• Бизнес-описание: Получение справочника типов серийных номеров, по которым ведётся учёт товаров. Важно для отраслей с обязательной прослеживаемостью и маркировкой.
• Особые требования: В справочник могут входить такие типы, как ЧЗ (честный знак), IMEI и другие, используемые для обязательной маркировки и отслеживания товаров.

4.5.2. Получить список товаров

• URL: /merchant-api/skus
• HTTP: GET
• Бизнес-описание: Получение полного перечня товаров, зарегистрированных в системе. Используется для автоматизации заказов, поставок, инвентаризации, интеграции с внешними каталогами.
• Особые требования: Доступ к товарам ограничен организацией, к которой привязан merchant-токен. Нет дополнительных ограничений.

4.5.3. Создать/изменить товары

• URL: /merchant-api/skus
• HTTP: POST
• Бизнес-описание: Добавление новых товаров или обновление характеристик существующих. Важно для поддержания актуальности товарного справочника и интеграции с внешними системами.
• Особые требования: Приёмка товаров осуществляется по уникальному штрихкоду (ШК). Один и тот же ШК не может быть использован для разных SKU. Поле title используется во всех печатных формах для склада, а поле title_en — для международных интеграций. Все операции доступны только в рамках своей организации.

---

4.6. Поставки

4.6.1. Получить список поставок

• URL: /merchant-api/supplies
• HTTP: GET
• Бизнес-описание: Получение перечня всех поставок, поступивших или ожидаемых на складе. Используется для контроля входящих потоков, планирования приёмки, отслеживания статусов и истории поставок.
• Особые требования: Доступ к поставкам ограничен организацией пользователя. Нет дополнительных ограничений.

4.6.2. Создать/изменить поставку

• URL: /merchant-api/supplies
• HTTP: POST
• Бизнес-описание: Регистрация новой поставки или обновление данных по существующей. Важно для автоматизации приёмки, интеграции с закупочными системами, контроля остатков.
• Особые требования: Поставку нельзя изменять после перехода в статус "В процессе приемки".
• NEW - Новый
• AWAITING_RECEIPT - Ожидает приемки
• RECEIVING - В процессе приемки
• RECEIVED - Приемка окончена
• DONE - Закрыта После перехода в любой из финальных статусов редактирование запрещено. Предусмотрена доверительная приемка. Настраивается на организацию (токен).

---

4.7. Заказы

4.7.1. Получить список заказов

• URL: /merchant-api/orders
• HTTP: GET
• Бизнес-описание: Получение перечня всех заказов, оформленных в системе. Используется для контроля отгрузок, планирования логистики, отслеживания статусов выполнения.
• Особые требования: Доступ к заказам ограничен организацией пользователя. Нет дополнительных ограничений.

4.7.2. Создать/изменить заказ

• URL: /merchant-api/orders
• HTTP: POST
• Бизнес-описание: Создание нового заказа на отгрузку или обновление параметров существующего. Важно для автоматизации продаж, интеграции с внешними магазинами, маркетплейсами, курьерскими службами.
• Особые требования: Заказы нельзя изменять после перехода в статус "В батче" (IN_BATCH). При создании заказа товары могут быть загружены как в резерве, так и не в резерве. Поддержка наборов (комплектов) находится в стадии проработки.

5. Работа с Честным знаком (ЧЗ)

Механизм загрузки ЧЗ в свободный пул находится в стадии проработки и реализовывается с учетом гибкости и безопасности.

Работа с маркировкой Честный знак (ЧЗ) в WMS организована с учетом современных требований прослеживаемости и интеграции с государственными и отраслевыми системами. Все коды ЧЗ поступают из внешней системы — это касается как приемки, так и отгрузки, а также комплектов и товаров, подлежащих обязательной маркировке на складе.

Основные принципы интеграции с ЧЗ

• Внешний источник данных: Все коды ЧЗ загружаются в WMS исключительно из внешних систем, что обеспечивает корректность, актуальность и юридическую значимость маркировки.
• Единый подход для всех бизнес-процессов: Независимо от сценария (приемка, отгрузка, комплектация, маркировка остатков) используется единая схема загрузки и контроля ЧЗ.

5.1. Загрузка ЧЗ

• Загрузка кодов ЧЗ осуществляется в свободный пул. Коды могут быть загружены как с привязкой к определённому документу (например, поставке или заданию на комплектацию), так и без привязки — для последующей маркировки остатков.
• Если поставщик привозит товар, который необходимо промаркировать ЧЗ, загрузка кодов производится в свободный пул с привязкой к поставке.

5.2. Приёмка товара

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

5.3. Приёмка возврата

• При возврате, если на товаре отсутствует ЧЗ, и принято решение разместить товар на сток "хороший", система автоматически подбирает подходящий ЧЗ по SKU из свободного пула и маркирует товар.

5.4. Маркировка стока

• Для маркировки остатков на складе система также использует коды ЧЗ из свободного пула, соответствующие данному товару.
• Имеется возможность промаркировать отдельный контейнер.

5.5. Отгрузка и комплектация

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

Контроль и использование ЧЗ

• При проведении операций WMS автоматически проверяет наличие и валидность ЧЗ в доверительной приемке или свободном пуле.
• Все действия с ЧЗ логируются и доступны для аудита, что обеспечивает прозрачность и соответствие требованиям законодательства.

6. Общая схема интеграции

Интеграция WMS с внешними системами строится на четкой структуре бизнес-процессов и прозрачном обмене данными между ключевыми блоками: Товары, Поставки и Заказы покупателей. Каждый блок реализует свой набор API-методов, обеспечивая полный цикл управления складскими и торговыми операциями. Взаимодействие между блоками позволяет автоматизировать приёмку, хранение, отгрузку, а также отслеживать статусы и управлять возвратами.

Взаимодействие между блоками и API

---

Пояснения к схеме:

• Все ключевые операции (создание, обновление, получение статусов) реализованы через REST API.
• Движение данных между блоками обеспечивает сквозную автоматизацию: от загрузки товаров до приёмки, хранения, отгрузки и возвратов.

6. Типовой план работ по интеграции

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

1. Клиент: Анализирует документацию по API, формирует пробные запросы с использованием тестовой учётной записи (предоставляется по запросу).
2. WMS: Изучает бизнес-процессы клиента, создает тестовую учётную запись с учётом специфики и требований интеграции.
3. Клиент Создает необходимые контракты доставки (POST /merchant-api/delivery-contracts), которые определяют условия работы с курьерскими и транспортными компаниями. Без наличия хотя бы одного действующего контракта оформление заказов на отгрузку невозможно.
4. Клиент: Выполняет выгрузку номенклатуры (товаров) в систему WMS.
5. WMS: Проводит анализ полученной номенклатуры, штрихкодов, полноты данных и корректности наименований для корректной работы склада.
6. Клиент: Формирует и выгружает заявку на приёмку товара.
7. WMS: Проверяет корректность заявки на приёмку, осуществляет "виртуальный" приём товара по заявке. На складе появляются остатки.
8. Клиент: Формирует и выгружает заявку на отгрузку товара.
9. WMS: Проверяет корректность данных клиента, адресной и товарной части, осуществляет "виртуальную" отгрузку по заявке.

---

Пример взаимодействия в ВМС

Этот сценарий отражает основные этапы интеграции и взаимодействия между клиентской системой и WMS, включая анализ, загрузку данных, формирование заявок и обработку бизнес-операций через API