Аналитика: API (1.0)

SelSup API — программный интерфейс для работы с сервисом SelSup. Он даёт возможность обмениваться информацией между системой продавца и SelSup.

Методы API позволяют использовать весь функционал сервиса SelSup для работы с маркетплейсами Ozon, Wildberries, Aliexpress, Яндекс.Маркет, СберМегаМаркет, Леруа Мерлен, кассами Эвотор и Авито. Работать со службами доставки.

SelSup позволяет создавать карточки на всех маркетплейсах, заполнять параметры, вести учет остатков товаров, принимать заказы по FBS с маркетплейсов и интернет-магазина, обновлять остатки на позиции, по которым пришел заказ. Вести аналитику продаж и учет финансов.

С помощью API вы можете подключить любые источники заказов к SelSup и вести быстрый учет остатков с маркетплейсов и сайта.

По умолчанию GET запросы используются для получения данных, все запросы на изменение данных отправляются методоми POST, DELETE, PUT, PATCH

Как передавать токен авторизации в запросах

curl "https://api.selsup.ru/api/product/findProduct" \
  -H "Authorization: token"

Проверьте, что у вас указан токен API вместо <token>. Он указан на странице добавления нового токена

Перейдите на страницу настройки API: https://selsup.ru/application/integration/api

Введите название нового токена в поле и нажмите кнопку Добавить токен. Название должно быть уникальным в рамках вашего аккаунта. Рекомендуется для разных сервисов использовать свои токены, чтобы в любой момент можно было отозвать токен.

Токен необходимо передавать в заголовке Authorization: токен

SelSup может отправлять запросы на внешние сервисы и так же получать информацию от внешних сервисов, в случае каких-то событий. Такими событиями могут быть:

• получение заказа с маркетплейса или от покупателя, в этом случае передается полная информация о заказе
• изменение остатка на товары, передается информация о товаре и новый остаток
• изменение цены на товар

Вы можете настроить Webhook, который будет отправлять HTTP/HTTPS запрос на адрес, который будет указан в кабинете. Возможна отправка POST или GET запроса в нужном формате с необходимыми заголовками.

Так вы сможете настроить интеграцию с любой собственной системой или сайтом.

Для поиска товаров используйте метод /api/product/find Он позволяет найти товары по фильтрам и поисковому запросу, либо просто получить все товары по порядку.

Для выбора всех товаров лучше передавать sortBy=ID, чтобы новые товары не изменяли порядок сортировки и отдавались в конце. Параметр count=true, позволяет отдать в ответе значение поля total - общего количества данных по запросу. Значение true необходимо передавать только в первом запросе или вообще не передавать, просто последовательно выбирать данные по страницам, пока количество товаров в ответе не будет меньше размера limit.

Метод не отдает полную информацию о товаре, только основные поля, которые отображаются на списке товаров. Чтобы получить полную информацию о карточке, необходимо запросить ее по ID модели из ответа rows[0].view.model.id и использовать метод /api/model/{modelId} для получения полной информации о карточке. Если вы хотите изменить товар, получив данные из ответа метода, можно использовать метод PATCH, который объединит данные с уже сохраненными, чтобы не затереть какие-то параметры.

Получает полную информацию о карточке модели со всеми полями. У модели есть список цветов colors и у каждого цвета есть список размеров: sizes.

В поиске product/find поиск производится только по наличию конечного размера, поэтому если вы добавите цвета или модель, но не укажите размеры, в поиске они находиться не будут.

Чтобы получить дополнительные параметры, передавайте параметр params=true и в ответе values будет отдаваться список значений для цвета, модели или товара.

Полный список полей

Позволяет получить всю информацию о карточке товара, включая все заполненные параметры для последующего изменения информации о товаре через метод POST/PUT model. В списке services передаются маркетплейсы или сервисы, в которые необходимо отправить карточку после сохранения.

Метод позволяет создать новый товар

Позволяет создавать карточку товара. Карточка состоит из нескольких цветов, у каждого цвета может быть несколько размеров. Если в вашей категории товаров нет разделения по цветам и размерам - то просто создается карточка с одним цветом и одним размером. Цвет указывать не обязательно, как и значения поля размера. Обязательно указывать только артикул у модели.

Штрих-коды если не указаны, будут автоматически сгенерированы SelSup, либо нужно указывать явно штрих-коды в карточке товара.

Полный список полей

Позволяет изменить информацию у существующей модели, добавить цвета или размеры. Так же при редактировании модели можно выставлять свойство hasChanges=false, чтобы не изменять некоторые цвета или размеры.

У каждой структуры ProductModel, ProductView и Product, есть список значений параметров. У каждого параметра есть идентификатор, который зачастую уникален в рамках всех категорий маркетплейса. Один параметр может повторяться в разных категориях. Мы всегда пытаемся максимально сохранять идентификатор параметра при любых изменения на маркетплейсе.

Значения можно определять на разных уровнях, при этом Product имеет самый высший приоритет, потом идут по порядку значения со следующим приоритетом: ProductView, ProductModel, Category

В некоторых случаях, на маркетплейс не могут быть переданы значения, записанные у размера, например на Wildberries, тк карточка Wildberries соответствует ProductView. Уровень параметра, указанный в Param.level служит лишь для определения уровня по умолчанию, на котором должно быть определено значение параметра.

Если у параметра проставлено multiValueAllowed, то может быть несколько ParamValue с одинаковым paramId для передачи параметров, у которых может быть несколько значений

