Документация oShip.ru

Appearance

Описание API ​

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

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

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

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

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

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

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

Тип метода запросов GET

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

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

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

Запросы ​

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

Запрос ​

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

Ответ ​

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

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

Запрос ​

js
GET https://поддомен.oship.ru/api/seller/orders?shipment_date=2023-08-30
Authorization: **Ваш API key**

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

Ответ ​

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

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

Запрос ​

js
GET https://поддомен.oship.ru/api/seller/orders/<shop UUID>?shipment_date=2023-08-30
Authorization: Ваш API key

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

Ответ ​

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

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

Запрос ​

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

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

Ответ ​

js
{
    "number": Номер заказа,
    "comment": Текст комментария,
    "shipment_date": Планируемая дата отгрузки,
    "status": Статус заказа (возможные значения: accepted,packaged,shipped,cancelled),
    "accepted_at": Дата приёма заказа,
    "packaged_at": Дата упаковки заказа,
    "shipped_at": Дата отгрузки заказа,
    "cancelled_at": Дата отмены заказа
    "products": [
        {
            "code": Код товара,
            "name": Название товара,
            "cis": Код "Честный знак",
            "assigned_at": Дата сканирования товара при упаковке,
            "barcodes": ["124312345"]
        },
        ...
    ],
    "packages": [
        {
            "number": Номер грузового места,
            "barcode": Штрих-код грузового места,
            "status": Статус грузового места (возможные значения: accepted,packaged,shipped),
            "packaged_at": Дата упаковки грузового места,
            "shipped_at": Дата отгрузки грузового места
        },
        ...
    ]
}

Добавление заказа ​

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

Запрос ​

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

{
  "number": "00001", // Номер заказа
  "comment": "Текст комментария", //Комментарий к заказу.Ограничение 250 символов (необязательно)
  "shipment_date": "2023-09-20", // Плановая дата отгрузки заказа
  "accepted_at": "2023-09-19", // Дата подтверждения заказа
  "products": [ // информация о товарах (массив)
    {
      "code": "111", // код товара (необязательно, если указаны barcodes)
      "name": "Test", // наименование (необязательно)
      "barcodes": ["2000259506566", ...], // массив штрихкодов товара (необязательно, если указан code)
      "cis": "qw4g3gasdfqw3e3f..." // честный знак (необязательно)
    },
    ...
  ],
  "packages": [ // информация об упаковках (массив)
    {
      "number": "1212", // номер упаковки
      "barcode": "1212" // штрихкод упаковки
    },
    ...
  ],
  "label": "" // файл с этикеткой в Base64
}

Значение 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 (Label less 10000 bytes or mime type not "application/pdf") - этикетка заказа менее 10000 байт или тип этикетки не pdf;
  • 409 - заказ с таким номером уже существует у этого магазина.

Изменение заказа ​

Запрос ​

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

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

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

Ответ ​

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

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

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

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

Запрос ​

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

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

Ответ ​

js
{
    "number": Номер заказа,
    "comment": Текст комментария,
    "shipment_date": Планируемая дата отгрузки,
    "status": Статус заказа (возможные значения: accepted,packaged,shipped,cancelled),
    "accepted_at": Дата приёма заказа,
    "packaged_at": Дата упаковки заказа,
    "shipped_at": Дата отгрузки заказа,
    "cancelled_at": Дата отмены заказа
    "products": [
        {
            "code": Код товара,
            "name": Название товара,
            "cis": Код "Честный знак",
            "assigned_at": Дата сканирования товара при упаковке
        },
        ...
    ],
    "packages": [
        {
            "number": Номер грузового места,
            "barcode": Штрих-код грузового места,
            "status": Статус грузового места (возможные значения: accepted,packaged,shipped),
            "packaged_at": Дата упаковки грузового места,
            "shipped_at": Дата отгрузки грузового места
        },
        ...
    ]
}

Важно

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