Перейти к содержанию

Список методов#

Список методов 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 происходит валидациях наличия таких полей и их значений:
  1. При заполнении полей placeNumber и placeTotal они должны быть заполнены для всех грузомест.
  2. Нумерация частей товара в 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#

Для перевода отправлений по статусной модели необходимо придерживаться статусной модели маркетплейса Леруа Мерлен.
План перевода по статусной модели: Example

Описание типов выходных данных#

Параметр Тип данных Описание
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 Доставлен.