Описание API

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

Авторизация

Авторизационные данные передаются в HTTP-заголовке Authorization:

Ваш API key доступен на странице Настройки аккаунта

Если ресурс API вызван без авторизационных данных, сервер вернет HTTP-статус 403

Отправка запросов

Запросы к API передаются по протоколу HTTPS

Для получения данных используется GET, для создания и изменения заказов API-магазина — PUT и POST, для подтверждения заказа маркетплейса без сканирования — POST. Метод указан в описании каждого запроса.

Формат ответа JSON

Все даты в запросах и ответах указаны в часовом поясе UTC

Базовый URL для запросов https://поддомен.oship.ru/api/seller/

Маркировка «Честный знак»

В объектах товаров используются два связанных поля:

cis — код маркировки. Строка содержит переданный или отсканированный код, пустая строка означает, что код ещё нужно получить, null — код отсутствует или необязательная маркировка была пропущена;
cis_requirement — требование к маркировке: none — код не нужен, required — код обязателен, optional — код можно передать или пропустить.

При создании заказа для магазина с типом API рекомендуется всегда передавать cis_requirement. Если поле не передано, сохраняется обратная совместимость: cis, равный 1 или строке "1", означает обязательное сканирование; непустое скалярное значение считается переданным обязательным кодом; 0, null, пустое или отсутствующее поле cis означает отсутствие требования.

IMEI

В объектах товаров используются поля:

imei — IMEI устройства. Строка содержит переданное или отсканированное значение, пустая строка означает, что IMEI нужно получить сканированием, null — значение отсутствует или необязательный IMEI был пропущен;
imei_requirement — требование к IMEI: none — значение не нужно, required — IMEI обязателен, optional — IMEI можно передать или пропустить.

IMEI должен состоять из 15 цифр и проходить проверку контрольной суммы. При создании заказа рекомендуется всегда передавать imei_requirement. Для none значение imei игнорируется и сохраняется как null. Для required отсутствие, null или пустая строка означает последующее обязательное сканирование. Для optional пустая строка или отсутствующее поле означает, что IMEI можно отсканировать либо пропустить; явно переданный imei: null означает, что необязательный IMEI уже пропущен.

Цена продажи

Поле sale_price в объекте товара содержит цену продажи одной физической единицы товара в российских копейках. Значение передаётся и возвращается целым неотрицательным числом. Если цена неизвестна, поле имеет значение null.

Для магазина с типом API поле необязательно при создании заказа в разделе «Упаковка». После создания заказа изменить цену продажи через API нельзя. Для нескольких единиц одного товара передавайте отдельный элемент массива products для каждой единицы.

Цена возвращается в объектах products подробных методов раздела «Упаковка»: GET /api/seller/orders/{shop UUID}/{order number} и GET /api/shop/orders/{order number}. В списках заказов и методах раздела «Подтверждение» это поле отсутствует.

Запросы

Получение списка магазинов

Запрос

GET https://поддомен.oship.ru/api/seller/shops
Authorization: **Ваш API key**

Ответ

[
    {
        "uuid": UUID магазина,
        "name": Название магазина,
        "active": Признак активности магазина (true — активен, false — неактивен),
        "prioritet": Приоритет магазина,
        "shipment_window": Период для упаковки,
        "source": {
            "name": Название источника магазина,
            "slug": slug источника магазина
        }
    },
    ...
]

Подтверждение заказов

Получение списка заказов раздела Подтверждение по планируемой дате отгрузки

Запрос

GET https://поддомен.oship.ru/api/seller/approves?shipment_date=2025-01-27
Authorization: Ваш API key

Если shipment_date не указан, то по умолчанию возвращаются заказы с планируемой датой отгрузки сегодня.

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

Планируемая дата отгрузки для Wildberries равна дате создания заказа в oShip.

Ответ

[
    {
        "shop": {
            "uuid": UUID магазина,
            "name": Название магазина,
            "source": {
                "name": Название источника магазина,
                "slug": техническое наименование источника магазина
            }
        },
        "number": Номер заказа,
        "shipment_date": Планируемая дата отгрузки,
        "status": Статус заказа (возможные значения: accepted, approved, cancelled),
        "accepted_at": Дата поступления заказа,
        "approved_at": Дата подтверждения заказа,
        "cancelled_at": Дата отмены заказа,
 "products": [
         {
             "code": Код товара,
             "name": Название товара,
             "cis": Код "Честный знак",
             "cis_requirement": Требование к коду (none, required или optional),
             "imei": IMEI товара,
             "imei_requirement": Требование к IMEI (none, required или optional),
             "assigned_at": Дата сканирования товара при подтверждении,
         },
         ...
     ],
    },
    ...
]

Получение списка заказов раздела Подтверждение конкретного магазина по планируемой дате отгрузки

Запрос

GET https://поддомен.oship.ru/api/seller/approves/{shop UUID}?shipment_date=2025-01-27
Authorization: Ваш API key

Если shipment_date не указан, то по умолчанию возвращаются заказы с планируемой датой отгрузки сегодня Значение для параметра shop_UUID можно узнать из запроса получения списка магазинов

Ответ

