Документация к API внешних интеграций, для продавцов

Методы API для продавцов

Общие данные

1. Для отправки любых запросов требуется получить у администратора маркетплейса (МП) логин и пароль для авторизации.

2. Каждый запрос проходит basic-авторизацию, поля ответа фильтруются по id продавца (мерчанта) которому были выданы доступы та где это необходимо.

3. Ответ всегда приходит в формате json если не указано иное

Заказы

Запрос

GET /api/v1/orders

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

Ключ	Значения	Описание
page	(array): number (int) size (int)	Массив для работы с пагинацией: Номер страницы Кол-во элементов на странице
status	int	Идентификатор статусов (см Статусная модель доставки)
payment_status	int	Идентификатор статусов (см Статусная модель доставки)
is_canceled	int (0|1)	Флаг только “отмененные/не отмененные заказы”
is_problem	int (0|1)	Флаг только “проблемные заказы”
number	string	Номер заказа который видет мерчант
store_id	int	Идентификатор склада отаправки

Ответ

В ответном массиве data приходит список Отправлений мерчанта подходящую под фильтр в запросе:

Ключ	Значение	Описание
id		Системный идентификатор заказа
delivery_id		Системный идентификатор доставки
number	string	Номер заказа который видит мерчант
store_id	int	Идентификатор склада
cargo_id	int	Системный идентификатор груза
delivery_service_zero_mile	string	Дата “Нулевой мили” “2022-06-07T16:30:00.000000Z”
psd	string	Дата “ПСД” “2022-06-07T16:30:00.000000Z”
fsd	string	Дата “ФСД” “2022-06-07T16:30:00.000000Z”
created_at	string	Дата создания заказа, например “13.06.2023 13:51”
status	int	Статус заказа (см Статусная модель доставки)
status_at	string	Дата последней смены статуса “13.06.2023 13:51”
payment_status	int	Статус оплаты заказа (см Статусная модель доставки)
payment_status_at	string	Дата последней смены статуса оплаты “13.06.2023 13:51”
is_canceled	bool	Флаг отмененного заказа
is_canceled_at	string	Дата отмены “13.06.2023 13:51”
is_problem	bool	Флаг проблемного заказа
is_problem_at	string	Дата отметки “проблемный” “13.06.2023 13:51”
cost	float	Общая стоимость заказа
width, height, length, weight	float	Ширина, высота, длина, вес отправления
required_shipping_at	string	Запрашиваемая дата доставки
updated_at	string	Дата последнего обновление модели “13.06.2023 13:51”
assembly_problem_comment	string	Комментарий при сборке заказа
problem_reason_id	int	Идентификатор проблемного заказа
basketItems	array	Массив со списком товаров в заказзе
delivery	array	Объект с информацией о доставке

Элемент списка товаров в заказе (массив basketItems):

Ключ	Значение	Описание
id	int	Системный идентификатор товара в корзине
basket_id	int	Системный идентификатор корзины
offer_id	int	Идентификатор оффера
type	int	Тип товара (1 - товар, 2 - услуга, 3 - подарочный сертификат)
name	string	Название товара
qty	int	Количество экземпляров
price	float	Цена на витрине
cost	float	Цена с учетом скидок
bonus_spent	int	Потрачено бонусов
bonus_discount	int	Бонусов начислено
created_at	string	Дата создания записи
updated_at	string	Дата обновления записи
referrer_id	?id	Идентификатор реферального партнера
bundle_id	?id	Идентификатор бандла
product	array	Объект с информацией о товаре
id	int	Системный идентификатор
weight, width, height, length	string	Характеристики ШВГ и вес
is_explosive	bool	Флаг взрывоопасного товара
categories	array	массив с идентификаторами категорий товара

Объект с информацией о доставке в доставке (массив delivery):

Ключ	Значение	Описание
id	int	Системный идентификатор доставки
order_id	int	Системный идентификатор заказа
delivery_method	int	Метод доставки (1- доставка курьером, 2 - ПВЗ, 3 - Постомат)
delivery_service	int	Системный идентификатор ЛО
status	int	Статус доставки (см Статусная модель доставки)
status_xml_id	string	Идентификатор статуса доставки у ЛО
payment_status	int	Статус оплаты доставки (см Статусная модель доставки)
payment_status_at	string	Дата оплаты
is_canceled	bool	Флаг отмененной доставки
is_canceled_at	string	Дата отмены
is_problem	bool	Флаг проблемной доставки
is_problem_at	string	Дата проблемы
xml_id	string	Идентификатор доставки у ЛО
tracknumber	string	Трек-номер
barcode	string	Штрих-код
error_xml_id	string	Ошибка со стороны ЛО
tariff_id	int	Идентификатор тарифа
point_id	int	Идентификатор ПВЗ
number	string	Номер доставки видимый Мерчанту
delivery_address	array	Объект с информацией об адресе доставки
receiver_name	string	Имя получателя
receiver_phone	string	Телефон получателя
cost	float	Стоимость доставки
width,height,length,weight,	string	Характеристики ШВГ и вес
delivery_at	string	Время, когда заказ был доставлен
delivery_time_code	string	Желаемое время доставки (окно), формат ЧЧ-ЧЧ
delivery_time_start	string	Желаемое дата и время доставки “c”
delivery_time_end	string	Желаемое дата и время доставки “до”
dt	int	ДТ
pdd	string	ПДД
status_at	string	Время последнего изменения статуса
status_xml_id_at	string	Время последнего изменения статуса ЛО
order	array	Объект с информацией о заказе

