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

Плюсомер
ВойтиПопробоватьПопробовать бесплатно

API отгрузок интернет-магазина

Через этот API интернет-магазин передаёт в Плюсомер подтверждённые отгрузки СДЭК. На этапе оплаты сайт резервирует товар у себя. После передачи посылки можно отправить событие для списания со склада. При повторном уведомлении отправьте прежние данные с тем же идентификатором. Плюсомер вернёт сохранённый результат, если событие уже записано.

Подключение

  1. Владелец рабочего пространства открывает «Настройки → Расширения → Отгрузки интернет-магазина». Указывает название подключения, выбирает один подключённый магазин Плюсомера с карточками для витрины и нажимает «Выпустить токен».
  2. Ключ plus_ds_… показывается один раз. Сохраните его в серверном хранилище секретов сайта. Он разрешает отправить отгрузку и прочитать её результат только для выбранного магазина. Для отчёта own_stock продолжайте использовать отдельный действующий токен чтения.
  3. Для ротации выпустите новый ключ на тот же магазин, замените его на сервере сайта и нажмите «Отозвать» у старого. История событий и дата начала учёта сохраняются. При смене магазина потребуется заново сопоставить карточки, а незавершённые события прежнего магазина сверить отдельно.

Первый выпуск токена задаёт дату начала учёта магазина. Передавайте только новые физические отгрузки после этой даты. Заказы из истории исключите из автоматической очереди.

Когда отправлять

Поставьте событие в долговечную очередь при подтверждённой передаче товара СДЭК или при получении более позднего статуса, который однозначно доказывает передачу. В обоих случаях используйте время самой передачи из истории перевозчика. Если его нельзя установить, отправьте заказ на ручную сверку.

Оплата создаёт локальное удержание на витрине. Оплата, накладная и этикетка складского события не создают. При отмене до передачи снимите локальное удержание. После передачи возврат денег ничего не добавляет в физический остаток. При фактической приёмке пригодного товара сотрудник может внести новый физический остаток через «Свой склад».

Сохраняйте один eventId на одну физическую отправку. У нескольких частичных отправок одного заказа разные идентификаторы и собственные количества. При повторной доставке уведомления СДЭК используйте прежний идентификатор. Храните исходное тело в очереди до подтверждения. Поля сопоставления берите из сохранённой привязки отправляемых позиций, чтобы расхождение с текущим составом комплекта попало на сверку.

Запись и проверка

POST /api/addons/v1/own-stock/dispatches
Authorization: Bearer <токен отгрузок>
Content-Type: application/json
{
  "eventId": "sdek:parcel-101",
  "orderNumber": "Д-101",
  "dispatchedAt": "2026-11-08T08:15:02.000Z",
  "items": [
    {
      "productId": "00000000-0000-4000-8000-0000000d0006",
      "poolId": "00000000-0000-4000-8000-0000000d0005",
      "unitsPerProduct": 3,
      "quantity": 2
    }
  ]
}
  • eventId содержит от 1 до 128 символов из A–Z, a–z, 0–9, _, ., :, -. Регистр значим. Область уникальности — рабочее пространство и магазин, определённые по токену.
  • orderNumber — отображаемый номер заказа, до 128 символов, без управляющих символов. Используйте внутренний номер без данных покупателя.
  • dispatchedAt — UTC с секундами и Z, с тремя знаками миллисекунд или без них.
  • items содержит от 1 до 100 строк. productId — UUID активной карточки, poolId — ожидаемый UUID физического пула. И карточка, и пул должны относиться к магазину токена. unitsPerProduct — ожидаемое число физических единиц на одно изделие, quantity — число переданных изделий. Оба числа целые от 1 до 2 147 483 647. Для отдельного товара обычно productId == poolId и unitsPerProduct == 1. Расход общего пула складывается по всем строкам.
  • Передавайте только перечисленные поля. Магазин, пространство, данные покупателя и реквизиты заказа в запросе не нужны.

Успешная запись возвращает HTTP 200.

{
  "eventId": "sdek:parcel-101",
  "orderNumber": "Д-101",
  "dispatchedAt": "2026-11-08T08:15:02.000Z",
  "status": "applied",
  "pools": [
    {
      "poolId": "00000000-0000-4000-8000-0000000d0005",
      "poolRevision": 41,
      "before": 20,
      "after": 14
    }
  ]
}

before и after указаны в физических единицах пула. poolRevision — ревизия этого пула сразу после списания. Результат сохраняется вместе с движениями и не меняется при последующих списаниях или инвентаризации.

HTTP 200 со статусом review означает, что Плюсомер сохранил причину для ручной сверки и оставил все остатки прежними.