[
    {
        "number": Номер заказа,
        "shipment_date": Планируемая дата отгрузки,
        "status": Статус заказа (возможные значения: accepted, approved, cancelled),
        "accepted_at": Дата поступления заказа,
        "approved_at": Дата подтверждения заказа,
        "cancelled_at": Дата отмены заказа,
 "products": [
         {
             "code": Код товара,
             "name": Название товара,
             "cis": Код "Честный знак",
             "cis_requirement": Требование к коду (none, required или optional),
             "imei": IMEI товара,
             "imei_requirement": Требование к IMEI (none, required или optional),
             "assigned_at": Дата сканирования товара при подтверждении,
         },
         ...
     ],
    },
    ...
]

Получение подробной информации по конкретному заказу раздела Подтверждение

Запрос

GET https://поддомен.oship.ru/api/seller/approves/{shop UUID}/{order number}
Authorization: **Ваш API key**

Значение для параметра shop UUID можно узнать из запроса получения списка магазинов или запроса на получение списка заказов раздела Подтверждение по планируемой дате отгрузкиorder number - номер заказа

Ответ

{
    "number": Номер заказа,
    "shipment_date": Планируемая дата отгрузки,
    "status": Статус заказа (возможные значения: accepted, approved, cancelled),
    "accepted_at": Дата поступления заказа,
    "approved_at": Дата подтверждения заказа,
    "cancelled_at": Дата отмены заказа,
    "products": [
        {
            "code": Код товара,
            "name": Название товара,
            "cis": Код "Честный знак",
            "cis_requirement": Требование к коду (none, required или optional),
            "imei": IMEI товара,
            "imei_requirement": Требование к IMEI (none, required или optional),
            "assigned_at": Дата сканирования товара при подтверждении,
            "barcodes": ["124312345"]
        },
        ...
    ]
}

Подтверждение одного заказа без сканирования

Метод подтверждает все оставшиеся неподтверждённые товары одного заказа в oShip и передаёт заказ в существующий процесс подтверждения на маркетплейсе. Доступен для магазинов Ozon, Wildberries и Яндекс Маркет.

Запрос

http

POST https://поддомен.oship.ru/api/seller/approves/{shop UUID}/{order number}/confirm
Authorization: Ваш API key

Значение shop UUID можно узнать из запроса получения списка магазинов. order number — номер заказа в указанном магазине.

Тело запроса не требуется. Допускается пустой JSON-объект {}. Дополнительные параметры в теле и строке запроса не принимаются.

Для выполнения необходимы действующий доступ к аккаунту, подключённые раздел «Подтверждение» и источник магазина, активный магазин и включённая настройка «Подтверждение без сканирования». Применяются те же ограничения по маркировке и IMEI, что и при подтверждении без сканирования в интерфейсе. В частности, для B2B-заказа Ozon сначала необходимо указать обязательный Честный знак; товары Яндекс Маркета с требованием IMEI подтверждаются сканированием.

Ранее подтверждённые товары, их даты, исполнители и коды сохраняются. У остальных товаров фиксируются дата подготовки и признак подтверждения без сканирования; сотрудник не назначается, поскольку запрос выполняется по ключу аккаунта. Если хотя бы одна оставшаяся позиция не проходит проверку, заказ не изменяется.

Для Wildberries применяется существующий подбор активной поставки;

Ответ

При успешном выполнении — 200 OK:

json

[]

Ответ означает успешное подтверждение товаров в oShip. Подтверждение на маркетплейсе выполняется асинхронно. Его завершение можно проверить по полю approved_at существующего запроса GET /api/seller/approves/{shop UUID}/{order number}. Поле assigned_at товара содержит дату его подготовки, в том числе без сканирования.

Повторный запрос для уже подготовленного или подтверждённого заказа возвращает тот же успешный ответ без повторного изменения товаров, если условия доступа сохраняются. После тайм-аута или внутренней ошибки запрос можно безопасно повторить.

Код	Описание
200	Товары успешно подтверждены в oShip либо были подтверждены ранее.
400	Некорректный адрес или тело запроса, переданы дополнительные параметры.
403	API key отсутствует или недействителен, срок доступа истёк, раздел «Подтверждение» или источник магазина недоступен.
404	Магазин не найден в аккаунте либо заказ не найден в указанном магазине.
409	Магазин отключён, подтверждение без сканирования выключено, источник не поддерживается, заказ отменён или недоступен для подтверждения, товары отсутствуют, не выполнены требования к маркировке/IMEI либо заказ занят другой операцией.
500	Внутренняя ошибка сохранения или постановки задачи на обработку.

Ошибки содержат HTTP-код и конкретную причину:

json

{
    "code": 409,
    "message": "Заказ отменён"
}

При ответе о занятости заказа повторите запрос после завершения текущей операции. Ошибки последующей обработки маркетплейсом не входят в ответ этого метода.

Упаковка заказов

Получение списка всех заказов раздела Упаковка по планируемой дате отгрузки

Запрос

GET https://поддомен.oship.ru/api/seller/orders?shipment_date=2025-01-27
Authorization: **Ваш API key**

Если shipment_date не указан, то по умолчанию возвращаются заказы с планируемой датой отгрузки сегодня

Ответ

[
    {
        "shop": {
            "uuid": UUID магазина,
            "name": Название магазина,
            "source": {
                "name": Название источника магазина,
                "slug": техническое наименование источника магазина
            }
        },
        "number": Номер заказа,
        "shipment_date": Планируемая дата отгрузки,
        "status": Статус заказа (возможные значения: accepted, packaged, shipped, delivered, cancelled),
        "has_returns": true или false — зафиксировано поступление связанного возврата,
        "comment": Текст комментария,
        "meta": {
            "client_type": Тип клиента (возможные значения: B2C, B2B)
        },
        "accepted_at": Дата приёма заказа,
        "packaged_at": Дата упаковки заказа,
        "shipped_at": Дата отгрузки заказа,
        "delivered_at": Дата доставки заказа,
        "cancelled_at": Дата отмены заказа
    },
    ...
]