Объект с информацией о доставке в заказе (массив order):

Ключ	Значение	Описание
id	int	Системный идентификатор заказа
number	string	Видимый мерчанту номер заказа
basket_id	int	Системный идентификатор корзины
type	int	Тип товара (1 - товар, 2 - услуга, 3 - подарочный сертификат)
customer_id	int	Системный идентификатор покупателя
receiver_name	string	Имя получателя
receiver_phone	string	Телефон получателя
receiver_email	string	email получателя
cost	float	Сумма заказа со скидкой
price	float	Сумма заказа без скидкой
delivery_price	float	Стоимость доставки
delivery_cost	float	Стоимость доставки со скидкой
spent_bonus	int	потрачено бонусов
added_bonus	int	Начислено бонусов
delivery_type	int	Метод доставки (1- доставка курьером, 2 - ПВЗ, 3 - Постомат)
status	int	Статус заказа (см Статусная модель доставки)
status_at	string	Дата обновления статуса
payment_status	int	Статус оплаты заказа(см Статусная модель доставки)
payment_status_at	string	Дата обновления статуса оплаты
is_problem	bool	Флаг проблемного заказа
is_problem_at	string	Дата проблемы
is_canceled	bool	Флаг отмененного заказа
is_canceled_at	string	Дата отмены
is_require_check	bool	Флаг что требуется проверка
manager_comment	string	Комментарий менеджера
confirmation_type	int	Тип подтверждения заказа
created_at	string	Дата создания записи
updated_at	string	Дата обновления записи
cancel_reason_id	int	Идентификатор причины отмены
cancel_text	string	Комментарий отмены
problem_reason_id	int	Идентификатор причины проблемы

Пример запроса: /api/v1/orders?sort=desc&filters[status]=26&page[number]=1&page[size]=5

Информация о конкретном заказе

GET /api/v1/orders/[номер заказа]

Отдает информацию о конкретном заказе.

Возвраты

Запрос

GET /api/v1/returns

Отдает список возвратов. Во входных параметрах доступен массив filters с добавлением в него полей необходимых для фильтрации списка

Ответ

Ключ	Значение	Описание
id	int	Системный идентификатор возврата
number	string	Видимый всем номер возврата
return_status_date	string	Дата изменения статуса
return_route	array	Объект с информацией о маршруте возврата
return_method	array	Объект с информацией о методе возврата
delivery_service	array	Объект с информацией об ЛО
return_date	string	Дата возврата
return_timeslot	string	Желаемый таймслот для возврата
point_id	int	Идентификатор ПВЗ
store_id	int	Идентификатор склада
delivery_service_order_number	string	Номер заказа в ЛО
delivery_service_claim_number	string	Номер заявки в ЛО
delivery_cost	float	Стоимость доставки
return_from_address	array	Объект с информацией об адресе отправителя
items	array	Объект с информацией о возвращаемых товарах
returnStatus	array	Объект с информацией о статусе возврата

Пример запроса

http://127.0.0.1:8000/api/v1/returns?sort=desc&filters[order_id]=57&page[number]=1&page[size]=5

Получение информации о конкретном возврате

GET /api/v1/returns/[номер возврата]

Отдает информацию о конкретном возврате.

Список покупателей

GET /api/v1/clients

Отдает список покупателей.

Доступные параметры для фильтрации:

Ключ	Значения	Описание
status	array	int- идентификаторы статусов согласно статусной модели покупателей
phone	string	номер телефона пользовтеля
fullName	string	ФИО
gender	?int	Пол покупателя: 1- Женский 2- Мужской (не заполнено) - любой
createdBetween	array	Массив строк дат периода создания заказа, дата в формате “ГГГГ-ММ-ДД”
isReferral	bool или int(0|1)	Флаг реферального партнера

Пример запроса:

/api/v1/clients?filter%5BcreatedBetween%5D%5B%5D=2023-05-01&filter%5BcreatedBetween%5D%5B%5D=2023-06-01

Пример ответа:

{"status":"success","message":null,"data":[{"register_date":"17.05.2023 10:17","full_name":"Guest","phone":"[phone]","email":null,"status":"Активный"},{"register_date":"15.05.2023 15:04","full_name":"Guest","phone":"[phone]","email":null,"status":"Активный"}]}