{
  "eventId": "sdek:parcel-101",
  "orderNumber": "Д-101",
  "dispatchedAt": "2026-11-08T08:15:02.000Z",
  "status": "review",
  "pools": [],
  "problem": { "code": "mapping_changed", "line": 1 }
}
problem.codeПричина
before_activationПередача произошла до первого выпуска ключа для магазина.
product_unavailableКарточка неизвестна, неактивна либо карточка или фактический пул вне магазина токена.
mapping_changedТекущий пул или число физических единиц отличаются от запроса.
quantity_overflowРасход одного пула превысил 2 147 483 647 физических единиц.
counted_after_dispatchФизический остаток пересчитали в момент передачи или позже.
stock_unknownФизический остаток не введён.
insufficient_stockСуммарный расход превышает остаток.

problem.line — номер строки с единицы. Для проблемы общего пула указан номер первой его строки. У before_activation поля line нет.

GET /api/addons/v1/own-stock/dispatches?eventId=sdek%3Aparcel-101
Authorization: Bearer <токен отгрузок>

GET возвращает тот же сохранённый JSON с HTTP 200 или HTTP 404 с {"error":"dispatch_not_found"}, если в магазине токена такого события нет. При таймауте, обрыве соединения или 5xx сначала проверьте GET. Если результат ещё неизвестен, повторите исходный POST с тем же телом и eventId с увеличивающейся задержкой. Если запись уже есть, POST возвращает её. Порядок полей JSON не учитывается, UUID приводятся к нижнему регистру, время нормализуется до миллисекунд. Порядок строк является частью содержимого.

  • HTTP 400 с invalid_dispatch, future_dispatched_at или invalid_event_id требует проверить запрос.
  • HTTP 401 означает отсутствующий, неверный, отозванный или просроченный ключ. HTTP 402 означает закрытый доступ по подписке. HTTP 403 означает потерю прав на подключение. В этих случаях сохраните событие в очереди до восстановления доступа.
  • HTTP 409 с {"error":"event_id_conflict"} означает, что этот идентификатор уже сохранён с другим содержимым. Сверьте исходное событие. Для review тоже нужна ручная сверка. Новый идентификатор для той же отправки может привести к повторному списанию.

Как снять удержание на витрине

GET /api/addons/v1/report?report=own_stock&year=2026 принимает действующий токен чтения. Прежние columns, units и rows сохраняют формат и порядок полей. Новый массив stockRefs соответствует строкам того же ответа по индексу. В каждом элементе есть productId, poolId и poolRevision. Для недоступного пула последние два поля равны null. Номер ревизии сравнивается только внутри одного poolId. Остаток в rows[i][4] уже выражен в изделиях карточки. Число физических единиц на изделие находится в rows[i][6]. В MCP‑ответе own_stock те же три поля находятся в каждом объекте products.

  1. Сохраните applied именно для этой отправки. Подтверждение другой отгрузки или уменьшение числа в отчёте само по себе удержание не снимает.
  2. Получите снимок, в котором для каждого затронутого пула poolRevision равна ревизии из подтверждения или больше. Для всех карточек, публикуемых из общего пула, используйте согласованный снимок. Если у строк одного пула в ответе оказались разные ревизии, обновите снимок перед публикацией.
  3. В одной локальной транзакции обновите опубликованные остатки и снимите удержание только отправленного количества. При частичной отправке оставьте удержание остальной части заказа. При review, неизвестном статусе или изменившейся привязке оставьте удержание до сверки. Если ответ POST потерялся, после загрузки нового снимка проверьте GET по отправленным событиям, прежде чем публиковать обновление. Если проверку выполнить не удалось, сохраните предыдущий согласованный снимок затронутых пулов вместе с удержаниями до восстановления связи.
  4. Если остаток неизвестен, доступное количество не увеличивайте. Пока действуют удержания, при расчёте доступности комплекта учитывайте общий расход удержаний пула в физических единицах. Остаток в этих единицах берите из строки основного товара, где productId совпадает с poolId. Если такой строки нет, не вычисляйте физический остаток из округлённого количества комплектов. При сравнении ревизий ориентируйтесь на poolId, потому что один и тот же пул может встречаться у разных карточек.

Первое включение

  1. Согласуйте один будущий заказ, карточки, состав комплектов и фактические остатки. Выпустите ключ, включите отправку только для выбранной отгрузки и зафиксируйте исходные остатки и ревизии.
  2. После подтверждения передачи СДЭК проверьте applied, GET по eventId и журнал «Товары → Свой склад». У движения будет источник «Интернет-магазин», номер заказа и остатки до и после по каждому пулу. Повтор POST должен вернуть ту же ревизию без второй строки движения для пула.
  3. Получите свежий own_stock, примите подтверждённые ревизии и снимите удержание. Сверьте доступное количество до отправки и после обновления с учётом оставшихся удержаний. При отсутствии других движений количество на витрине должно остаться прежним после замены удержания списанием. После этой сверки можно включить очередь для следующих подтверждённых передач.