has_returns — булев признак исторического факта поступления связанного возврата. Поле доступно в списках и подробных ответах заказов Seller API и Shop API и не меняет основной status. После удаления возврата или отключения модуля «Возвраты» значение true сохраняется. false означает, что возврат не зафиксирован в oShip; признак не определяет возврат каждого товара или всего состава заказа. Поле доступно только для чтения.

Получение списка заказов раздела Упаковка конкретного магазина по планируемой дате отгрузки

Запрос

GET https://поддомен.oship.ru/api/seller/orders/{shop UUID}?shipment_date=2025-01-27
Authorization: Ваш API key

Ответ

[
    {
        "number": Номер заказа,
        "shipment_date": Планируемая дата отгрузки,
        "status": Статус заказа (возможные значения: accepted, packaged, shipped, delivered, cancelled),
        "has_returns": true или false — зафиксировано поступление связанного возврата,
        "comment": Текст комментария,
        "meta": {
            "client_type": Тип клиента (возможные значения: B2C, B2B)
        },
        "accepted_at": Дата приёма заказа,
        "packaged_at": Дата упаковки заказа,
        "shipped_at": Дата отгрузки заказа,
        "delivered_at": Дата доставки заказа,
        "cancelled_at": Дата отмены заказа
    },
    ...
]

Получение подробной информации по конкретному заказу раздела Упаковка

Запрос

GET https://поддомен.oship.ru/api/seller/orders/{shop UUID}/{order number}
Authorization: **Ваш API key**

Значение для параметра shop UUID можно узнать из запроса получения списка магазиновorder number - номер заказа

Ответ

{
    "number": Номер заказа,
    "shipment_date": Планируемая дата отгрузки,
    "status": Статус заказа (возможные значения: accepted, packaged, shipped, delivered, cancelled),
    "has_returns": true или false — зафиксировано поступление связанного возврата,
    "comment": Текст комментария,
    "meta": {
            "client_type": Тип клиента (возможные значения: B2C, B2B)
        },
    "accepted_at": Дата приёма заказа,
    "packaged_at": Дата упаковки заказа,
    "shipped_at": Дата отгрузки заказа,
    "delivered_at": Дата доставки заказа,
    "cancelled_at": Дата отмены заказа,
    "products": [
        {
            "code": Код товара,
            "name": Название товара,
            "sale_price": Цена продажи одной единицы в российских копейках или null,
            "cis": Код "Честный знак",
            "cis_requirement": Требование к коду (none, required или optional),
            "imei": IMEI товара,
            "imei_requirement": Требование к IMEI (none, required или optional),
            "assigned_at": Дата сканирования товара при упаковке,
            "barcodes": ["124312345"]
        },
        ...
    ],
    "packages": [
        {
            "number": Номер грузового места,
            "barcode": Штрих-код грузового места,
            "status": Статус грузового места (возможные значения: accepted,packaged,shipped),
            "packaged_at": Дата упаковки грузового места,
            "shipped_at": Дата отгрузки грузового места
        },
        ...
    ]
}

Магазины с типом API

Добавление заказа в раздел Подтверждение для магазина с типом API

Доступно только для магазинов с типом API

Запрос

PUT https://поддомен.oship.ru/api/shop/approves
Authorization: **API key вашего магазина oShip**

{
  "number": "00001", // Номер заказа
  "shipment_date": "2025-01-27", // Плановая дата отгрузки заказа
  "products": [ // информация о товарах (массив)
    {
      "code": "111", // код товара (необязательно, если указаны barcodes)
      "name": "Test", // наименование (необязательно)
      "barcodes": ["2000259506566", ...], // массив штрихкодов товара (необязательно, если указан code)
      "cis": null, // код «Честный знак»: строка с кодом, "" для последующего сканирования или null
      "cis_requirement": "optional", // none, required или optional
      "imei": "", // 15 цифр, "" для последующего сканирования или null
      "imei_requirement": "required" // none, required или optional
    },
    ...
  ]
}

Для cis_requirement: "none" значение cis игнорируется и сохраняется как null. Для required отсутствие, null или пустая строка в cis означает, что обязательный код нужно отсканировать. Для optional пустая строка или отсутствующий cis означает, что код можно отсканировать либо пропустить; явно переданный cis: null означает, что необязательный код уже пропущен.

Правила для imei и imei_requirement описаны в разделе IMEI.

Значение API key доступно при создании магазина с типом API

Ответ

Варианты ответов:

200 Заказ успешно создан;
400 (Empty code and barcodes) - не заполнен код товара и штрихкоды;
400 (Product not found) - товар с переданными штрихкодами не найден;
400 (More than one product found) - по переданным штрихкодам найдено более 1 товара;
409 - заказ с таким номером уже существует у этого магазина.

Изменение заказа в разделе Подтверждение для магазина с типом API

Запрос

Доступно только для магазинов с типом API

POST https://поддомен.oship.ru/api/shop/approves/{номер заказа}
Authorization: **API key вашего магазина oShip**

