Список методов#
Список методов Marketplace merchants API представлен ниже. Также есть возможность скачать описание методов Marketplace merchants API в формате Swagger.
Авторизация#
POST /oauth/token
#
- Возвращает JWT-токен в JSON-документе.
1. Отказ от заказа#
1.1. POST /parcels/{parcelId}:cancel
#
- Переводит отправление по переданному идентификатору в формате
MP0123456-001
в статус Отменено. Данный метод можно использовать до статуса "Подтверждено" или после статуса "Подтверждено". В остальных случаях он будет отдавать 409 ответ (конфликт запроса). В методе используются Querry-параметры: stage и reason. Stage указывает статус, в котором производится отмена отправления Отменен до подтверждения или Отменен после подтверждения. Reason указывается причина отмены отправления.
1.2. POST /parcels:cancel
#
- Переводит массив отправлений по переданным идентификаторам в теле запроса в формате
MP0123456-001
в статус "Отменено". Данный метод можно использовать до статуса Подтвержено или после статуса Подтвержено. В остальных случаях он будет отдавать 409 ответ (конфликт запроса). В методе используются Querry-параметры: stage и reason. Stage указывает статус, в котором производится отмена отправления "Отменен до подтверждения" (CancelAtConfirmation) или "Отменен после подтверждения" (CancelAfterConfirmation). В reason указывается причина отмены отправления.
2. Работа с данными / изменение статуса#
2.1. GET /parcels/{parcelId}
#
- Возвращает информацию об отправлении по переданному идентификатору в формате
MP0123456-001
.
2.2. GET /parcels
#
- Возвращает список отправлений с возможностью пагинации с помощью Query-параметров: limit и offset.
Для получения списка отправлений c определенным статусом, необходимо выполнить запрос с query-параметром status.
Сортировка результатов производится от новых к старым.
Список доступных значений параметра status:
- created - ожидает подтверждения
- canceled - отменен
- packingStarted - комплектуется
- awaitingMarking - ожидание валидации кода маркировки
- failedMarking - не пройдена валидация кода маркировки
- expiredMarking - просрочено ожидание кода маркировки
- successMarking - пройдена валидация кода маркировки
- refused - отказ в комплектации
- packingCompleted - комплектация завершена
- shipped - отгружен
- deliveryStarted - в пути
- delivered - доставлен
2.3. GET /parcels/{parcelId}/statuses
#
- Возвращает список исторических статусов отправления по переданному идентификатору в формате
MP0123456-001
. Статусы отсортированы по времени получения статуса.
2.4. POST /parcels:statuses
#
- Возвращает список отправлений с историческими статусами. В тело запроса необходимо передать идентификаторы отправления в формате
MP0123456-001
.
2.5. POST /parcels/{parcelId}:confirm
#
- Переводит отправление по переданному идентификатору в формате
MP0123456-001
в статус "Подтверждено".
2.6. POST /parcels:confirm
#
- Переводит массив отправлений по переданным идентификаторам в тело запроса в формате
MP0123456-001
в статус "Подтверждено".
2.7. POST /parcels/{parcelId}:pack
#
- Переводит отправление по переданному идентификатору в формате
MP0123456-001
в статус Скомплектовано.
2.8. POST /parcels:pack
#
- Переводит массив отправлений по переданным идентификаторам в тело запроса в формате
MP0123456-001
в статус "Скомплектовано".
2.9. POST /acceptance-reports
#
- Создает документ Акт приема-передачи по переданному в теле запроса списку идентификаторов отправлений в формате
MP0123456-001
. После успешного создания документа Акт приема-передачи все отправления переводятся в статус “Отгружен“.
В ответе возвращаются массив объектов АПП (acceptanceReports) и массив идентификаторов отправлений, которые не вошли в состав сформированных АПП (errorParcelIds).
3. Работа с сопроводительными документами#
3.1. POST /documents
#
- Получает сопроводительные документы по списку отправлений. Возвращает ссылку на pdf файл по указанному в теле запроса параметру documentType (вид документа).
Возможные значения параметра Тип документа (documentType):
- selectedProdutLists (Групповая печать описей отправлений по переданному в теле запроса массиву идентификаторов отправлений в формате
MP0123456-001
); - selectedbarcodeStickers (Групповая печать термоэтикеткок по переданному в теле запроса массиву идентификаторов отправлений в формате
MP0123456-001
).
Первый запрос инициирует процесс формирования файла.
В ответе на запрос будет получен статус “В процессе формирования”* (“IN_PROGRESS”) или статус “Готов” (“DONE”) и ссылка на файл.
*При статусе “В процессе формирования” (“IN_PROGRESS”) необходимо повторить запрос через 2 минуты.
3.2. GET /documents/{parcelId}
#
- Получает сопроводительные документы по одному отправлению. Возвращает ссылку на pdf файл по указанному Query-параметру documentType (вид документа).
Возможные значения параметра Тип документа (documentType):
- productList (Опись отправления);
- barcodeSticker (Термоэтикетки отправления);
- acceptanceReport (Акт приема-передачи);
- acceptanceReportBarcodeStickers (Термоэтикетки в рамках Акта приема-передачи).
В ответе на запрос будет получен статус “В процессе формирования”* (“IN_PROGRESS”) или статус “Готов” (“DONE”) и ссылка на файл.
*При статусе “В процессе формирования” (“IN_PROGRESS”) необходимо повторить запрос через 2 минуты.
4. Работа с грузоместами#
4.1. GET /parcels/{parcelId}/boxes
#
- Возвращает отправление с содержимым грузомест по переданному идентификатору в формате
MP0123456-001
. Информация о грузоместах: артикул товара и его количество.
4.2. PUT /parcels/{parcelId}/boxes
#
- Обновляет количество грузомест отправления по переданному идентификатору в формате
MP0123456-001
. В тело запроса прописывается sku (артикул) и quantity (количество) товара в рамках каждого грузоместа. Если грузоместо лишь одно, поля placeNumber и placeTotal передавать не нужно.
Также опционально наряду с sku и quantity можно прописать placeNumber (номер грузоместа в отправлении) и placeTotal (количество грузомест в отправлении всего).
В случае использования полей placeNumber и placeTotal происходит валидациях наличия таких полей и их значений:
- При заполнении полей placeNumber и placeTotal они должны быть заполнены для всех грузомест.
- Нумерация частей товара в placeNumber должна строго соответствовать общему количеству частей в placeTotal (все порядковые номера вплоть до placeTotal должны быть использованы).
По умолчанию поля placeNumber и placeTotal получают в качестве значения 1.
5. Методы, прекращающие работу в третьем квартале 2024 года#
5.1. POST /parcels/{parcelId}:ship
#
- Переводит отправление по переданному идентификатору в формате
MP0123456-001
в статус Отгружено.
5.2. POST /parcels:ship
#
- Переводит массив отправлений по переданным идентификаторам в тело запроса в формате
MP0123456-001
в статус "Отгружено".
Модель использования public API#
Для перевода отправлений по статусной модели необходимо придерживаться статусной модели маркетплейса Леруа Мерлен.
План перевода по статусной модели:
Описание типов выходных данных#
Параметр | Тип данных | Описание |
---|---|---|
Parcel | ||
id | String | ID отправления в Маркетплейсе вида MP0123456-001 |
creationDate | Date-time | Дата создания отправления в кабинете мерчанта (фактически - дата оплаты отправления покупателем) |
parcelPrice | Int32 | Стоимость всех товаров в отправлении, сумма, оплаченная покупателем на сайте |
promisedDeliveryDate | Date-time | Обещанная дата доставки клиенту |
deliveryCost | Int32 | Стоимость доставки для мерчанта |
pickup | Pickup | Информация о пикапе |
products | Array<Product> | Информация о товарах |
calculatedWeight | Int32 | Расчетный вес |
calculatedLength | Int32 | Расчетная высота |
calculatedHeight | Int32 | Расчетная длина |
calculatedWidth | Int32 | Расчетная ширина |
Pickup | ||
deliveryServiceId | Int32 | Идентификатор службы доставки на отгрузке |
deliveryServiceName | String | Название службы доставки на отгрузке |
warehouseId | String | Идентификатор склада отгрузки |
pickupDate | Date-time | Дата отгрузки |
timeInterval | String | Интервал отгрузки |
Product | ||
lmId | String | Идентификатор товара в Леруа Мерлен |
vendorCode | String | Артикул производителя |
placeNumber | Int32 | Номер грузоместа в отправлении |
placeTotal | Int32 | Количество грузомест в отправлении всего |
price | Int32 | Стоимость |
qty | Int32 | Количество |
comissionRate | Int32 | Ставка комиссии |
Status | ||
name | String | Текстовое значение статуса |
date | Date-time | Дата получения статуса |
Document | ||
status | String | Статус документа. Возможные значения: 1. IN_PROGRESS 2. DONE |
fileUrl | String | Ссылка на файл |
AcceptanceReport | ||
acceptanceReportId | String | Номер Акта приема-передачи |
parcelIds | Array of Strings | Массив идентификаторов отправлений |
ErrorParcelIds | ||
parcelId | String | Иденификатор отправления в формате MP0123456-001 |
reason | String | Описание причины отмены. Возможные варианты: - Некорректный статус = “wrong status”; - Отправление принадлежит другому мерчанту = “other merсhant”; - Отправление не найдено = “not found”; - Отправление входит в состав другого документа АПП = “acceptance report №“999999”, где “999999“ - это номер документа АПП. |
reasonCode | String | Код причины отмены. Возможные варианты: - Некорректный статус = 409; - Отправление принадлежит другому мерчанту = 403; - Отправление не найдено = 404; - Отправление входит в состав другого документа АПП = 409. |
Список статусов отправления#
Код статуса | Описание статуса |
---|---|
created | Новый. Необходимо подтвердить или отказаться от заказа. |
canceled | Отменен. |
packingStarted | Комплектуется. Возможно деление отправления на грузоместа. После окончания комплектации необходимо изменить статус отправления на “Комплектация завершена”. Возможно отказаться от заказа. |
refused | Отказ в комплектации. |
awaitingMarking | Ожидание валидации кодов маркировки. Работа в системе ЭДО. Возможно отказаться от заказа. |
failedMarking | Не пройдена валидация кодов маркировки. Работа в системе ЭДО. Необходимо обновить данные УПД. Возможно отказаться от заказа. |
expiredMarking | Просрочено ожидание кодов маркировки. Работа в системе ЭДО. Направить данные УПД. Возможно отказаться от заказа. |
successMarking | Пройдена валидация кодов маркировки. Необходимо скомплектовать отправление. При необходимости возможно разделить отправление на грузоместа. По окончании комплектации необходимо изменить статус отправления на packingCompleted (Комплектация завершена). В этом статусе разделение на грузоместа запрещено. Возможно отказаться от заказа. |
packingCompleted | Комплектация завершена. Разделение на грузоместа запрещено. Возможно отказаться от заказа. |
shipped | Отгружен. |
deliveryStarted | В пути. |
delivered | Доставлен. |