Информация о конкретном получателе

GET /api/v1/clients/[id клиента]

Отдает информацию о конкретном клиенте.

Список категорий

GET /api/v1/categories

Выводит список категорий

Список атрибутов товаров в категории

GET /api/v1/categories[id категории]/properties

Список товаров

GET /api/v1/products

Выводит список товаров. Параметры с полями для фильтрации в разработке

Информация о товаре

GET /api/v1/products/[id товара]

Выводит информацию о конкретном товаре

Импорт товара

POST /api/v1/products

Формат json, может быть вложенным массивом items до 100 элементов (в разработке)

Параметры:

Ключ	Значение	Описание
name	string обязательное	Название
brand_id	int обязательное	id бренда
category_id	int обязательное	id категории
vendor_code	string может быть null	Артикул
xml_id	string обязательное	Внешний код
barcode	string обязательное	Штрих-код
weight	int необязательное	Вес
width	int необязательное	Ширина(см)
height	int необязательное	Высота(см)
length	int необязательное	Длина(см)
packaged_width	int необязательное	Ширина в упаковке (см)
packaged_height	int необязательное	Высота в упаковке (см)
packaged_length	int необязательное	Длина в упаковке (см)
packaged_weight	int необязательное	Вес в упаковке(гр)
gas	bool обязательное	Газ
explosive	bool обязательное	Взрывоопасное
has_battery	bool обязательное	Имеет аккумулятор
fragile	bool обязательное	Хрупкое
description	string обязательное	Описание
description_video	string может быть null	Ссылка на видео
need_special_case	string может быть null	Специальная упаковка
need_special_store	string может быть null	Специальные условия хранения
days_to_return	int может быть null	Дней на возврат

По умолчанию статус товара “Не согласовано” (1). Администратор маркетплейса может поменять статус по умолчанию через константу “DEFAULT_PRODUCT_APPROVAL_STATUS” в .env файле. Константа может принимать значения соответствующие этим статусам (integer):

“Не согласовано” - 1, “Отправлено” - 2, “На рассмотрении” - 3, “Отклонено” - 4, “Согласовано” - 5, “Сформировано” - 6

В ответе приходит id оффера и товара, пример:

{"product_id": 1058,"offer_id": 1101}

Список офферов

GET /api/v1/offers

Возвращает список офферов мерчанта

Информация об оффере

GET /api/v1/offers/[id оффера]

Возвращает информацию об оффере

Добавление оффера

POST /api/v1/offers

Формат json, может быть вложенным массивом items до 100 элементов (в разработке)

Параметры:

Ключ	Значение	Описание
product_id	int Обязательно	id товара
price	int Обязательно	цена
sale_status	int Обязательно	Идентификатор статуса согласно статусной модели оффера
sale_at	string Необязательно	дата начала продажи
stocks	array store_id int qty int	массив складов с остатками. Идентификатор склада Остатки

Статусная модель оффера id:

1 = В продаже

2 = Предзаказ

3 = Снято с продажи

4 = Доступен к продаже

5 = Недоступен к продаже

Пример запроса:

{"product_id":"1061","price":100,"sale_status":1,"sale_at":"","stocks":[{"store_id":"1","qty":100},{"store_id":"11","qty":200},{"store_id":"10","qty":20}]}

Ответ:

{"offer_id": 1106}

Обновление оффера

POST /api/v1/offers[id оффера]

Параметры аналогичны запросу на создание оффера

Массовое обновление цен

POST /api/v1/prices/set-prices

Массово обновляет цены офферам

Параметры:

Ключ	Значение	Описание
(array) prices	(int) offer_id обязательно (int) price обязательно	Массив Идентификатор оффера Цена

Пример запроса:

{"prices":[{"offer_id":350,"price":200},{"offer_id":973,"price":200}]}

Массовое обновление остатков

POST /api/v1/stocks/set-stocks

Массово обновляет остатки оффера на складах

Параметры:

Ключ	Значение	Описание
(array) stocks	(int) offer_id обязательно (int) store_id обязательно (int) product_id обязательно (int) qty обязательно	Массив Идентификатор оффера Идентификатор склада Идентификатор товара Количество остатков

Загрузка файлов/изображений

Изображения загружаются не непосредственно в файловый микросервис

POST [микросервис file-ms]/api/v1/files

Параметры:

Ключ	Значение	Описание
file	file обязательно	загружаемый файл
folder	string обязательно	Папка, например “catalog”

В ответе получаем идентификатор загруженного файла

Добавление изображения к товару

POST /api/v1/products/[id товара]/add-image

Добавляет изображение к товару

Параметры:

Ключ	Значение	Описание
id	int обязательно	идентификатор файла
type	int обязательно	Тип файла 2 - фото для каталога 3 - фото для галереи 4 - фото в описание товара

Пример запроса:

{ "id": "47049","type": 2}