Товары

Карточки товаров: названия, описания, категории, опции и фото. У вариантов свои методы; товар создаётся и пишется вместе с ними.

Загружаем поисковый индекс…

Товары

Объекты

Product

  • idintegerобязательно

    ID записи, уникальный среди записей своего вида в магазине.

  • external_idstring или nullобязательно

    Внешний id — id записи в вашей системе; null, если приложение его не задало. Каждое приложение видит только свои ID.

  • versionintegerобязательно

    Версия записи: растёт с каждым изменением. Чтобы изменить запись, передайте её как ETag в If-Match.

  • typestringобязательно

    Вид товара: goods — товар для продажи; dish — блюдо, готовится под заказ; ingredient — сырьё для техкарт; prep — полуфабрикат собственного приготовления; manufactured — продукция собственного производства; meal_program — программа питания по подписке; bundle — набор из других товаров; gift_card — подарочная карта; service — услуга по записи.

    Значения:
    goodsdishingredientprepmanufacturedmeal_programbundlegift_cardserviceservice_package
  • stock_unitobject или nullобязательно

    Единица учёта позиции со складом по мере (сырьё, заготовка, производимый товар): в ней остатки, тех-карты и выход. null у товара и блюда — их единица задаётся осью продажи варианта.

    Поля · 3
    • unitstringобязательно

      Базовая единица: g — граммы, ml — миллилитры, pcs — штуки. Количества вариантов товара — десятичные строки в этой единице.

      Значения:
      gmlpcs
    • purchase_unitstring или nullобязательно

      Название тары закупки, например кг или коробка; null — позицию закупают в базовой единице.

    • purchase_quantitystringобязательно

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

  • nameсловарь stringобязательно

    Название по языкам: объект заполненных языков, например {"es": "Café", "ru": "Кофе"}.

  • short_descriptionсловарь stringобязательно

    Краткое описание по языкам, простой текст для списков товаров.

  • descriptionсловарь stringобязательно

    Описание по языкам в Markdown (GitHub Flavored): объект заполненных языков.

  • slugstringобязательно

    Адрес товара на витрине, уникальный в магазине.

  • brand_idinteger или nullобязательно

    ID бренда товара; null, если не задан.

  • tax_class_idinteger или nullобязательно

    ID налогового класса товара (/v1/tax-classes); null — класс магазина по умолчанию. Продажа запоминает ставку позиции: смена класса меняет только будущие продажи.

  • category_idsмассив integerобязательно

    ID категорий товара по возрастанию.

  • primary_category_idinteger или nullобязательно

    Основная категория из category_ids; null, если основная не выбрана.

  • optionsмассив objectобязательно

    Опции, которыми различаются варианты, например размер или цвет, по порядку.

    Поля · 5
    • idintegerобязательно

      ID опции.

    • keystringобязательно

      Машинный ключ опции, уникальный в товаре, например size.

    • nameсловарь stringобязательно

      Название опции по языкам.

    • positionintegerобязательно

      Позиция опции: меньшая идёт первой.

    • valuesмассив objectобязательно

      Значения опции по порядку.

      Поля · 4
      • idintegerобязательно

        ID значения. Варианты ссылаются на него в option_values.

      • valueсловарь stringобязательно

        Значение по языкам, например {"es": "Rojo", "ru": "Красный"}.

      • swatch_colorstring или nullобязательно

        Цвет образца, шестнадцатеричный код вида #C0392B; null, если у значения нет образца.

      • positionintegerобязательно

        Позиция значения: меньшая идёт первой.

  • modifier_groupsмассив objectобязательно

    Группы модификаторов товара по порядку показа с правилом выбора на этом товаре. Надбавки опций по вариантам — GET /v1/products/{product}/modifier-groups; заменяет группы PUT того же адреса.

    Поля · 2
    • group_idintegerобязательно

      ID группы модификаторов (/v1/modifier-groups).

    • selection_ruleobject или nullобязательно

      Правило выбора на этом товаре вместо правила группы; null — правило группы.

      Поля · 2
      • min_selectintegerобязательно

        Сколько опций обязательно выбрать на этом товаре.

      • max_selectinteger или nullобязательно

        Сколько опций можно выбрать на этом товаре; null — без предела.

  • mediaмассив objectобязательно

    Фото и видео галереи по порядку: те же объекты, что в /v1/products/{product}/media.

    Поля · 7
    • idintegerобязательно

      ID файла в медиатеке. Файл стоит в галерее товара не больше одного раза.

    • kindstringобязательно

      image — фото, video — видео.

      Значения:
      imagevideo
    • urlstringобязательно

      Публичный адрес файла.

    • mimestringобязательно

      MIME-тип файла, например image/webp.

    • altсловарь stringобязательно

      Альтернативный текст по языкам — для экранных чтецов и поисковиков.

    • positionintegerобязательно

      Место в галерее, с нуля.

    • is_primarybooleanобязательно

      Главное фото: витрина показывает его первым.

  • is_activebooleanобязательно

    false снимает товар с продажи и скрывает его с витрины.

  • published_atstring (date-time) или nullобязательно

    Когда товар появляется на витрине; null — сразу.

  • unpublished_atstring (date-time) или nullобязательно

    Когда товар уходит с витрины; null — остаётся.

  • sale_scheduleмассив object или nullобязательно

    Когда позицию можно заказать — окна недели в часовом поясе магазина; null — всегда. Вне окна товар виден и кладётся в корзину, а оформление сверяет расписание со временем исполнения заказа.

    Поля · 3
    • daysмассив integerобязательно

      Дни окна по ISO: 1 — понедельник, 7 — воскресенье.

    • fromstringобязательно

      Начало окна, «HH:MM» по часам магазина.

    • tostringобязательно

      Конец окна, «HH:MM», сам момент не входит; «24:00» — до конца дня. Конец раньше начала — окно через полночь, оно принадлежит дню начала.

  • created_atstring (date-time)обязательно

    Когда запись создана.

  • updated_atstring (date-time)обязательно

    Когда запись менялась последний раз.

  • deleted_atstring (date-time) или nullобязательно

    Когда товар отправлен в архив вместе с вариантами; null у живого товара.

Методы

Товары: категории, опции и фото, без вариантов

get/products

Scope: catalog:read

Параметры

Строка запроса

  • limitinteger

    Размер страницы: до 250 записей; по умолчанию 50.

    Минимум:
    1
    Максимум:
    250
  • cursorstring

    Непрозрачный курсор: next_cursor предыдущей страницы или sync_cursor последней страницы, сохранённый прошлой синхронизацией. Список идёт в порядке коммитов, поэтому курсор синхронизации позже отдаёт только изменённое после него.

    Макс. длина:
    4096
  • updated_sincestring (date-time)

    Только записи, изменённые после этого момента, ISO 8601 с часовым поясом. Фильтр первой синхронизации; дальше — курсор.

    Шаблон:
    ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
  • include_deletedboolean

    true — отдавать и удалённые записи: архивные с заполненным deleted_at и стёртые из базы — отметками об удалении {id, deleted_at} в продолжении по курсору синхронизации. Включайте для синхронизации.

Ответы

200Успешно

application/json

  • dataмассив Productобязательно

    Записи страницы.

  • deletedмассив objectобязательно

    Записи, стёртые из базы с момента курсора, отметками об удалении: только с include_deleted=true в продолжении по курсору синхронизации.

    Поля · 2
    • idintegerобязательно

      ID стёртой записи.

    • deleted_atstring (date-time)обязательно

      Когда запись стёрта.

  • next_cursorstring или nullобязательно

    Курсор следующей страницы; null на последней.

  • has_morebooleanобязательно

    true, если есть следующая страница.

  • sync_cursorstring или nullобязательно

    На последней странице — курсор, с которого продолжить позже: по нему придёт только изменённое после этой страницы. null на остальных.