{
    // Необходимо передать один нужный параметр для изменения
  "cancelled_at": "2025-03-14 09:09:22", // Дата и время отмены заказа (После изменения даты статус заказа меняется на "Отменен")
  "approved_at": "2025-03-14 09:09:22", // Дата и время подтверждения заказа (После изменения даты статус заказа меняется на "Подтвержден")
  "shipment_date": "2025-03-14" // Изменение даты плановой отгрузки заказа
}

Ответ

Варианты ответов:

200 - заказ успешно изменён;
404 - номер заказа не найден, либо у заказа статус Подтвержден или Отменён.

Получение подробной информации по конкретному заказу из раздела Подтверждение для магазина с типом API

Доступно только для магазинов с типом API

Запрос

GET https://поддомен.oship.ru/api/shop/approves/{order number}
Authorization: **API key вашего магазина oShip**

order number - номер заказа

Ответ

{
    "number": Номер заказа,
    "shipment_date": Планируемая дата отгрузки,
    "status": Статус заказа (возможные значения: accepted, approved, cancelled),
    "accepted_at": Дата поступления заказа,
    "approved_at": Дата подтверждения заказа,
    "cancelled_at": Дата отмены заказа,
    "products": [
        {
            "code": Код товара,
            "name": Название товара,
            "cis": Код "Честный знак",
            "cis_requirement": Требование к коду (none, required или optional),
            "imei": IMEI товара,
            "imei_requirement": Требование к IMEI (none, required или optional),
            "assigned_at": Дата сканирования товара при подтверждении,
            "barcodes": ["124312345"]
        },
        ...
    ]
}

Получение списка заказов раздела Подтверждение конкретного магазина с типом API по планируемой дате отгрузки

Запрос

GET https://поддомен.oship.ru/api/shop/approves?shipment_date=2025-03-22
Authorization: Ваш API key

Если shipment_date не указан, то по умолчанию возвращаются заказы с планируемой датой отгрузки сегодня

Значение API key доступно при создании магазина с типом API

Ответ

[
    {
        "number": Номер заказа,
        "shipment_date": Планируемая дата отгрузки,
        "status": Статус заказа (возможные значения: accepted, approved, cancelled),
        "accepted_at": Дата поступления заказа,
        "approved_at": Дата подтверждения заказа,
        "cancelled_at": Дата отмены заказа,
 "products": [
         {
             "code": Код товара,
             "name": Название товара,
             "cis": Код "Честный знак",
             "cis_requirement": Требование к коду (none, required или optional),
             "imei": IMEI товара,
             "imei_requirement": Требование к IMEI (none, required или optional),
             "assigned_at": Дата сканирования товара при подтверждении,
         },
         ...
     ],
    },
    ...
]

Добавление заказа в раздел Упаковка для магазина с типом API

Доступно только для магазинов с типом API

Запрос

PUT https://поддомен.oship.ru/api/shop/orders
Authorization: **API key вашего магазина oShip**

{
  "number": "00001", // Номер заказа
  "alt_numbers": ["ALT-1", "ALT-2"], // Альтернативные номера заказа (необязательно)
  "comment": "Текст комментария", //Комментарий к заказу.Ограничение 250 символов (необязательно)
  "shipment_date": "2025-01-27", // Плановая дата отгрузки заказа
  "accepted_at": "2025-01-27", // Дата подтверждения заказа
  "products": [ // информация о товарах (массив)
    {
      "code": "111", // код товара (необязательно, если указаны barcodes)
      "name": "Test", // наименование (необязательно)
      "barcodes": ["2000259506566", ...], // массив штрихкодов товара (необязательно, если указан code)
      "sale_price": 149900, // цена продажи одной единицы в российских копейках (необязательно)
      "cis": null, // код «Честный знак»: строка с кодом, "" для последующего сканирования или null
      "cis_requirement": "optional", // none, required или optional
      "imei": "", // 15 цифр, "" для последующего сканирования или null
      "imei_requirement": "required" // none, required или optional
    },
    ...
  ],
  "packages": [ // информация об упаковках (массив)
    {
      "number": "1212", // номер упаковки
      "barcode": "1212" // штрихкод упаковки
    },
    ...
  ],
  "label": "" // файл с этикеткой в Base64
}

Правила для imei и imei_requirement описаны в разделе IMEI.

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

Значение API key доступно при создании магазина с типом API

Если код товара ("code") заполнен, то происходит поиск товара в oShip, если товар с таким кодом не найден, то происходит создание товара с указанными параметрами (код товара, наименование (в этом случае наличие обязательно), штрихкоды). Если код товара ("code") не заполнен, то поиск товара в oShip осуществляется по баркоду.

Товары не привязываются к конкретным упаковкам, если для заказа передать информацию о нескольких упаковках, то при упаковке заказа будут напечатаны несколько этикеток, штрихкод с которых необходимо будет отсканировать, для завершения процесса упаковки.

Ответ

Варианты ответов:

200 Заказ успешно создан;
400 (Empty code and barcodes) - не заполнен код товара и штрихкоды;
400 (Product not found) - товар с переданными штрихкодами не найден;
400 (More than one product found) - по переданным штрихкодам найдено более 1 товара;
400 (sale_price must be a non-negative integer in Russian kopecks or null) - цена продажи указана нецелым или отрицательным значением;
403 - исчерпан лимит заказов либо отсутствует доступ;
404 (Label less 5000 bytes or mime type not "application/pdf") - этикетка заказа после декодирования Base64 менее 5000 байт или её тип не PDF;
409 - заказ с таким номером уже существует у этого магазина.

