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

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

Общие данные

Для отправки любых запросов требуется получить у администратора маркетплейса (МП) логин и пароль для авторизации.
Каждый запрос проходит basic-авторизацию, поля ответа фильтруются по id продавца (мерчанта) которому были выданы доступы та где это необходимо.
Ответ всегда приходит в формате 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 приходит список Отправлений мерчанта подходящую под фильтр в запросе:

Ключ

Значение

Описание

Системный идентификатор заказа

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):

Ключ

Значение

Описание

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

Объект с информацией о товаре

int

Системный идентификатор

weight, width, height, length

string

Характеристики ШВГ и вес

is_explosive

bool

Флаг взрывоопасного товара

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

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

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

Возвраты

Запрос

GET /api/v1/returns

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

Ответ

Ключ

Значение

Описание

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":"+79999999947","email":null,"status":"Активный"},{"register_date":"15.05.2023 15:04","full_name":"Guest","phone":"+79999552351","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

массив складов с остатками.

Идентификатор склада

Остатки

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

{"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

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

Параметры:

Ключ

Значение

Описание

int обязательно

идентификатор файла

type

int обязательно

Тип файла

2 - фото для каталога

3 - фото для галереи

4 - фото в описание товара

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

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

Last updated 12 days ago