401Токена нет, он неверен, истёк или отозван

Заголовки

  • WWW-Authenticatestringобязательно

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer

application/problem+json

Возвращает Problem

403Запрос не разрешают тариф, IP-адрес или scopes токена

Заголовки

  • WWW-Authenticatestring

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Возвращает ForbiddenProblem

410Курсор синхронизации старше срока хранения удалений или выдан до восстановления базы

application/problem+json

Возвращает Problem

422Параметр неверен или неизвестен

application/problem+json

Возвращает ValidationProblem

429Лимит запросов исчерпан

Заголовки

  • Retry-Afterintegerобязательно

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает RateLimitProblem

503Магазин временно недоступен

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает Problem

Отказы метода

Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки

Пример запроса
curl "https://api.saleya.app/v1/products" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Пример ответа · 200
{
  "data": [
    {
      "id": 0,
      "external_id": "string",
      "version": 0,
      "type": "goods",
      "stock_unit": {
        "unit": "g",
        "purchase_unit": "string",
        "purchase_quantity": "string"
      },
      "name": {
        "key": "string"
      },
      "short_description": {
        "key": "string"
      },
      "description": {
        "key": "string"
      },
      "slug": "string",
      "brand_id": 0,
      "tax_class_id": 0,
      "category_ids": [
        0
      ],
      "primary_category_id": 0,
      "options": [
        {
          "id": 0,
          "key": "string",
          "name": {
            "key": "string"
          },
          "position": 0,
          "values": [
            {
              "id": 0,
              "value": {
                "key": "string"
              },
              "swatch_color": "string",
              "position": 0
            }
          ]
        }
      ],
      "modifier_groups": [
        {
          "group_id": 0,
          "selection_rule": {
            "min_select": 0,
            "max_select": 0
          }
        }
      ],
      "media": [
        {
          "id": 0,
          "kind": "image",
          "url": "string",
          "mime": "string",
          "alt": {
            "key": "string"
          },
          "position": 0,
          "is_primary": true
        }
      ],
      "is_active": true,
      "published_at": "2026-01-15T12:00:00Z",
      "unpublished_at": "2026-01-15T12:00:00Z",
      "sale_schedule": [
        {
          "days": [
            0
          ],
          "from": "string",
          "to": "string"
        }
      ],
      "created_at": "2026-01-15T12:00:00Z",
      "updated_at": "2026-01-15T12:00:00Z",
      "deleted_at": "2026-01-15T12:00:00Z"
    }
  ],
  "deleted": [
    {
      "id": 0,
      "deleted_at": "2026-01-15T12:00:00Z"
    }
  ],
  "next_cursor": "string",
  "has_more": true,
  "sync_cursor": "string"
}

Создать товар вместе с вариантами

post/products

Scope: catalog:write

Параметры

Заголовок

  • Idempotency-Keystring

    Уникальный ключ попытки, например UUID. Повтор с тем же ключом и телом получает сохранённый ответ вместо второй записи. Ключ живёт 24 часа.

    Мин. длина:
    1
    Макс. длина:
    255
    Пример:
    8e03978e-40d5-43e8-bc93-6894a57f9324

Тело запроса application/json

  • nameсловарь string или nullобязательно

    Название по языкам: объект заполненных языков, например {"es": "Café", "ru": "Кофе"}.

    Макс. длина:
    255
  • short_descriptionсловарь string или null или null

    Краткое описание по языкам, простой текст для списков товаров.

    Макс. длина:
    500
  • descriptionсловарь string или null или null

    Описание по языкам в Markdown (GitHub Flavored): объект заполненных языков.

    Макс. длина:
    50000
  • slugstring

    Адрес товара на витрине, уникальный в магазине.

    Макс. длина:
    160
  • brand_idinteger или null

    ID бренда товара; null, если не задан.

  • tax_class_idinteger или null

    ID налогового класса товара (/v1/tax-classes); null — класс магазина по умолчанию. Продажа запоминает ставку позиции: смена класса меняет только будущие продажи.

  • category_idsмассив integer

    ID категорий товара по возрастанию.

  • primary_category_idinteger или null

    Основная категория из category_ids; null, если основная не выбрана.

  • is_activeboolean

    false снимает товар с продажи и скрывает его с витрины.

  • published_atstring (date-time) или null

    Когда товар появляется на витрине; null — сразу.

  • unpublished_atstring (date-time) или null

    Когда товар уходит с витрины; null — остаётся.

  • sale_scheduleмассив object или null

    Когда позицию можно заказать — окна недели в часовом поясе магазина; null — всегда. Вне окна товар виден и кладётся в корзину, а оформление сверяет расписание со временем исполнения заказа.

    Макс. элементов:
    14
    Поля · 3
    • daysмассив integerобязательно

      Дни окна по ISO: 1 — понедельник, 7 — воскресенье.

      Мин. элементов:
      1
      Макс. элементов:
      7
      Минимум:
      1
      Максимум:
      7
    • fromstringобязательно

      Начало окна, «HH:MM» по часам магазина.

      Шаблон:
      ^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
    • tostringобязательно

      Конец окна, «HH:MM», сам момент не входит; «24:00» — до конца дня. Конец раньше начала — окно через полночь, оно принадлежит дню начала.

      Шаблон:
      ^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
  • typestring

    Вид товара: goods — товар для продажи; dish — блюдо, готовится под заказ; ingredient — сырьё для техкарт; prep — полуфабрикат собственного приготовления; manufactured — продукция собственного производства; meal_program — программа питания по подписке; bundle — набор из других товаров; gift_card — подарочная карта; service — услуга по записи.

    Значения:
    goodsdishingredientprep
  • stock_unitobject или null

    Единица учёта позиции со складом по мере (сырьё, заготовка, производимый товар): в ней остатки, тех-карты и выход. null у товара и блюда — их единица задаётся осью продажи варианта.

    Поля · 3
    • unitstring

      Базовая единица: g — граммы, ml — миллилитры, pcs — штуки. Количества вариантов товара — десятичные строки в этой единице.

      Значения:
      gmlpcs
    • purchase_unitstring или null

      Название тары закупки, например кг или коробка; null — позицию закупают в базовой единице.

      Макс. длина:
      16
    • purchase_quantitystring или null

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

      Макс. длина:
      32
  • external_idstring или null

    Внешний id — id записи в вашей системе; null, если приложение его не задало. Каждое приложение видит только свои ID.

  • variantsмассив objectобязательно

    Строки вариантов, записываемые вместе с карточкой. Строка находится по своему external_id: вариант товара с этим ID правится присланными полями, без такого — заводится; неупомянутые варианты не трогаются. Для создания товара нужна хотя бы одна строка с ценой.

    Мин. элементов:
    1
    Макс. элементов:
    200
    Поля · 23
    • external_idstring или null

      Внешний id варианта — его id в вашей системе: ключ, по которому находится строка.

    • skustring или null

      Артикул (SKU); null, если не задан.

      Макс. длина:
      64
    • nameсловарь string или null или null

      Название варианта по языкам, например {"es": "Grande"}.

      Макс. длина:
      255
    • priceintegerобязательно

      Цена за price_per_quantity единиц, целым в минимальных единицах currency.

      Минимум:
      0
      Максимум:
      10000000000
    • track_inventoryboolean

      Магазин ведёт остаток варианта; false — продаёт без учёта остатка.

    • is_activeboolean

      false снимает вариант с продажи.

    • positioninteger

      Позиция среди вариантов товара: меньшая идёт первой.

      Минимум:
      0
      Максимум:
      2147483647
    • list_priceinteger

      Цена, как её назначил владелец, в минимальных единицах list_price_currency; null — цена назначена в деньгах учёта (price). У такой позиции price считает система по курсу прайса и во входе его не принимает.

      Минимум:
      0
      Максимум:
      10000000000
    • list_price_currencystring или null

      Валюта назначенной цены (прайс магазина в чужой валюте); null — цена в валюте магазина currency. Во входе — валюта прайса магазина или currency.

      Значения:
      ARSUSDBRLCLPCOPMXNPENRUBnull
    • compare_at_priceinteger или null

      Цена до скидки, показывается зачёркнутой; null, если скидки нет.

      Максимум:
      10000000000
    • weight_gramsinteger или null

      Вес для доставки в граммах; null, если не задан.

      Минимум:
      0
      Максимум:
      2147483647
    • length_mminteger или null

      Длина упаковки в миллиметрах; null, если не задана.

      Минимум:
      0
      Максимум:
      2147483647
    • width_mminteger или null

      Ширина упаковки в миллиметрах; null, если не задана.

      Минимум:
      0
      Максимум:
      2147483647
    • height_mminteger или null

      Высота упаковки в миллиметрах; null, если не задана.

      Минимум:
      0
      Максимум:
      2147483647
    • sale_starts_atstring (date-time) или null

      Когда начинается распродажа: compare_at_price показывается с этого момента; null — без начала.

    • sale_ends_atstring (date-time) или null

      Когда распродажа заканчивается; null — без конца.

    • sold_bystring

      Как продаётся вариант: each — поштучно; weight — на вес; volume — на объём.

      Значения:
      eachweightvolume
    • price_per_quantitystring или null

      За сколько единиц цена, десятичной строкой: за одну штуку или за 1000 — цена килограмма у весового варианта. null, если у весового или объёмного варианта она не задана.

      Макс. длина:
      32
    • measure_stepstring или null

      Шаг количества в строке весового или объёмного варианта, в его единице; null, если не задан.

      Макс. длина:
      32
    • min_measure_qtystring или null

      Наименьшее количество в строке весового или объёмного варианта; null, если не задано.

      Макс. длина:
      32
    • max_measure_qtystring или null

      Наибольшее количество в строке весового или объёмного варианта; null, если не задано.

      Макс. длина:
      32
    • net_contentobject

      Мера нетто одной штуки: пачка 500 г, бутылка 1000 мл. У упаковки из нескольких единиц другого варианта выводится из него, у фасованной штуки — из её меры; записать можно только у обычного штучного варианта. null у весового и объёмного и у штуки без меры.

      Поля · 2
      • quantitystring

        Мера десятичной строкой в unit: "500", "0.5".

        Макс. длина:
        32
      • unitstring

        Единица меры: g — граммы; ml — миллилитры.

        Значения:
        gml
    • barcodesмассив object или null

      Штрихкоды варианта.

      Макс. элементов:
      20
      Поля · 3
      • typestringобязательно

        Символика: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix или other.

        Значения:
        ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
      • valuestringобязательно

        Штрихкод.

      • is_primaryboolean или null

        Основной штрихкод варианта: его печатают этикетки и чеки.