Изменение заказа в разделе Упаковка для магазина с типом API

Запрос

Доступно только для магазинов с типом API

POST https://поддомен.oship.ru/api/shop/orders/{номер заказа}
Authorization: **API key вашего магазина oShip**

{
    // Необходимо передать один нужный параметр для изменения
  "cancelled_at": "2025-01-28 09:09:22", // Дата и время отмены заказа (После изменения даты статус заказа меняется на "Отменен")
  "shipped_at": "2025-01-27 09:09:22", // Дата и время отгрузки заказа (После изменения даты статус заказа меняется на "Отгружен")
  "delivered_at": "2025-01-29 12:30:00", // Дата и время доставки заказа (После изменения даты статус заказа меняется на "Доставлен")
  "shipment_date": "2025-01-27" // Изменение даты плановой отгрузки заказа
}

delivered_at и cancelled_at нельзя передавать одновременно. Дата доставки не может быть раньше accepted_at или уже сохранённой shipped_at и не может быть более чем на 24 часа в будущем. Если shipped_at ещё не заполнено, при установке delivered_at оно автоматически получает ту же дату. Доставленный заказ нельзя отменить, а отменённый — отметить доставленным. Повторная передача доставки или отмены не изменяет уже сохранённую дату.

Ответ

Варианты ответов:

200 - заказ успешно изменён;
400 - некорректная дата или недопустимый переход между статусами;
404 - номер заказа не найден. Для изменения shipment_date или shipped_at также возвращается 404, если заказ уже отгружен, доставлен или отменён.

Получение подробной информации по конкретному заказу из раздела Упаковка для магазина с типом API

Доступно только для магазинов с типом API

Запрос

GET https://поддомен.oship.ru/api/shop/orders/{order number}
Authorization: **API key вашего магазина oShip**

order number - номер заказа

Ответ

{
    "number": Номер заказа,
    "alt_numbers": Альтернативные номера заказов,
    "comment": Текст комментария,
    "shipment_date": Планируемая дата отгрузки,
    "status": Статус заказа (возможные значения: accepted, packaged, shipped, delivered, cancelled),
    "has_returns": true или false — зафиксировано поступление связанного возврата,
    "accepted_at": Дата приёма заказа,
    "packaged_at": Дата упаковки заказа,
    "shipped_at": Дата отгрузки заказа,
    "delivered_at": Дата доставки заказа,
    "cancelled_at": Дата отмены заказа,
    "products": [
        {
            "code": Код товара,
            "name": Название товара,
            "sale_price": Цена продажи одной единицы в российских копейках или null,
            "cis": Код "Честный знак",
            "cis_requirement": Требование к коду (none, required или optional),
            "imei": IMEI товара,
            "imei_requirement": Требование к IMEI (none, required или optional),
            "assigned_at": Дата сканирования товара при упаковке
        },
        ...
    ],
    "packages": [
        {
            "number": Номер грузового места,
            "barcode": Штрих-код грузового места,
            "status": Статус грузового места (возможные значения: accepted,packaged,shipped),
            "packaged_at": Дата упаковки грузового места,
            "shipped_at": Дата отгрузки грузового места
        },
        ...
    ]
}

Получение списка заказов раздела Упаковка конкретного магазина с типом API по планируемой дате отгрузки

Запрос

GET https://поддомен.oship.ru/api/shop/orders?shipment_date=2025-01-27
Authorization: Ваш API key

Если shipment_date не указан, то по умолчанию возвращаются заказы с планируемой датой отгрузки сегодня

Значение API key доступно при создании магазина с типом API

Ответ

[
    {
        "shop": {
            "uuid": UUID магазина,
            "name": Название магазина,
            "source": {
                "name": Название источника магазина,
                "slug": техническое наименование источника магазина
            }
        },
        "number": Номер заказа,
        "alt_numbers": Альтернативные номера заказов,
        "shipment_date": Планируемая дата отгрузки,
        "status": Статус заказа (возможные значения: accepted, packaged, shipped, delivered, cancelled),
        "has_returns": true или false — зафиксировано поступление связанного возврата,
        "comment": Текст комментария,
        "accepted_at": Дата приёма заказа,
        "packaged_at": Дата упаковки заказа,
        "shipped_at": Дата отгрузки заказа,
        "delivered_at": Дата доставки заказа,
        "cancelled_at": Дата отмены заказа
    },
    ...
]

Возвраты

Методы доступны при подключённом разделе Возвраты. Используйте API key аккаунта и UUID магазина из списка магазинов. Возвращаются как загруженные из маркетплейса, так и созданные вручную возвраты.

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

Получение возвратов магазина по дате выдачи

http

GET https://поддомен.oship.ru/api/seller/returns/{shop UUID}?issued_date=2026-09-20
Authorization: Ваш API key

Параметр issued_date обязателен. Укажите дату выдачи в формате YYYY-MM-DD; отбор производится за календарный день в UTC. Результат — массив возвратов, отсортированный по дате выдачи и ID. Если возвратов нет, возвращается пустой массив.

json

