Общая информация

Введение

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" \
  -H "Content-Type: application/json"

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

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

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

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

Webhooks

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

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

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

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

Примеры решений

Поиск товаров

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

GET https://api.selsup.ru/api/product/find?query=text&sortBy=ID
Authorization: ...
Content-Type: application/json

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

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

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

Получить информацию о карточке модели, вы можете с помощью метода:
/api/model/{modelId}

GET https://api.selsup.ru/api/model/1234/
Content-Type: application/json
Authorization: ...

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

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

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

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

PUT https://api.selsup.ru/api/model/1234/
Content-Type: application/json
Authorization: ...

{
//данные модели
}

В списке services передаются маркетплейсы или сервисы,
в которые необходимо отправить карточку после сохранения.

Создание модели

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

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

Обязательно указывать только артикул у модели.

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

Минимальный набор полей для создания карточки с товаром.

Бренд и категорию можно предварительно создать через соответствующие методы

POST https://api.selsup.ru/api/model/
Content-Type: application/json
Authorization: ...

{
  "article": "ModelArticle",
  "title": "Название модели",
  "brandId": 12303,
  "categoryId": 27640,
  "organizationId": 1,
  "views": [
    {
      "color": "color",
      "sizes": [
        {
          "name": "Название товара"
        }
      ]
    }
  ]
}

Редактирование модели

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

Позволяет изменить информацию у существующей модели, добавить цвета или размеры.
Так же при редактировании модели можно выставлять свойство 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 обязательно должна быть создана категория.

Список категорий можно получить методом /api/category/find:

GET https://api.selsup.ru/api/category/find?query=name
Content-Type: application/json
Authorization: ...

Создать категорию можно с помощью метода:

POST https://api.selsup.ru/api/category/
Content-Type: application/json
Authorization: ...

{
  "name": "New category name"
}

В ответе будет ID новой категории

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

Обязательным полем у категории является только название.

Поиск бренда

Список брендов можно получить методом /api/brand/find:

GET https://api.selsup.ru/api/brand/find?query=name
Content-Type: application/json
Authorization: ...

Создать бренд можно с помощью метода: /api/brand/

POST https://api.selsup.ru/api/brand/
Content-Type: application/json
Authorization: ...

{
  "name": "Test brand"
}

В ответе будет идентификатор бренда

Создание заказа с сайта

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

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

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

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

Полное описание метода создания заказа

POST https://api.selsup.ru/api/order/
Content-Type: application/json
Authorization: ...

{
  "type": "RETAIL",
  "organizationId": 1,
  "externalOrderId": "12345", //Не обязательное поле
  "products": [
    {
      "productId": 1422585,
      "quantity": 5,
      "price": 1000
    }
  ]
}

Создание отгрузки на маркетплейс

Вы можете передавать новые заказы в 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

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

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

Получить остатки товаров в SelSup вы можете методом
api/wms/stock/all по идентификатору склада:

GET https://api.selsup.ru/api/wms/stock/all?warehouseId=10129
Content-Type: application/json
Authorization: ...

В ответе будет JSON массив со всеми остатками по складу:
quantity - сколько доступно остатка
calculatedQuantity - сколько доступно рассчитанного остатка
sku - в объекте будет заполнен основной товар для данного SKU

[
  {
    "id": 1422612,
    "sku": {
      "product": {
        "id": 1422612,
        "deleted": false,
        "size": "0",
        "ozonArticle": "2045145255975",
        "skuId": 1044318,
        "barcodes": [],
        "quantity": 24,
        "cellId": 66,
        "site": "",
        "emptyBarcodes": true,
        "anyArticle": "2045145255975",
        "anyLink": ""
      }
    },
    "skuId": 1044318,
    "cell": {
      "id": 66,
      "warehouseId": 10129,
      "fullName": "А.1.1.1",
      "sortName": "А.1.1.1"
    },
    "cellId": 66,
    "modifyDate": 1762973011.000000000,
    "quantity": 24,
    "calculatedQuantity": 0,
    "availableQuantity": 24
  },
  {
    "id": 1423491,
    "sku": {
      "product": {
        "id": 1423491,
        "deleted": false,
        "size": "0",
        "skuId": 1044862,
        "barcodes": [],
        "quantity": 5,
        "cellId": 66,
        "site": "",
        "emptyBarcodes": true,
        "anyArticle": "",
        "anyLink": ""
      }
    },
    "skuId": 1044862,
    "cell": {
      "id": 66,
      "warehouseId": 10129,
      "fullName": "А.1.1.1",
      "sortName": "А.1.1.1"
    },
    "cellId": 66,
    "modifyDate": 1762973016.000000000,
    "quantity": 5,
    "calculatedQuantity": 0,
    "availableQuantity": 5
  }
]

Изменение остатков

Если вы хотите изменить остатки в SelSup, то необходимо использовать один из методов:

Изменение остатков по сущностям SelSup

В этом случае используется метод /api/wms/stock
В запросе передается skuId - идентификатор остатка у товара, его можно получить
в ответе /api/product/find в поле skuId.

В поле serviceWarehouseId необходимо передать ID склада SelSup

updateInService передавайте false, иначе метод будет долго отвечать, синхронно обновляя остатки
на маркетплейсах

withReservedStock обычно передается true, для учета резерва остатков в SelSup

POST https://api.selsup.ru/api/wms/stock
[
  {
    "stock": 5,
    "serviceWarehouseId": "1234",
    "updateInService": false,
    "withReservedStock": true,
    "skuId": 12345
  }
]

Изменение остатков по артикулу или штрих-коду

Вы так же можете изменять остатки товаров по артикулу маркетплейса или штрих-коду:
/api/wms/stock/{service}

При этом вместе service указывается сервис, артикул которого необходимо использовать для
поиска товаров у которых изменить остаток.

serviceWarehouseId - необходимо указать ваш ID склада в связях со складами для данного сервиса

Например обновление по артикулу 1С:

POST https://api.selsup.ru/api/wms/stock/1C
[
  {
    "stock": 5,
    "serviceProductId": "ID товара 1C в SelSup",
    "serviceWarehouseId": "ID склада 1C",
    "updateInService": false,
    "withReservedStock": true,
  }
]

Например обновление по штрих-коду:

POST https://api.selsup.ru/api/wms/stock/OZON
[
  {
    "stock": 5,
    "barcode": "123456789",
    "serviceWarehouseId": "ID склада Ozon",
    "updateInService": false,
    "withReservedStock": true,
  }
]

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

Добавление функций в магазин приложений

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

React-расширения

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

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

https://github.com/SelSup/component

Backend интеграции

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

Доступные API