Ответы

201Создано

Заголовки

  • Idempotent-Replayedstring

    true, когда это сохранённый ответ более раннего запроса с тем же Idempotency-Key.

    Значения:
    true
  • ETagstringобязательно

    Версия записи. Передайте её в If-Match, чтобы изменить запись.

    Пример:
    "7"
  • Locationstring (uri)обязательно

    Адрес созданной записи, а у принятого к исполнению (202) — адрес, где следить за исходом.

application/json

Возвращает Product

401Токена нет, он неверен, истёк или отозван

Заголовки

  • WWW-Authenticatestringобязательно

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer

application/problem+json

Возвращает Problem

403Запрос не разрешают тариф, IP-адрес или scopes токена

Заголовки

  • WWW-Authenticatestring

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Возвращает ForbiddenProblem

409Запрос с тем же ключом идемпотентности ещё исполняется, данные изменились после чтения, внешний id у другой записи, исчерпан лимит тарифа или адресов вебхуков, или правке нужно согласие на последствия

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает ConflictProblem

422Параметр неверен или неизвестен

application/problem+json

Возвращает ValidationProblem

429Лимит запросов исчерпан

Заголовки

  • Retry-Afterintegerобязательно

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает RateLimitProblem

503Магазин временно недоступен

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает Problem

Отказы метода

Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки

Пример запроса
curl -X POST "https://api.saleya.app/v1/products" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Тело запроса — body.json
{
  "name": {
    "key": "string"
  },
  "short_description": {
    "key": "string"
  },
  "description": {
    "key": "string"
  },
  "slug": "string",
  "brand_id": 0,
  "tax_class_id": 0,
  "category_ids": [
    0
  ],
  "primary_category_id": 0,
  "is_active": true,
  "published_at": "2026-01-15T12:00:00Z",
  "unpublished_at": "2026-01-15T12:00:00Z",
  "sale_schedule": [
    {
      "days": [
        1
      ],
      "from": "string",
      "to": "string"
    }
  ],
  "type": "goods",
  "stock_unit": {
    "unit": "g",
    "purchase_unit": "string",
    "purchase_quantity": "string"
  },
  "external_id": "string",
  "variants": [
    {
      "external_id": "string",
      "sku": "string",
      "name": {
        "key": "string"
      },
      "price": 0,
      "track_inventory": true,
      "is_active": true,
      "position": 0,
      "list_price": 0,
      "list_price_currency": "ARS",
      "compare_at_price": 0,
      "weight_grams": 0,
      "length_mm": 0,
      "width_mm": 0,
      "height_mm": 0,
      "sale_starts_at": "2026-01-15T12:00:00Z",
      "sale_ends_at": "2026-01-15T12:00:00Z",
      "sold_by": "each",
      "price_per_quantity": "string",
      "measure_step": "string",
      "min_measure_qty": "string",
      "max_measure_qty": "string",
      "net_content": {
        "quantity": "string",
        "unit": "g"
      },
      "barcodes": [
        {
          "type": "ean13",
          "value": "string",
          "is_primary": true
        }
      ]
    }
  ]
}
Пример ответа · 201
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "type": "goods",
  "stock_unit": {
    "unit": "g",
    "purchase_unit": "string",
    "purchase_quantity": "string"
  },
  "name": {
    "key": "string"
  },
  "short_description": {
    "key": "string"
  },
  "description": {
    "key": "string"
  },
  "slug": "string",
  "brand_id": 0,
  "tax_class_id": 0,
  "category_ids": [
    0
  ],
  "primary_category_id": 0,
  "options": [
    {
      "id": 0,
      "key": "string",
      "name": {
        "key": "string"
      },
      "position": 0,
      "values": [
        {
          "id": 0,
          "value": {
            "key": "string"
          },
          "swatch_color": "string",
          "position": 0
        }
      ]
    }
  ],
  "modifier_groups": [
    {
      "group_id": 0,
      "selection_rule": {
        "min_select": 0,
        "max_select": 0
      }
    }
  ],
  "media": [
    {
      "id": 0,
      "kind": "image",
      "url": "string",
      "mime": "string",
      "alt": {
        "key": "string"
      },
      "position": 0,
      "is_primary": true
    }
  ],
  "is_active": true,
  "published_at": "2026-01-15T12:00:00Z",
  "unpublished_at": "2026-01-15T12:00:00Z",
  "sale_schedule": [
    {
      "days": [
        0
      ],
      "from": "string",
      "to": "string"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Товар

get/products/{product}

Scope: catalog:read

Параметры

Путь

  • productintegerобязательно

    ID товара.

Ответы

200Успешно

Заголовки

  • ETagstringобязательно

    Версия записи. Передайте её в If-Match, чтобы изменить запись.

    Пример:
    "7"

application/json

Возвращает Product

401Токена нет, он неверен, истёк или отозван

Заголовки

  • WWW-Authenticatestringобязательно

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer

application/problem+json

Возвращает Problem

403Запрос не разрешают тариф, IP-адрес или scopes токена

Заголовки

  • WWW-Authenticatestring

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Возвращает ForbiddenProblem

404Объекта нет или он недоступен приложению

application/problem+json

Возвращает Problem

422Параметр неверен или неизвестен

application/problem+json

Возвращает ValidationProblem

429Лимит запросов исчерпан

Заголовки

  • Retry-Afterintegerобязательно

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает RateLimitProblem

503Магазин временно недоступен

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает Problem

Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки

Пример запроса
curl "https://api.saleya.app/v1/products/{product}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Пример ответа · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "type": "goods",
  "stock_unit": {
    "unit": "g",
    "purchase_unit": "string",
    "purchase_quantity": "string"
  },
  "name": {
    "key": "string"
  },
  "short_description": {
    "key": "string"
  },
  "description": {
    "key": "string"
  },
  "slug": "string",
  "brand_id": 0,
  "tax_class_id": 0,
  "category_ids": [
    0
  ],
  "primary_category_id": 0,
  "options": [
    {
      "id": 0,
      "key": "string",
      "name": {
        "key": "string"
      },
      "position": 0,
      "values": [
        {
          "id": 0,
          "value": {
            "key": "string"
          },
          "swatch_color": "string",
          "position": 0
        }
      ]
    }
  ],
  "modifier_groups": [
    {
      "group_id": 0,
      "selection_rule": {
        "min_select": 0,
        "max_select": 0
      }
    }
  ],
  "media": [
    {
      "id": 0,
      "kind": "image",
      "url": "string",
      "mime": "string",
      "alt": {
        "key": "string"
      },
      "position": 0,
      "is_primary": true
    }
  ],
  "is_active": true,
  "published_at": "2026-01-15T12:00:00Z",
  "unpublished_at": "2026-01-15T12:00:00Z",
  "sale_schedule": [
    {
      "days": [
        0
      ],
      "from": "string",
      "to": "string"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Изменить карточку товара: поля, категории, внешний id

patch/products/{product}

Scope: catalog:write

Параметры

Путь

  • productintegerобязательно

    ID товара.

Заголовок

  • Idempotency-Keystring

    Уникальный ключ попытки, например UUID. Повтор с тем же ключом и телом получает сохранённый ответ вместо второй записи. Ключ живёт 24 часа.

    Мин. длина:
    1
    Макс. длина:
    255
    Пример:
    8e03978e-40d5-43e8-bc93-6894a57f9324
  • If-Matchstringобязательно

    ETag записи из последнего чтения, например "7". Правка применится, только если запись с тех пор никто не менял, иначе 412. Без заголовка — 428.

    Пример:
    "7"

Тело запроса application/json

  • nameсловарь string или null

    Название по языкам: объект заполненных языков, например {"es": "Café", "ru": "Кофе"}.

    Макс. длина:
    255
  • short_descriptionсловарь string или null или null

    Краткое описание по языкам, простой текст для списков товаров.

    Макс. длина:
    500
  • descriptionсловарь string или null или null

    Описание по языкам в Markdown (GitHub Flavored): объект заполненных языков.

    Макс. длина:
    50000
  • slugstring

    Адрес товара на витрине, уникальный в магазине.

    Макс. длина:
    160
  • brand_idinteger или null

    ID бренда товара; null, если не задан.

  • tax_class_idinteger или null

    ID налогового класса товара (/v1/tax-classes); null — класс магазина по умолчанию. Продажа запоминает ставку позиции: смена класса меняет только будущие продажи.

  • category_idsмассив integer

    ID категорий товара по возрастанию.

  • primary_category_idinteger или null

    Основная категория из category_ids; null, если основная не выбрана.

  • is_activeboolean

    false снимает товар с продажи и скрывает его с витрины.

  • published_atstring (date-time) или null

    Когда товар появляется на витрине; null — сразу.

  • unpublished_atstring (date-time) или null

    Когда товар уходит с витрины; null — остаётся.

  • sale_scheduleмассив object или null

    Когда позицию можно заказать — окна недели в часовом поясе магазина; null — всегда. Вне окна товар виден и кладётся в корзину, а оформление сверяет расписание со временем исполнения заказа.

    Макс. элементов:
    14
    Поля · 3
    • daysмассив integerобязательно

      Дни окна по ISO: 1 — понедельник, 7 — воскресенье.

      Мин. элементов:
      1
      Макс. элементов:
      7
      Минимум:
      1
      Максимум:
      7
    • fromstringобязательно

      Начало окна, «HH:MM» по часам магазина.

      Шаблон:
      ^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
    • tostringобязательно

      Конец окна, «HH:MM», сам момент не входит; «24:00» — до конца дня. Конец раньше начала — окно через полночь, оно принадлежит дню начала.

      Шаблон:
      ^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
  • external_idstring или null

    Внешний id — id записи в вашей системе; null, если приложение его не задало. Каждое приложение видит только свои ID.

  • variantsмассив object

    Строки вариантов, записываемые вместе с карточкой. Строка находится по своему external_id: вариант товара с этим ID правится присланными полями, без такого — заводится; неупомянутые варианты не трогаются. Для создания товара нужна хотя бы одна строка с ценой.

    Мин. элементов:
    1
    Макс. элементов:
    200
    Поля · 24
    • external_idstring или null

      Внешний id варианта — его id в вашей системе: ключ, по которому находится строка.

    • skustring или null

      Артикул (SKU); null, если не задан.

      Макс. длина:
      64
    • nameсловарь string или null или null

      Название варианта по языкам, например {"es": "Grande"}.

      Макс. длина:
      255
    • priceinteger

      Цена за price_per_quantity единиц, целым в минимальных единицах currency.

      Минимум:
      0
      Максимум:
      10000000000
    • track_inventoryboolean

      Магазин ведёт остаток варианта; false — продаёт без учёта остатка.

    • is_activeboolean

      false снимает вариант с продажи.

    • positioninteger

      Позиция среди вариантов товара: меньшая идёт первой.

      Минимум:
      0
      Максимум:
      2147483647
    • list_priceinteger

      Цена, как её назначил владелец, в минимальных единицах list_price_currency; null — цена назначена в деньгах учёта (price). У такой позиции price считает система по курсу прайса и во входе его не принимает.

      Минимум:
      0
      Максимум:
      10000000000
    • list_price_currencystring или null

      Валюта назначенной цены (прайс магазина в чужой валюте); null — цена в валюте магазина currency. Во входе — валюта прайса магазина или currency.

      Значения:
      ARSUSDBRLCLPCOPMXNPENRUBnull
    • compare_at_priceinteger или null

      Цена до скидки, показывается зачёркнутой; null, если скидки нет.

      Максимум:
      10000000000
    • weight_gramsinteger или null

      Вес для доставки в граммах; null, если не задан.

      Минимум:
      0
      Максимум:
      2147483647
    • length_mminteger или null

      Длина упаковки в миллиметрах; null, если не задана.

      Минимум:
      0
      Максимум:
      2147483647
    • width_mminteger или null

      Ширина упаковки в миллиметрах; null, если не задана.

      Минимум:
      0
      Максимум:
      2147483647
    • height_mminteger или null

      Высота упаковки в миллиметрах; null, если не задана.

      Минимум:
      0
      Максимум:
      2147483647
    • sale_starts_atstring (date-time) или null

      Когда начинается распродажа: compare_at_price показывается с этого момента; null — без начала.

    • sale_ends_atstring (date-time) или null

      Когда распродажа заканчивается; null — без конца.

    • sold_bystring

      Как продаётся вариант: each — поштучно; weight — на вес; volume — на объём.

      Значения:
      eachweightvolume
    • price_per_quantitystring или null

      За сколько единиц цена, десятичной строкой: за одну штуку или за 1000 — цена килограмма у весового варианта. null, если у весового или объёмного варианта она не задана.

      Макс. длина:
      32
    • measure_stepstring или null

      Шаг количества в строке весового или объёмного варианта, в его единице; null, если не задан.

      Макс. длина:
      32
    • min_measure_qtystring или null

      Наименьшее количество в строке весового или объёмного варианта; null, если не задано.

      Макс. длина:
      32
    • max_measure_qtystring или null

      Наибольшее количество в строке весового или объёмного варианта; null, если не задано.

      Макс. длина:
      32
    • net_contentobject

      Мера нетто одной штуки: пачка 500 г, бутылка 1000 мл. У упаковки из нескольких единиц другого варианта выводится из него, у фасованной штуки — из её меры; записать можно только у обычного штучного варианта. null у весового и объёмного и у штуки без меры.

      Поля · 2
      • quantitystring

        Мера десятичной строкой в unit: "500", "0.5".

        Макс. длина:
        32
      • unitstring

        Единица меры: g — граммы; ml — миллилитры.

        Значения:
        gml
    • barcodesмассив object или null

      Штрихкоды варианта.

      Макс. элементов:
      20
      Поля · 3
      • typestringобязательно

        Символика: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix или other.

        Значения:
        ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
      • valuestringобязательно

        Штрихкод.

      • is_primaryboolean или null

        Основной штрихкод варианта: его печатают этикетки и чеки.

    • option_valuesмассив object

      Значения опций варианта: по одному значению каждой опции товара.

      Макс. элементов:
      10
      Поля · 2
      • option_idintegerобязательно

        ID опции из options товара.

      • value_idintegerобязательно

        ID значения из values этой опции.

Ответы

200Успешно

Заголовки

  • Idempotent-Replayedstring

    true, когда это сохранённый ответ более раннего запроса с тем же Idempotency-Key.

    Значения:
    true
  • ETagstringобязательно

    Версия записи. Передайте её в If-Match, чтобы изменить запись.

    Пример:
    "7"

application/json

Возвращает Product

401Токена нет, он неверен, истёк или отозван

Заголовки

  • WWW-Authenticatestringобязательно

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer

application/problem+json

Возвращает Problem

403Запрос не разрешают тариф, IP-адрес или scopes токена

Заголовки

  • WWW-Authenticatestring

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Возвращает ForbiddenProblem

404Объекта нет или он недоступен приложению

application/problem+json

Возвращает Problem

409Запрос с тем же ключом идемпотентности ещё исполняется, данные изменились после чтения, внешний id у другой записи, исчерпан лимит тарифа или адресов вебхуков, или правке нужно согласие на последствия

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает ConflictProblem

412Запись изменилась после чтения: версия в If-Match не текущая

application/problem+json

Возвращает Problem

422Параметр неверен или неизвестен

application/problem+json

Возвращает ValidationProblem

428Запросу нужен If-Match с ETag записи

application/problem+json

Возвращает Problem

429Лимит запросов исчерпан

Заголовки

  • Retry-Afterintegerобязательно

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает RateLimitProblem

503Магазин временно недоступен

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает Problem

Отказы метода

Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки

Пример запроса
curl -X PATCH "https://api.saleya.app/v1/products/{product}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Тело запроса — body.json
{
  "name": {
    "key": "string"
  },
  "short_description": {
    "key": "string"
  },
  "description": {
    "key": "string"
  },
  "slug": "string",
  "brand_id": 0,
  "tax_class_id": 0,
  "category_ids": [
    0
  ],
  "primary_category_id": 0,
  "is_active": true,
  "published_at": "2026-01-15T12:00:00Z",
  "unpublished_at": "2026-01-15T12:00:00Z",
  "sale_schedule": [
    {
      "days": [
        1
      ],
      "from": "string",
      "to": "string"
    }
  ],
  "external_id": "string",
  "variants": [
    {
      "external_id": "string",
      "sku": "string",
      "name": {
        "key": "string"
      },
      "price": 0,
      "track_inventory": true,
      "is_active": true,
      "position": 0,
      "list_price": 0,
      "list_price_currency": "ARS",
      "compare_at_price": 0,
      "weight_grams": 0,
      "length_mm": 0,
      "width_mm": 0,
      "height_mm": 0,
      "sale_starts_at": "2026-01-15T12:00:00Z",
      "sale_ends_at": "2026-01-15T12:00:00Z",
      "sold_by": "each",
      "price_per_quantity": "string",
      "measure_step": "string",
      "min_measure_qty": "string",
      "max_measure_qty": "string",
      "net_content": {
        "quantity": "string",
        "unit": "g"
      },
      "barcodes": [
        {
          "type": "ean13",
          "value": "string",
          "is_primary": true
        }
      ],
      "option_values": [
        {
          "option_id": 0,
          "value_id": 0
        }
      ]
    }
  ]
}
Пример ответа · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "type": "goods",
  "stock_unit": {
    "unit": "g",
    "purchase_unit": "string",
    "purchase_quantity": "string"
  },
  "name": {
    "key": "string"
  },
  "short_description": {
    "key": "string"
  },
  "description": {
    "key": "string"
  },
  "slug": "string",
  "brand_id": 0,
  "tax_class_id": 0,
  "category_ids": [
    0
  ],
  "primary_category_id": 0,
  "options": [
    {
      "id": 0,
      "key": "string",
      "name": {
        "key": "string"
      },
      "position": 0,
      "values": [
        {
          "id": 0,
          "value": {
            "key": "string"
          },
          "swatch_color": "string",
          "position": 0
        }
      ]
    }
  ],
  "modifier_groups": [
    {
      "group_id": 0,
      "selection_rule": {
        "min_select": 0,
        "max_select": 0
      }
    }
  ],
  "media": [
    {
      "id": 0,
      "kind": "image",
      "url": "string",
      "mime": "string",
      "alt": {
        "key": "string"
      },
      "position": 0,
      "is_primary": true
    }
  ],
  "is_active": true,
  "published_at": "2026-01-15T12:00:00Z",
  "unpublished_at": "2026-01-15T12:00:00Z",
  "sale_schedule": [
    {
      "days": [
        0
      ],
      "from": "string",
      "to": "string"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Архивировать товар вместе с вариантами

delete/products/{product}

Scope: catalog:write

Параметры

Путь

  • productintegerобязательно

    ID товара.

Строка запроса

  • consentobject

    Согласия на последствия правки по видам: consent[<consent_kind>]=<consent_token> из ответа 409 consent_required. Уже данные согласия сохраняются, когда спрашивается следующий вид.

    Поля · 4
    • recipe_ingredientstring

      Позиция — ингредиент действующих техкарт и уйдёт из них.

      Мин. длина:
      64
      Макс. длина:
      64
    • production_draftstring

      Черновики производственных актов с позицией будут отменены.

      Мин. длина:
      64
      Макс. длина:
      64
    • program_menustring

      Блюдо уйдёт из меню программ питания по подписке.

      Мин. длина:
      64
      Макс. длина:
      64
    • live_subscriptionsstring

      Программа с действующими подписками уйдёт из продажи.

      Мин. длина:
      64
      Макс. длина:
      64

Заголовок

  • Idempotency-Keystring

    Уникальный ключ попытки, например UUID. Повтор с тем же ключом и телом получает сохранённый ответ вместо второй записи. Ключ живёт 24 часа.

    Мин. длина:
    1
    Макс. длина:
    255
    Пример:
    8e03978e-40d5-43e8-bc93-6894a57f9324
  • If-Matchstringобязательно

    ETag записи из последнего чтения, например "7". Правка применится, только если запись с тех пор никто не менял, иначе 412. Без заголовка — 428.

    Пример:
    "7"

Ответы

204Успешно

Заголовки

  • Idempotent-Replayedstring

    true, когда это сохранённый ответ более раннего запроса с тем же Idempotency-Key.

    Значения:
    true

Без тела

401Токена нет, он неверен, истёк или отозван

Заголовки

  • WWW-Authenticatestringобязательно

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer

application/problem+json

Возвращает Problem

403Запрос не разрешают тариф, IP-адрес или scopes токена

Заголовки

  • WWW-Authenticatestring

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Возвращает ForbiddenProblem

404Объекта нет или он недоступен приложению

application/problem+json

Возвращает Problem

409Запрос с тем же ключом идемпотентности ещё исполняется, данные изменились после чтения, внешний id у другой записи, исчерпан лимит тарифа или адресов вебхуков, или правке нужно согласие на последствия

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает ConflictProblem

412Запись изменилась после чтения: версия в If-Match не текущая

application/problem+json

Возвращает Problem

422Параметр неверен или неизвестен

application/problem+json

Возвращает ValidationProblem

428Запросу нужен If-Match с ETag записи

application/problem+json

Возвращает Problem

429Лимит запросов исчерпан

Заголовки

  • Retry-Afterintegerобязательно

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает RateLimitProblem

503Магазин временно недоступен

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает Problem

Отказы метода

Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки

Пример запроса
curl -X DELETE "https://api.saleya.app/v1/products/{product}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"'

Товар по внешнему id

get/products/by-external-id/{external_id}

Scope: catalog:read

Параметры

Путь

  • external_idstringобязательно

    Внешний id — id записи в вашей системе.

Ответы

200Успешно

Заголовки

  • ETagstringобязательно

    Версия записи. Передайте её в If-Match, чтобы изменить запись.

    Пример:
    "7"

application/json

Возвращает Product

401Токена нет, он неверен, истёк или отозван

Заголовки

  • WWW-Authenticatestringобязательно

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer

application/problem+json

Возвращает Problem

403Запрос не разрешают тариф, IP-адрес или scopes токена

Заголовки

  • WWW-Authenticatestring

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Возвращает ForbiddenProblem

404Объекта нет или он недоступен приложению

application/problem+json

Возвращает Problem

422Параметр неверен или неизвестен

application/problem+json

Возвращает ValidationProblem

429Лимит запросов исчерпан

Заголовки

  • Retry-Afterintegerобязательно

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает RateLimitProblem

503Магазин временно недоступен

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает Problem

Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки

Пример запроса
curl "https://api.saleya.app/v1/products/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Пример ответа · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "type": "goods",
  "stock_unit": {
    "unit": "g",
    "purchase_unit": "string",
    "purchase_quantity": "string"
  },
  "name": {
    "key": "string"
  },
  "short_description": {
    "key": "string"
  },
  "description": {
    "key": "string"
  },
  "slug": "string",
  "brand_id": 0,
  "tax_class_id": 0,
  "category_ids": [
    0
  ],
  "primary_category_id": 0,
  "options": [
    {
      "id": 0,
      "key": "string",
      "name": {
        "key": "string"
      },
      "position": 0,
      "values": [
        {
          "id": 0,
          "value": {
            "key": "string"
          },
          "swatch_color": "string",
          "position": 0
        }
      ]
    }
  ],
  "modifier_groups": [
    {
      "group_id": 0,
      "selection_rule": {
        "min_select": 0,
        "max_select": 0
      }
    }
  ],
  "media": [
    {
      "id": 0,
      "kind": "image",
      "url": "string",
      "mime": "string",
      "alt": {
        "key": "string"
      },
      "position": 0,
      "is_primary": true
    }
  ],
  "is_active": true,
  "published_at": "2026-01-15T12:00:00Z",
  "unpublished_at": "2026-01-15T12:00:00Z",
  "sale_schedule": [
    {
      "days": [
        0
      ],
      "from": "string",
      "to": "string"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Создать или изменить товар вместе с вариантами по внешнему id

patch/products/by-external-id/{external_id}

Scope: catalog:write

Параметры

Путь

  • external_idstringобязательно

    Внешний id — id записи в вашей системе.

Заголовок

  • Idempotency-Keystring

    Уникальный ключ попытки, например UUID. Повтор с тем же ключом и телом получает сохранённый ответ вместо второй записи. Ключ живёт 24 часа.

    Мин. длина:
    1
    Макс. длина:
    255
    Пример:
    8e03978e-40d5-43e8-bc93-6894a57f9324
  • If-Matchstring

    ETag записи из последнего чтения. Обязателен, если запись с этим внешним id уже есть (иначе 428), и не передаётся, если её нет.

    Пример:
    "7"
  • If-None-Matchstring

    * — только создать: если запись с этим внешним id уже есть, запрос получит 412.

    Значения:
    *

Тело запроса application/json

  • nameсловарь string или null

    Название по языкам: объект заполненных языков, например {"es": "Café", "ru": "Кофе"}.

    Макс. длина:
    255
  • short_descriptionсловарь string или null или null

    Краткое описание по языкам, простой текст для списков товаров.

    Макс. длина:
    500
  • descriptionсловарь string или null или null

    Описание по языкам в Markdown (GitHub Flavored): объект заполненных языков.

    Макс. длина:
    50000
  • slugstring

    Адрес товара на витрине, уникальный в магазине.

    Макс. длина:
    160
  • brand_idinteger или null

    ID бренда товара; null, если не задан.

  • tax_class_idinteger или null

    ID налогового класса товара (/v1/tax-classes); null — класс магазина по умолчанию. Продажа запоминает ставку позиции: смена класса меняет только будущие продажи.

  • category_idsмассив integer

    ID категорий товара по возрастанию.

  • primary_category_idinteger или null

    Основная категория из category_ids; null, если основная не выбрана.

  • is_activeboolean

    false снимает товар с продажи и скрывает его с витрины.

  • published_atstring (date-time) или null

    Когда товар появляется на витрине; null — сразу.

  • unpublished_atstring (date-time) или null

    Когда товар уходит с витрины; null — остаётся.

  • sale_scheduleмассив object или null

    Когда позицию можно заказать — окна недели в часовом поясе магазина; null — всегда. Вне окна товар виден и кладётся в корзину, а оформление сверяет расписание со временем исполнения заказа.

    Макс. элементов:
    14
    Поля · 3
    • daysмассив integerобязательно

      Дни окна по ISO: 1 — понедельник, 7 — воскресенье.

      Мин. элементов:
      1
      Макс. элементов:
      7
      Минимум:
      1
      Максимум:
      7
    • fromstringобязательно

      Начало окна, «HH:MM» по часам магазина.

      Шаблон:
      ^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
    • tostringобязательно

      Конец окна, «HH:MM», сам момент не входит; «24:00» — до конца дня. Конец раньше начала — окно через полночь, оно принадлежит дню начала.

      Шаблон:
      ^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
  • typestring

    Вид товара: goods — товар для продажи; dish — блюдо, готовится под заказ; ingredient — сырьё для техкарт; prep — полуфабрикат собственного приготовления; manufactured — продукция собственного производства; meal_program — программа питания по подписке; bundle — набор из других товаров; gift_card — подарочная карта; service — услуга по записи.

    Значения:
    goodsdishingredientprep
  • stock_unitobject или null

    Единица учёта позиции со складом по мере (сырьё, заготовка, производимый товар): в ней остатки, тех-карты и выход. null у товара и блюда — их единица задаётся осью продажи варианта.

    Поля · 3
    • unitstring

      Базовая единица: g — граммы, ml — миллилитры, pcs — штуки. Количества вариантов товара — десятичные строки в этой единице.

      Значения:
      gmlpcs
    • purchase_unitstring или null

      Название тары закупки, например кг или коробка; null — позицию закупают в базовой единице.

      Макс. длина:
      16
    • purchase_quantitystring или null

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

      Макс. длина:
      32
  • variantsмассив object

    Строки вариантов, записываемые вместе с карточкой. Строка находится по своему external_id: вариант товара с этим ID правится присланными полями, без такого — заводится; неупомянутые варианты не трогаются. Для создания товара нужна хотя бы одна строка с ценой.

    Мин. элементов:
    1
    Макс. элементов:
    200
    Поля · 24
    • external_idstring или null

      Внешний id варианта — его id в вашей системе: ключ, по которому находится строка.

    • skustring или null

      Артикул (SKU); null, если не задан.

      Макс. длина:
      64
    • nameсловарь string или null или null

      Название варианта по языкам, например {"es": "Grande"}.

      Макс. длина:
      255
    • priceinteger

      Цена за price_per_quantity единиц, целым в минимальных единицах currency.

      Минимум:
      0
      Максимум:
      10000000000
    • track_inventoryboolean

      Магазин ведёт остаток варианта; false — продаёт без учёта остатка.

    • is_activeboolean

      false снимает вариант с продажи.

    • positioninteger

      Позиция среди вариантов товара: меньшая идёт первой.

      Минимум:
      0
      Максимум:
      2147483647
    • list_priceinteger

      Цена, как её назначил владелец, в минимальных единицах list_price_currency; null — цена назначена в деньгах учёта (price). У такой позиции price считает система по курсу прайса и во входе его не принимает.

      Минимум:
      0
      Максимум:
      10000000000
    • list_price_currencystring или null

      Валюта назначенной цены (прайс магазина в чужой валюте); null — цена в валюте магазина currency. Во входе — валюта прайса магазина или currency.

      Значения:
      ARSUSDBRLCLPCOPMXNPENRUBnull
    • compare_at_priceinteger или null

      Цена до скидки, показывается зачёркнутой; null, если скидки нет.

      Максимум:
      10000000000
    • weight_gramsinteger или null

      Вес для доставки в граммах; null, если не задан.

      Минимум:
      0
      Максимум:
      2147483647
    • length_mminteger или null

      Длина упаковки в миллиметрах; null, если не задана.

      Минимум:
      0
      Максимум:
      2147483647
    • width_mminteger или null

      Ширина упаковки в миллиметрах; null, если не задана.

      Минимум:
      0
      Максимум:
      2147483647
    • height_mminteger или null

      Высота упаковки в миллиметрах; null, если не задана.

      Минимум:
      0
      Максимум:
      2147483647
    • sale_starts_atstring (date-time) или null

      Когда начинается распродажа: compare_at_price показывается с этого момента; null — без начала.

    • sale_ends_atstring (date-time) или null

      Когда распродажа заканчивается; null — без конца.

    • sold_bystring

      Как продаётся вариант: each — поштучно; weight — на вес; volume — на объём.

      Значения:
      eachweightvolume
    • price_per_quantitystring или null

      За сколько единиц цена, десятичной строкой: за одну штуку или за 1000 — цена килограмма у весового варианта. null, если у весового или объёмного варианта она не задана.

      Макс. длина:
      32
    • measure_stepstring или null

      Шаг количества в строке весового или объёмного варианта, в его единице; null, если не задан.

      Макс. длина:
      32
    • min_measure_qtystring или null

      Наименьшее количество в строке весового или объёмного варианта; null, если не задано.

      Макс. длина:
      32
    • max_measure_qtystring или null

      Наибольшее количество в строке весового или объёмного варианта; null, если не задано.

      Макс. длина:
      32
    • net_contentobject

      Мера нетто одной штуки: пачка 500 г, бутылка 1000 мл. У упаковки из нескольких единиц другого варианта выводится из него, у фасованной штуки — из её меры; записать можно только у обычного штучного варианта. null у весового и объёмного и у штуки без меры.

      Поля · 2
      • quantitystring

        Мера десятичной строкой в unit: "500", "0.5".

        Макс. длина:
        32
      • unitstring

        Единица меры: g — граммы; ml — миллилитры.

        Значения:
        gml
    • barcodesмассив object или null

      Штрихкоды варианта.

      Макс. элементов:
      20
      Поля · 3
      • typestringобязательно

        Символика: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix или other.

        Значения:
        ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
      • valuestringобязательно

        Штрихкод.

      • is_primaryboolean или null

        Основной штрихкод варианта: его печатают этикетки и чеки.

    • option_valuesмассив object

      Значения опций варианта: по одному значению каждой опции товара.

      Макс. элементов:
      10
      Поля · 2
      • option_idintegerобязательно

        ID опции из options товара.

      • value_idintegerобязательно

        ID значения из values этой опции.

Ответы

200Успешно

Заголовки

  • Idempotent-Replayedstring

    true, когда это сохранённый ответ более раннего запроса с тем же Idempotency-Key.

    Значения:
    true
  • ETagstringобязательно

    Версия записи. Передайте её в If-Match, чтобы изменить запись.

    Пример:
    "7"

application/json

Возвращает Product

201Создано

Заголовки

  • Idempotent-Replayedstring

    true, когда это сохранённый ответ более раннего запроса с тем же Idempotency-Key.

    Значения:
    true
  • ETagstringобязательно

    Версия записи. Передайте её в If-Match, чтобы изменить запись.

    Пример:
    "7"
  • Locationstring (uri)обязательно

    Адрес созданной записи, а у принятого к исполнению (202) — адрес, где следить за исходом.

application/json

Возвращает Product

401Токена нет, он неверен, истёк или отозван

Заголовки

  • WWW-Authenticatestringобязательно

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer

application/problem+json

Возвращает Problem

403Запрос не разрешают тариф, IP-адрес или scopes токена

Заголовки

  • WWW-Authenticatestring

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Возвращает ForbiddenProblem

409Запрос с тем же ключом идемпотентности ещё исполняется, данные изменились после чтения, внешний id у другой записи, исчерпан лимит тарифа или адресов вебхуков, или правке нужно согласие на последствия

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает ConflictProblem

412Запись изменилась после чтения: версия в If-Match не текущая

application/problem+json

Возвращает Problem

422Параметр неверен или неизвестен

application/problem+json

Возвращает ValidationProblem

428Запросу нужен If-Match с ETag записи

application/problem+json

Возвращает Problem

429Лимит запросов исчерпан

Заголовки

  • Retry-Afterintegerобязательно

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает RateLimitProblem

503Магазин временно недоступен

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает Problem

Отказы метода

Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки

Пример запроса
curl -X PATCH "https://api.saleya.app/v1/products/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Тело запроса — body.json
{
  "name": {
    "key": "string"
  },
  "short_description": {
    "key": "string"
  },
  "description": {
    "key": "string"
  },
  "slug": "string",
  "brand_id": 0,
  "tax_class_id": 0,
  "category_ids": [
    0
  ],
  "primary_category_id": 0,
  "is_active": true,
  "published_at": "2026-01-15T12:00:00Z",
  "unpublished_at": "2026-01-15T12:00:00Z",
  "sale_schedule": [
    {
      "days": [
        1
      ],
      "from": "string",
      "to": "string"
    }
  ],
  "type": "goods",
  "stock_unit": {
    "unit": "g",
    "purchase_unit": "string",
    "purchase_quantity": "string"
  },
  "variants": [
    {
      "external_id": "string",
      "sku": "string",
      "name": {
        "key": "string"
      },
      "price": 0,
      "track_inventory": true,
      "is_active": true,
      "position": 0,
      "list_price": 0,
      "list_price_currency": "ARS",
      "compare_at_price": 0,
      "weight_grams": 0,
      "length_mm": 0,
      "width_mm": 0,
      "height_mm": 0,
      "sale_starts_at": "2026-01-15T12:00:00Z",
      "sale_ends_at": "2026-01-15T12:00:00Z",
      "sold_by": "each",
      "price_per_quantity": "string",
      "measure_step": "string",
      "min_measure_qty": "string",
      "max_measure_qty": "string",
      "net_content": {
        "quantity": "string",
        "unit": "g"
      },
      "barcodes": [
        {
          "type": "ean13",
          "value": "string",
          "is_primary": true
        }
      ],
      "option_values": [
        {
          "option_id": 0,
          "value_id": 0
        }
      ]
    }
  ]
}
Пример ответа · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "type": "goods",
  "stock_unit": {
    "unit": "g",
    "purchase_unit": "string",
    "purchase_quantity": "string"
  },
  "name": {
    "key": "string"
  },
  "short_description": {
    "key": "string"
  },
  "description": {
    "key": "string"
  },
  "slug": "string",
  "brand_id": 0,
  "tax_class_id": 0,
  "category_ids": [
    0
  ],
  "primary_category_id": 0,
  "options": [
    {
      "id": 0,
      "key": "string",
      "name": {
        "key": "string"
      },
      "position": 0,
      "values": [
        {
          "id": 0,
          "value": {
            "key": "string"
          },
          "swatch_color": "string",
          "position": 0
        }
      ]
    }
  ],
  "modifier_groups": [
    {
      "group_id": 0,
      "selection_rule": {
        "min_select": 0,
        "max_select": 0
      }
    }
  ],
  "media": [
    {
      "id": 0,
      "kind": "image",
      "url": "string",
      "mime": "string",
      "alt": {
        "key": "string"
      },
      "position": 0,
      "is_primary": true
    }
  ],
  "is_active": true,
  "published_at": "2026-01-15T12:00:00Z",
  "unpublished_at": "2026-01-15T12:00:00Z",
  "sale_schedule": [
    {
      "days": [
        0
      ],
      "from": "string",
      "to": "string"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Заменить опции товара целиком и разложить по ним его варианты

put/products/{product}/options

Scope: catalog:write

Параметры

Путь

  • productintegerобязательно

    ID товара.

Строка запроса

  • consentobject

    Согласия на последствия правки по видам: consent[<consent_kind>]=<consent_token> из ответа 409 consent_required. Уже данные согласия сохраняются, когда спрашивается следующий вид.

    Поля · 1
    • variant_axesstring

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

      Мин. длина:
      64
      Макс. длина:
      64

Заголовок

  • Idempotency-Keystring

    Уникальный ключ попытки, например UUID. Повтор с тем же ключом и телом получает сохранённый ответ вместо второй записи. Ключ живёт 24 часа.

    Мин. длина:
    1
    Макс. длина:
    255
    Пример:
    8e03978e-40d5-43e8-bc93-6894a57f9324
  • If-Matchstringобязательно

    ETag записи из последнего чтения, например "7". Правка применится, только если запись с тех пор никто не менял, иначе 412. Без заголовка — 428.

    Пример:
    "7"

Тело запроса application/json

  • optionsмассив objectобязательно

    Опции, которыми различаются варианты, например размер или цвет, по порядку.

    Макс. элементов:
    10
    Поля · 4
    • keystringобязательно

      Машинный ключ опции, уникальный в товаре, например size.

      Макс. длина:
      32
      Шаблон:
      ^[a-z][a-z0-9_]*$
    • nameсловарь string или nullобязательно

      Название опции по языкам.

      Макс. длина:
      120
    • valuesмассив objectобязательно

      Значения опции по порядку.

      Мин. элементов:
      1
      Макс. элементов:
      50
      Поля · 3
      • valueсловарь string или nullобязательно

        Значение по языкам, например {"es": "Rojo", "ru": "Красный"}.

        Макс. длина:
        120
      • swatch_colorstring или null

        Цвет образца, шестнадцатеричный код вида #C0392B; null, если у значения нет образца.

        Макс. длина:
        16
        Шаблон:
        ^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
      • idinteger или null

        ID значения. Варианты ссылаются на него в option_values.

    • idinteger или null

      ID опции.

  • variantsмассив objectобязательно

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

    Макс. элементов:
    200
    Поля · 3
    • idintegerобязательно

      ID варианта.

    • archiveboolean

      true — отправить вариант в архив вместо значений.

    • value_indexesмассив integer

      Значения варианта: для каждой опции — индекс значения в options[i].values этого запроса, так называются и новые значения без id.

      Макс. элементов:
      10
      Минимум:
      0
      Максимум:
      49

Ответы

200Успешно

Заголовки

  • Idempotent-Replayedstring

    true, когда это сохранённый ответ более раннего запроса с тем же Idempotency-Key.

    Значения:
    true
  • ETagstringобязательно

    Версия записи. Передайте её в If-Match, чтобы изменить запись.

    Пример:
    "7"

application/json

Возвращает Product

401Токена нет, он неверен, истёк или отозван

Заголовки

  • WWW-Authenticatestringобязательно

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer

application/problem+json

Возвращает Problem

403Запрос не разрешают тариф, IP-адрес или scopes токена

Заголовки

  • WWW-Authenticatestring

    Схема аутентификации (RFC 6750).

    Пример:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Возвращает ForbiddenProblem

404Объекта нет или он недоступен приложению

application/problem+json

Возвращает Problem

409Запрос с тем же ключом идемпотентности ещё исполняется, данные изменились после чтения, внешний id у другой записи, исчерпан лимит тарифа или адресов вебхуков, или правке нужно согласие на последствия

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает ConflictProblem

412Запись изменилась после чтения: версия в If-Match не текущая

application/problem+json

Возвращает Problem

422Параметр неверен или неизвестен

application/problem+json

Возвращает ValidationProblem

428Запросу нужен If-Match с ETag записи

application/problem+json

Возвращает Problem

429Лимит запросов исчерпан

Заголовки

  • Retry-Afterintegerобязательно

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает RateLimitProblem

503Магазин временно недоступен

Заголовки

  • Retry-Afterinteger

    Сколько секунд подождать перед повтором.

    Минимум:
    0

application/problem+json

Возвращает Problem

Отказы метода

Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки

Пример запроса
curl -X PUT "https://api.saleya.app/v1/products/{product}/options" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Тело запроса — body.json
{
  "options": [
    {
      "key": "string",
      "name": {
        "key": "string"
      },
      "values": [
        {
          "value": {
            "key": "string"
          },
          "swatch_color": "string",
          "id": 0
        }
      ],
      "id": 0
    }
  ],
  "variants": [
    {
      "id": 0,
      "archive": true,
      "value_indexes": [
        0
      ]
    }
  ]
}
Пример ответа · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "type": "goods",
  "stock_unit": {
    "unit": "g",
    "purchase_unit": "string",
    "purchase_quantity": "string"
  },
  "name": {
    "key": "string"
  },
  "short_description": {
    "key": "string"
  },
  "description": {
    "key": "string"
  },
  "slug": "string",
  "brand_id": 0,
  "tax_class_id": 0,
  "category_ids": [
    0
  ],
  "primary_category_id": 0,
  "options": [
    {
      "id": 0,
      "key": "string",
      "name": {
        "key": "string"
      },
      "position": 0,
      "values": [
        {
          "id": 0,
          "value": {
            "key": "string"
          },
          "swatch_color": "string",
          "position": 0
        }
      ]
    }
  ],
  "modifier_groups": [
    {
      "group_id": 0,
      "selection_rule": {
        "min_select": 0,
        "max_select": 0
      }
    }
  ],
  "media": [
    {
      "id": 0,
      "kind": "image",
      "url": "string",
      "mime": "string",
      "alt": {
        "key": "string"
      },
      "position": 0,
      "is_primary": true
    }
  ],
  "is_active": true,
  "published_at": "2026-01-15T12:00:00Z",
  "unpublished_at": "2026-01-15T12:00:00Z",
  "sale_schedule": [
    {
      "days": [
        0
      ],
      "from": "string",
      "to": "string"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}