[
  {
    "id": 123,
    "oship_barcode": "OSHIP_RETURN_123",
    "order_number": "123456789",
    "scheme": "fbs",
    "status": "assessment",
    "reason": "Возврат покупателя",
    "place": "Пункт выдачи",
    "issued_at": "2026-09-20 09:00:00",
    "updated_at": "2026-09-20 10:15:00",
    "products": [
      {
        "id": 456,
        "marketplace_return_id": 987654,
        "code": "ART-001",
        "name": "Товар",
        "condition": "damaged",
        "condition_description": "Повреждена упаковка",
        "result": null
      }
    ]
  }
]

oship_barcode используйте в том виде, в котором его вернул API. id — идентификатор возврата oShip; marketplace_return_id — идентификатор возвращённой позиции на маркетплейсе, у ручных возвратов он равен null.

products[].id — ID конкретной товарной позиции возврата в oShip, не ID карточки товара. Он совпадает в списке и подробном ответе; у нескольких экземпляров одного товара разные ID позиций. При изменении состояния позиции её ID не меняется.

updated_at — время последнего изменения возврата в UTC с точностью до секунды: основной записи, позиций, их сканирования и ЧЗ, состояния, описания и результата, комментариев или добавления штрихкодов возврата. Обновление updated_at позиции при автоматическом распознавании также обновляет дату возврата.

Получение подробной информации о возврате

http

GET https://поддомен.oship.ru/api/seller/returns/{shop UUID}/{return id}
Authorization: Ваш API key

Укажите return id из поля id списка возвратов. Удалённый возврат также доступен по ID с status: "deleted", сохранённым составом и историей.

Метод возвращает один объект со всеми полями возврата из списка и дополнительными данными:

Поле	Описание
`assessment_at`, `assessed_at`, `processed_at`	Даты начала оценки, завершения оценки и завершения обработки; `null`, если этап ещё не наступил
`barcodes`	Массив штрихкодов возврата с полями `type` и `value`: `marketplace` — стикер маркетплейса, `fbs_package` — штрихкод исходной упаковки
`products[].barcodes`	Массив штрихкодов сопоставленного товара
`products[].cis`	Сохранённый Честный знак, пустая строка для ожидающего сканирования кода или `null`
`products[].assigned_at`	Дата сканирования позиции при оценке
`products[].is_opened`	Сохранённый признак вскрытия: `true`, `false` или `null`
`products[].storage`	Стоимость хранения из данных возврата OZON: число или `null`, если значение не получено
`comments`	Комментарии и события обработки: `id`, `event_type`, `returns_products_id`, `users_id`, `author`, `system`, `text`, `created_at`

Если товар ещё не распознан, code и name равны null, а список его штрихкодов пуст. Для возврата Wildberries без исходного заказа order_number может быть пустой строкой. Интеграция должна сохранять такие возвраты и не считать их ошибочными.

В comments системное событие может иметь исполнителя: например, system: true, event_type: "item_assigned", users_id: 12, author: "Анна". returns_products_id указывает ID конкретного экземпляра из products[].id; для действий над всем возвратом поле равно null.

Типы событий: manual_created — ручное создание и начало оценки, assessment_started — начало оценки, item_assigned — успешная проверка экземпляра (включая обязательный КИЗ), assessment_finished — завершение оценки, processed — завершение обработки, processed_without_assessment — административная пометка без оценки, reopened - повторное открытие, deleted - удаление ручного возврата, comment - обычный комментарий. Порядок событий определяется created_at, затем id.

У старых записей event_type и returns_products_id равны null; их прежние значения system и author сохраняются. users_id и author могут быть null, если исполнитель неизвестен или удалён. Текст системного события сохраняет имя на момент действия. Нельзя определять системность новых записей по отсутствию автора - используйте system.

Получение изменений возвратов

Метод возвращает текущее состояние возвратов магазина, изменившихся с указанного времени. Повторно запрашивать каждую карточку по ID не требуется.

Запрос

http

GET https://поддомен.oship.ru/api/seller/returns/{shop UUID}/changes?updated_since=2026-10-23T09:00:00Z&limit=10
Authorization: Ваш API key

В пути укажите UUID магазина. Доступны следующие параметры запроса:

Параметр	Обязательность	Описание
`updated_since`	Необязателен для первого запроса	Нижняя граница `updated_at` в UTC, строго `YYYY-MM-DDTHH:MM:SSZ`, без долей секунды. Пример: `2026-10-23T09:00:00Z`
`page_token`	Обязателен для продолжения обмена	Строка из `next_page_token` предыдущего ответа. Передаётся без `updated_since`
`limit`	Необязателен	Максимальное число возвратов в ответе: целое число от `1` до `100`. Для первого запроса по умолчанию `100`; при продолжении без `limit` используется размер порции из токена

Без updated_since и page_token начинается выгрузка всей истории магазина:

http

GET https://поддомен.oship.ru/api/seller/returns/{shop UUID}/changes
Authorization: Ваш API key

Для первого обмена рекомендуется полная выгрузка. Большой период обрабатывается порциями: один ответ содержит не более limit возвратов (по умолчанию 100), упорядоченных по updated_at, затем по id по возрастанию. Каждая запись имеет тот же подробный состав, что и получение возврата по ID, включая позиции, штрихкоды и комментарии.

limit ограничивает количество возвратов, а не количество позиций или комментариев внутри карточек. Ответ может содержать меньше записей, чем указано в limit; для определения завершения текущего прохода используйте has_more.

Ответ

