API: загрузка закупочных цен из вашей программы

Закупочные цены — единственные данные, которые маркетплейс о вас не знает: их вводите вы. Если закупки уже живут в вашей учётной системе — МойСклад, 1С, таблица со скриптом, — присылать их к нам можно программой, а не выгружать файл руками каждую неделю.

Для этого есть API: вы выпускаете ключ в кабинете, ваша программа шлёт с ним запросы. Всё, что делает API, вы можете сделать и руками в разделе «Цены» — API просто избавляет от ручной работы.

Как выпустить ключ

1. 1

   Профиль → «Ключи API» → «Настроить»

   Или сразу по адресу «Ключи API».
2. 2

   Назовите ключ и нажмите «Выпустить»

   Название — по программе, которая будет им пользоваться: «МойСклад», «1С». Когда ключей несколько, только по названию и понятно, какой можно отозвать.
3. 3

   Скопируйте ключ сразу

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

Как устроен запрос

Адрес — https://sellervpluse.ru/api/v1/…, ключ передаётся заголовком Authorization. Тело запросов и ответов — JSON.

curl https://sellervpluse.ru/api/v1/ping \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"

{
  "ok": true,
  "account": { "email": "you@example.com" },
  "key": { "name": "МойСклад" }
}

Если вместо этого пришла ошибка — дальше идти незачем: сначала разберитесь с ключом, иначе ошибку загрузки цен не отличить от ошибки доступа.

Загрузка закупочных цен

POST /api/v1/prices — присылаете список артикулов с ценами и дату, с которой они действуют.

curl -X POST https://sellervpluse.ru/api/v1/prices \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "validFrom": "2026-08-01",
    "prices": [
      { "article": "SHIRT-RED-M",  "price": 450 },
      { "article": "SHIRT-BLUE-L", "price": 480.50 }
    ]
  }'

{
  "created":    2,
  "updated":    0,
  "unchanged":  0,
  "duplicates": 0,
  "errors":     []
}

За один запрос принимается до 50 000 цен, а тело запроса — до 10 МБ (прайс на 50 000 позиций весит около 2 МБ, так что упереться в мегабайты раньше, чем в строки, трудно). Запись целиком либо проходит, либо не проходит: половины не бывает, поэтому при ошибке достаточно повторить тот же запрос.

Главное про дату «действует с»

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

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

Каких цен не хватает

GET /api/v1/prices/missing отвечает на вопрос «по каким товарам вы продаёте, а закупки не знаете». Это тот же список, что в кабинете по кнопке «Товары без себестоимости».

curl "https://sellervpluse.ru/api/v1/prices/missing" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"

{
  "articles": [
    {
      "article":      "SHIRT-RED-M",
      "orders":       12,
      "firstOrderAt": "2026-07-01T00:00:00.000Z",
      "lastOrderAt":  "2026-08-10T00:00:00.000Z",
      "costArticle":  null
    }
  ],
  "total": 1,
  "windowDays": 90
}

firstOrderAt — дата самой ранней продажи, которая осталась без цены. Именно её (самую раннюю по всей пачке) и стоит поставить в validFrom, когда вы дозаливаете недостающие цены: иначе цена «с сегодня» эти продажи не закроет и товар из списка не исчезнет.

Список считается за последние 90 дней — столько же, сколько мы храним подробности заказов. Пустой ответ означает «за 90 дней всё заполнено».

Выгрузка цен

GET /api/v1/prices отдаёт то, что у нас записано, — например, чтобы сверить с прайсом в своей системе.

curl "https://sellervpluse.ru/api/v1/prices?limit=500&page=1" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"

{
  "prices": [
    {
      "article":    "SHIRT-RED-M",
      "price":      "450.00",
      "validFrom":  "2026-08-01T00:00:00.000Z",
      "validUntil": null
    }
  ],
  "total": 1, "page": 1, "pageCount": 1, "limit": 500
}

Ошибки и ограничения

У ошибки всегда есть HTTP-код, текст в поле error и машинный код в поле code. Ветвиться в своём скрипте нужно по code: текст мы можем переформулировать.

Сколько запросов можно слать

• Чтение (ping, выгрузка цен, список без себестоимости) — 120 запросов в минуту на ключ, 240 в минуту на аккаунт.
• Загрузка цен — 60 запросов в час на ключ, 120 в час на аккаунт.

Счётчиков два, и они работают вместе: первый — на каждый ключ отдельно, второй — общий потолок на все ключи аккаунта. Ключей можно выпустить до пяти, но суммарная скорость от их числа не растёт: две интеграции, работающие одновременно на полной скорости, в общий лимит укладываются, дальше они делят его между собой.

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

Как это обычно настраивают

1. 1

   Первая заливка — задним числом

   Спросите /api/v1/prices/missing, возьмите самую раннюю firstOrderAt и загрузите весь прайс с этой датой в validFrom. Так закроются уже накопленные продажи.
2. 2

   Дальше — по расписанию

   Раз в сутки (или как часто меняются закупки) шлите весь прайс без validFrom. Записываться будет только изменившееся: в ответе это видно по created и updated.
3. 3

   Проверяйте, что пробелов не осталось

   Тем же /api/v1/prices/missing: пустой список означает, что прибыль считается по всем продажам.

Если что-то не сходится — загляните в раздел «Цены»: там видно то же самое глазами. А как история цен влияет на прибыль, разобрано в статье «Себестоимость и история цен».