Интеграции WMS

1. Общие сведения

WMS предоставляет набор интеграционных интерфейсов для взаимодействия с внешними системами. Основной канал интеграции -- Merchant API (REST), через который мерчанты управляют товарами, заказами, приёмками, возвратами и другими складскими операциями.

Все запросы к API требуют авторизации. Формат обмена данными -- JSON. Пагинация поддерживается через параметры page и size.

---

2. Архитектура интеграции

2.1 Общая схема взаимодействия

2.2 Процесс авторизации

---

3. Merchant API

3.1 Общее описание

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

Базовый путь: /merchant-api/

3.2 Таблица эндпоинтов

Группа	Метод	Путь	Описание
Товары	GET	/merchant-api/item	Получить список товаров
Товары	POST	/merchant-api/item	Создать товар
Товары	PUT	/merchant-api/item	Обновить товар
Товары	GET	/merchant-api/item/{id}	Получить товар по идентификатору
Товары	GET	/merchant-api/item/stocks	Получить остатки товаров
Заказы	GET	/merchant-api/order	Получить список заказов
Заказы	POST	/merchant-api/order	Создать заказ
Заказы	PUT	/merchant-api/order	Обновить заказ
Заказы	GET	/merchant-api/order/{id}	Получить заказ по идентификатору
Заказы	DELETE	/merchant-api/order/{id}	Отменить заказ
Приёмки	GET	/merchant-api/receipt	Получить список приёмок
Приёмки	POST	/merchant-api/receipt	Создать приёмку
Приёмки	GET	/merchant-api/receipt/{id}	Получить приёмку по идентификатору
Возвраты	GET	/merchant-api/returning	Получить список возвратов
Возвраты	POST	/merchant-api/returning	Создать возврат
Перемещения	GET	/merchant-api/movement	Получить движения товаров
Доставка	GET	/merchant-api/delivery	Информация о доставке
Наборы	GET	/merchant-api/bundle	Информация о наборах/комплектах

---

4. Описание операций

4.1 Товары (item)

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

Получение остатков (GET /merchant-api/item/stocks) возвращает актуальные данные о количестве товаров на складе с разбивкой по статусам (доступен, зарезервирован, в карантине).

4.2 Заказы (order)

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

При создании заказа указываются: состав (товары и количества), данные получателя, способ доставки. Система автоматически резервирует товары на складе.

4.3 Приёмки (receipt)

Управление поступлениями товаров на склад. Мерчант создаёт ожидаемую приёмку с перечнем товаров и количеств, склад выполняет фактическую приёмку с проверкой.

4.4 Создание товара

Для создания товара необходимо передать: наименование, артикул, штрихкод (опционально), габариты и вес (опционально), единицу измерения. Система проверяет уникальность артикула в рамках мерчанта.

4.5 Создание заказа

Для создания заказа необходимо передать: список товаров с количествами, данные получателя (ФИО, телефон, адрес), способ доставки, внешний номер заказа (опционально). Система проверяет наличие достаточного количества товаров на складе.

4.6 Создание приёмки

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

4.7 Получение остатков

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

4.8 Возвраты (returning)

Получение списка возвратов и создание новых возвратов через API.

GET /merchant-api/returning -- возвращает список возвратов мерчанта с поддержкой пагинации и фильтрации по статусу, дате, номеру заказа.

POST /merchant-api/returning -- создание возврата. Указывается заказ, перечень возвращаемых товаров с количествами и причина возврата. Система инициирует процесс приёмки возврата на склад.

4.9 Перемещения (movement)

Получение информации о движениях товаров на складе.

GET /merchant-api/movement -- возвращает историю перемещений товаров: поступления, отгрузки, внутренние перемещения между зонами склада. Поддерживается фильтрация по товару, дате, типу перемещения.

4.10 Доставка (delivery)

Информация о статусах доставки заказов.

GET /merchant-api/delivery -- возвращает данные о доставке: текущий статус, трек-номер, расчётные сроки, информация о курьерской службе. Поддерживается фильтрация по заказу, статусу доставки, дате.