Поле	Тип	Описание
`returns`	Массив объектов	Подробные карточки возвратов. Пустой массив, если в текущей порции нет записей
`next_page_token`	Строка	Токен для следующего запроса. Возвращается всегда, в том числе при пустом массиве и `has_more: false`
`has_more`	Булево значение	`true` — есть следующая порция текущего прохода; `false` — проход завершён, следующий запрос с токеном начнёт очередной опрос

Пример ответа без изменений:

json

{
  "returns": [],
  "next_page_token": "непрозрачный токен продолжения",
  "has_more": false
}

Продолжение обмена

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

http

GET https://поддомен.oship.ru/api/seller/returns/{shop UUID}/changes?page_token={next_page_token}
Authorization: Ваш API key

Чтобы изменить размер порции, передайте limit вместе с page_token. Например, запрос ниже уменьшит следующую порцию до пяти возвратов. Продолжение начнётся с прежней позиции; выбранный размер сохранится в новом токене и будет использоваться также при дальнейших периодических опросах. Токены, полученные до появления limit, остаются действительными и по умолчанию используют порцию из 100 возвратов.

http

GET https://поддомен.oship.ru/api/seller/returns/{shop UUID}/changes?page_token={next_page_token}&limit=5
Authorization: Ваш API key

Если has_more: true, сразу запросите следующую порцию. Если false, текущий проход завершён: сохраните next_page_token и используйте его при следующем периодическом опросе. Токен возвращается и при пустом returns; он привязан к аккаунту и магазину, его нельзя изменять или использовать для другого магазина.

Сначала сохраните все записи ответа у себя, затем сохраните токен. Запись в своей системе обновляйте по id возврата oShip. При status: "deleted" отметьте её удалённой. При ошибке запроса повторите его с прежним токеном. Повторная выдача записей предусмотрена: обрабатывайте её идемпотентно и не отбрасывайте запись только из-за совпавшего updated_at — несколько изменений могут произойти в одну секунду.

Все даты в ответе /changes представлены в UTC в формате YYYY-MM-DD HH:MM:SS. Некорректная дата, повреждённый токен, токен другого магазина/аккаунта или сочетание page_token с updated_since приводят к ошибке 400. Действующие проверки API key, доступа к разделу и принадлежности магазина аккаунту сохраняются.

Ошибки

HTTP-статус	Причина
`400`	Некорректные `updated_since` или `page_token`, токен другого аккаунта/магазина, переданы оба параметра одновременно либо `limit` не является целым числом от `1` до `100`
`403`	Нет доступа к API или не подключён раздел «Возвраты»
`404`	Магазин не найден или не принадлежит аккаунту

Значения статусов и результатов

scheme: fbs, fbo, unknown — схема не определена, manual — ручной возврат.
status: accepted — ожидает обработки, assessment — идёт оценка, assessed — оценён, manager_attention — требует реакции менеджера, warehouse_attention — требует реакции склада, processed — обработан, deleted — удалён.
condition: missing — товар отсутствует, ok — без проблем, damaged — повреждён, destroyed — уничтожен, decision — требует решения; null — состояние ещё не указано.
result: written_off — списан, restored — восстановлен, discounted — уценён; null — результат не указан.

condition_description содержит описание состояния конкретного экземпляра товара, до 200 символов, либо null. Статус processed также используется, когда администратор отметил возврат обработанным без оценки. В этом случае состояние и результат товаров могут остаться незаполненными; основание доступно в истории.

Варианты ошибок: 400 — не указан UUID магазина или обязательная дата списка; 403 — нет доступа к API или разделу; 404 — магазин или возврат не найден.

Поставки FBO

Получение списка всех поставок раздела

Запрос

GET https://поддомен.oship.ru/api/seller/supplies
Authorization: Ваш API key

Возвращает последние 100 поставок c сортировкой по дате создания.

Ответ

[
    {
        "shop": {
            "uuid": UUID магазина,
            "name": Название магазина,
            "source": {
                "name": Название источника магазина,
                "slug": техническое наименование источника магазина
            }
        },
        "number": Номер поставки,
        "warehouse": Наименование склада маркетплейса,
        "shipment_date": Планируемая дата отгрузки,
        "status": Статус поставки (возможные значения: accepted, packaging, shipped),
        "accepted_at": Дата создания поставки,
        "packaging_at": Дата начала сборки поставки,
        "shipped_at": Дата окончания сборки поставки
    },
    ...
]

Получение списка поставок конкретного магазина

Запрос

GET https://поддомен.oship.ru/api/seller/supplies/{shop UUID}
Authorization: Ваш API key

Возвращает последние 100 поставок c сортировкой по дате создания.

Значение для параметра shop_UUID можно узнать из запроса получения списка магазинов

Ответ

[
    {
        "number": Номер поставки,
        "warehouse": Наименование склада маркетплейса,
        "shipment_date": Планируемая дата отгрузки,
        "status": Статус поставки (возможные значения: accepted, packaging, shipped),
        "accepted_at": Дата создания поставки,
        "packaging_at": Дата начала сборки поставки,
        "shipped_at": Дата окончания сборки поставки

    },
    ...
]

Получение подробной информации по конкретной поставке

Запрос

GET https://поддомен.oship.ru/api/seller/supplies/{shop UUID}/{supplie number}
Authorization: Ваш API key

Значение для параметра shop_UUID можно узнать из запроса получения списка магазиновsupplie number - номер поставки

Ответ