В зависимости от типа параметра Param.valueType, должны проставляться соответствующие поля в значении ParamValue.

Получить список параметров можно через специальный компонент, который ежедневно обновляет список параметров для каждого маркетплейса. Параметры динамические - они могут постоянно добавляться и удаляться из категории, когда их правит маркетплейс - тк это параметры маркетплейсов:

https://params.selsup.ru/knowledge/getParams?ozonCategoryId=91025609&wildberriesTypeId=105&avitoCategoryId=103

Список значений может отдаваться для параметров с Param.valueType: "ENUM" или "TEXT" В этом случае у них обязательно будет проставлен Param.displayType: "SUGGEST", который говорит о том, что список значений нужно получать из ответа метода:

https://options.selsup.ru/option/fetchOption?aliexpressCategoryId=201236503&paramId=60019&useCategoryOption=true&query=123&limit=10

Полученные значения необходимо подставлять в качестве option у ParamValue в карточке товара. У значения всегда есть name, а вот идентификатор может вообще отсутствовать или может соответствовать идентификаторам значений на маркетплейсах

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

Позволяет найти бренды по запросу или фильтру. Идентификатор бренда необходимо использовать для создания товара.

Вы можете передавать новые заказы в SelSup по API, например с вашего интернет-магазина. В запросе необходимо передавать информацию о заказе и список товаров в заказе. В качестве уникального ключа, для того, чтобы не создавать дубликаты заказов используйте externalOrderId - номер заказа на сайте интернет-магазина.

Поле organizationId нужно обязательно передавать, если у вас в аккаунте несколько организаций.

Для передачи товаров необходимо предварительно связать товары сайта, с товарами в SelSup, чтобы потом передавать productId - идентификатор товара в SelSup. Сделать это можно, импортировав все товары методом findProduct

В позиции заказа в товаре quantity обязательно нужно передавать, как и цену товара price.

Вы можете передавать новые заказы в SelSup по API, например с вашего интернет-магазина. В запросе необходимо передавать информацию о заказе и список товаров в заказе. В качестве уникального ключа, для того, чтобы не создавать дубликаты используется externalOrderId

Возможные ошибки

В результате отдается JSON заказа, с проставленным значение id

{
  "message": "error_empty_warehouse"
}

В случае ошибки отдается код ответа 400, а в теле отдается message - с кодом ошибки и messageParams - дополнительные параметры сообщения об ошибке. Любые коды, отличные от 200 - ошибка запроса

С помощью запроса вы можете получить список заказов:

Параметр count отвечает за подсчет общего количества заказов по указанному запросу. Лучше передавать значение false, если вам не нужно знать общее количество заказов, тк подсчет количества может занимать продолжительное время, особенно если по запросу выбирается большое количество заказов. Лучше запрашивать постоянно изменяя параметр page, чтобы выбрать все данные, пока количество равно лимиту, который вы передаете в запросе.

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

curl "https://api.selsup.ru/api/order/find?type=FBS&modifiedDate=2024-06-20T15:00:00Z" \
  -H "Authorization: <token>"

Остатки товаров в SelSup привязываются к SKU - единице хранения на складе. Каждому товару присваивается свой номер SKU и в дальнейшем можно указать одинаковый SKU для нескольких разных товаров в SelSup.

Вы можете использовать две схемы хранения остатков в SelSup: 1)Когда на каждую штуку товара клеится отдельный уникальный код, по которому можно отслеживать всю историю товара и вы всегда можете отделить каждую единицу товара друг от друга. Данный уникальный стикер позволяет вам клеить его в удобное для быстрого поиска место товара, что существенно ускоряет сборку товаров на складе и их идентификацию - особенно если вы работаете с кодами маркировки честного знака 2)Когда остаток хранится просто к привязки к ячейке по штрих-коду. В этом случае в остатке записывается количество - сколько лежит определенного товара в данной ячейке.

Полный список полей

curl -X POST "https://api.selsup.ru/api/wms/changeStock?skuId=123&stock=5&warehouseId=123" \
  -H "Authorization: <token>"

В результате отдается 200 код ответа или 400 в случае ошибки

Позволяет для SKU изменить остатки товаров на складе. Работает для всех схем хранения, как с уникальными кодами, так и без них

Вы можете разрабатывать расширения SelSup, которые добавляют различные возможности в SelSup. Существует несколько возможных вариантов встраивания функций в SelSup

Вы можете разрабатывать расширения для SelSup реализуя функциональные React компоненты, которые встраиваются в различные места кабинета SelSup и взаимодействуют с API SelSup или API внешних сервисов. Внешнему сервису необходимо разрешить принимать запросы с домена selsup.ru. При этом вы можете использовать все стандартные компоненты SelSup и добавлять свои собственные

Клонируйте репозиторий демо-компонента SelSup и начните разрабатывать React-расширение.

https://github.com/SelSup/component

Вы можете реализовать на Java один из вариантов интеграции: маркетплейс (интеграция по остаткам, заказам, товарам, ценам) или служба доставки, реализовав соответствующий интерфейс SelSup. Код компонента попадет в основную ветку SelSup и будет доступен для использования вашим платным или бесплатным расширением. Вы сможете обновлять функции вашего расширения и изменения будут регулярно попадать в новые релизы SelSup.

Методы для работы с аналитическими отчетами: товарный, финансовый по всем маркетплейсам