4.11 Наборы (bundle)

Информация о комплектах (наборах) товаров.

GET /merchant-api/bundle -- возвращает данные о наборах: состав комплекта, входящие товары и их количества. Наборы позволяют группировать несколько товаров в одну единицу для продажи и отгрузки.

---

5. Интеграция с системой "Честный знак"

5.1 Общее описание

Система поддерживает работу с маркированными товарами в рамках требований национальной системы цифровой маркировки "Честный знак". Маркировка обязательна для определённых товарных групп (табачная продукция, обувь, лекарства, одежда и другие).

Система поддерживает автоматизированные процессы работы с маркировкой.

5.2 Поддерживаемые операции

• Сканирование и валидация кодов маркировки при приёмке товаров
• Привязка кодов маркировки к товарным позициям
• Проверка статуса кодов маркировки
• Агрегация и разагрегация кодов (групповая упаковка)
• Передача данных о движении маркированных товаров в систему "Честный знак"
• Вывод товаров из оборота при отгрузке конечному потребителю

5.3 Процесс работы с маркировкой

5.4 Маркировка в складских операциях

Операция	Действия с маркировкой
Приёмка	Сканирование кодов, проверка в "Честном знаке", привязка к товарам
Хранение	Учёт кодов маркировки в привязке к ячейкам хранения
Сборка заказа	Сканирование кодов при отборе товаров
Отгрузка	Формирование отчёта о выводе из оборота
Возврат	Повторный ввод в оборот, проверка статуса кода

---

6. Прочие интеграции

6.1 Интеграция с ERP-системами

Синхронизация данных о товарах и заказах между WMS и ERP-системами мерчантов. Обмен данными осуществляется через Merchant API. Поддерживается как ручной импорт/экспорт, так и автоматическая синхронизация по расписанию.

Основные сценарии:

• Передача справочника товаров из ERP в WMS
• Автоматическое создание заказов из ERP
• Получение актуальных остатков из WMS в ERP
• Синхронизация статусов заказов

6.2 Интеграция с курьерскими службами через ApiShip

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

Возможности:

• Расчёт стоимости доставки по различным службам
• Автоматическое создание заявок на доставку
• Получение трек-номеров
• Отслеживание статусов доставки в реальном времени
• Печать транспортных накладных

6.3 Система уведомлений

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

Поддерживаемые события:

• Создание и завершение приёмки
• Изменение статуса заказа
• Критически низкие остатки товаров
• Завершение отгрузки
• Ошибки при интеграции

6.4 Печать документов и этикеток

Система поддерживает формирование и печать складской документации:

• Штрихкоды товаров и ячеек хранения
• Термоэтикетки для маркировки товаров
• Транспортные этикетки для отгрузки
• PDF-документы (акты приёмки, накладные, упаковочные листы)
• Этикетки с кодами маркировки "Честный знак"

---

7. План интеграции для новых мерчантов

7.1 Этапы подключения

7.2 Рекомендации

1. Начните с товаров. Загрузите полный справочник товаров через POST /merchant-api/item, указывая штрихкоды и габариты для корректной работы склада.

2. Настройте приёмки. Создавайте приёмки заблаговременно через POST /merchant-api/receipt, чтобы склад был готов к поступлению товаров.

3. Тестируйте заказы. Перед запуском в продуктив создайте несколько тестовых заказов и убедитесь, что весь цикл (создание, сборка, отгрузка) проходит корректно.

4. Отслеживайте остатки. Настройте регулярный опрос GET /merchant-api/item/stocks для синхронизации остатков с вашей системой.

5. Обрабатывайте ошибки. Реализуйте корректную обработку HTTP-кодов ответа (400, 401, 404, 500) и повторные попытки при временных сбоях.

---

8. Коды ответов API

Код	Значение
200	Успешный запрос
201	Ресурс создан
400	Ошибка в параметрах запроса
401	Ошибка авторизации
403	Доступ запрещён
404	Ресурс не найден
409	Конфликт (например, дублирование артикула)
500	Внутренняя ошибка сервера