{
    "number": Номер поставки,
    "warehouse": Наименование склада маркетплейса,
    "shipment_date": Планируемая дата отгрузки,
    "status": Статус поставки (возможные значения: accepted, packaging, shipped),
    "accepted_at": Дата создания поставки,
    "packaging_at": Дата начала сборки поставки,
    "shipped_at": Дата окончания сборки поставки,
    "products": [
        {
            "code": Артикул товара,
            "name": Наименование товара,
            "cis": Маркировка "Честный знак",
            "assigned_at": Дата сканирования товара при сборке,
            "barcodes": Массив штрихкодов товара в поставке,
            "cargo_id": Идентификатор грузового места,
            "cargo_type": Тип грузового места (возможные значения: PALLET, BOX)
        },
        ...
        ]
}

Важно

Ваш API key доступен на странице Настройки аккаунта

Описание API ​

Авторизация ​

Отправка запросов ​

Маркировка «Честный знак» ​

IMEI ​

Цена продажи ​

Запросы ​

Получение списка магазинов ​

Запрос ​

Ответ ​

Подтверждение заказов ​

Получение списка заказов раздела Подтверждение по планируемой дате отгрузки ​

Запрос ​

Ответ ​

Получение списка заказов раздела Подтверждение конкретного магазина по планируемой дате отгрузки ​

Запрос ​

Ответ ​

Получение подробной информации по конкретному заказу раздела Подтверждение ​

Запрос ​

Ответ ​

Подтверждение одного заказа без сканирования ​

Запрос ​

Ответ ​

Упаковка заказов ​

Получение списка всех заказов раздела Упаковка по планируемой дате отгрузки ​

Запрос ​

Ответ ​

Получение списка заказов раздела Упаковка конкретного магазина по планируемой дате отгрузки ​

Запрос ​

Ответ ​

Получение подробной информации по конкретному заказу раздела Упаковка ​

Запрос ​

Ответ ​

Магазины с типом API ​

Добавление заказа в раздел Подтверждение для магазина с типом API ​

Запрос ​

Ответ ​

Изменение заказа в разделе Подтверждение для магазина с типом API ​

Запрос ​

Ответ ​

Получение подробной информации по конкретному заказу из раздела Подтверждение для магазина с типом API ​

Запрос ​

Ответ ​

Получение списка заказов раздела Подтверждение конкретного магазина с типом API по планируемой дате отгрузки ​

Запрос ​

Ответ ​

Добавление заказа в раздел Упаковка для магазина с типом API ​

Запрос ​

Ответ ​

Изменение заказа в разделе Упаковка для магазина с типом API ​

Запрос ​

Ответ ​

Получение подробной информации по конкретному заказу из раздела Упаковка для магазина с типом API ​

Запрос ​

Ответ ​

Получение списка заказов раздела Упаковка конкретного магазина с типом API по планируемой дате отгрузки ​

Запрос ​

Ответ ​

Возвраты ​

Получение возвратов магазина по дате выдачи ​

Получение подробной информации о возврате ​

Получение изменений возвратов ​

Запрос ​

Ответ ​

Продолжение обмена ​

Ошибки ​

Значения статусов и результатов ​

Поставки FBO ​

Получение списка всех поставок раздела ​

Запрос ​

Ответ ​

Получение списка поставок конкретного магазина ​

Запрос ​

Ответ ​

Получение подробной информации по конкретной поставке ​

Запрос ​

Ответ ​

Описание API

Авторизация

Отправка запросов

Маркировка «Честный знак»

IMEI

Цена продажи

Запросы

Получение списка магазинов

Запрос

Ответ

Подтверждение заказов

Получение списка заказов раздела Подтверждение по планируемой дате отгрузки

Запрос

Ответ

Получение списка заказов раздела Подтверждение конкретного магазина по планируемой дате отгрузки

Запрос

Ответ

Получение подробной информации по конкретному заказу раздела Подтверждение

Запрос

Ответ

Подтверждение одного заказа без сканирования

Запрос

Ответ

Упаковка заказов

Получение списка всех заказов раздела Упаковка по планируемой дате отгрузки

Запрос

Ответ

Получение списка заказов раздела Упаковка конкретного магазина по планируемой дате отгрузки

Запрос

Ответ

Получение подробной информации по конкретному заказу раздела Упаковка

Запрос

Ответ

Магазины с типом API

Добавление заказа в раздел Подтверждение для магазина с типом API

Запрос

Ответ

Изменение заказа в разделе Подтверждение для магазина с типом API

Запрос

Ответ

Получение подробной информации по конкретному заказу из раздела Подтверждение для магазина с типом API

Запрос

Ответ

Получение списка заказов раздела Подтверждение конкретного магазина с типом API по планируемой дате отгрузки

Запрос

Ответ

Добавление заказа в раздел Упаковка для магазина с типом API

Запрос

Ответ

Изменение заказа в разделе Упаковка для магазина с типом API

Запрос

Ответ

Получение подробной информации по конкретному заказу из раздела Упаковка для магазина с типом API

Запрос

Ответ

Получение списка заказов раздела Упаковка конкретного магазина с типом API по планируемой дате отгрузки

Запрос

Ответ

Возвраты

Получение возвратов магазина по дате выдачи

Получение подробной информации о возврате

Получение изменений возвратов

Запрос

Ответ

Продолжение обмена

Ошибки

Значения статусов и результатов

Поставки FBO

Получение списка всех поставок раздела

Запрос

Ответ

Получение списка поставок конкретного магазина

Запрос

Ответ

Получение подробной информации по конкретной поставке

Запрос

Ответ