История заказов

IMSHOP Retail Protocol (IRP) является объектом интеллектуальной собственности ООО «АЙ ЭМ СОЛЮШНЗ» (IMSHOP) и защищён как объект авторского права. Свидетельство о депонировании произведения № 023-014461 от 16 января 2023 г. подтверждает исключительные права ООО «АЙ ЭМ СОЛЮШНЗ» на данные технологии.

IMSHOP Retail Protocol создан по заказу ООО «АЙ ЭМ СОЛЮШНЗ». Использование IMSHOP Retail Protocol допустимо только при взаимодействии с ООО "АЙ ЭМ СОЛЮШНЗ" и наличии действующего лицензионного договора. Более подробно можно ознакомиться здесь.

Для авторизованного пользователя доступна синхронизация истории заказов в мобильном приложении с его общей историей заказов.

Запрос

APP SERVER → INFRASTRUCTURE

От вас потребуется URL, на который наш сервер будет слать POST-запрос. Да, мы запрашиваем данные через POST, а не через GET.

В вашу систему будут приходить вот такие данные:

{
    "userIdentifier": "12345",
    "page": 1
}

• userIdentifier — идентификатор пользователя (обязательное поле), полученный от системы клиента на этапе авторизации

• page – номер текущей страницы. Вы сами определяете размер отдаваемой страницы

Ответ:

{
    "nextPage": 2,
    "orders": [
        {
            "id": "111003",
            "status": "Доставлен в Махачкалу",
            "statusMessage": "Александр, заказ прибыл в ваш город и будет доставлен завтра",
            "price": 1003.33,
            "deliveryPrice": 0,
            "itemsPrice": 1003.33,
            "createdOn": 1613800424,
            "receiptUrl": "https://imshop.io/",
            "updatedOn": 1613807437,
            "inProgress": true,
            "itemsPrice": 29336,
            "usedBonuses": 0,
            "appliedDiscount": 0,
            "retryPaymentMethod": "payu",
            "cancellable": true,
            "trackingUrl": "https://www.cdek.ru/ru/tracking?order_id=1234567890",
            "items": [
                {
                    "privateId": "6527",
                    "configurationId": "3464",
                    "name": "Плюшевый медведь",
                    "image": "https://some.com/files/image.jpg",
                    "price": 29336,
                    "quantity": 1,
                    "discount": 0,
                    "subtotal": 29336                    
                }
            ],
            "publicDeliveryDetails": {
                "title": "Доставка курьерской службой",
                "details": "Доставка до двери",
                "buyerName": "Александр",
                "buyerEmail": "[e-mail]",
                "buyerPhone": "79998887766",
                "deliveryDate": "2021-02-24",
                "deliveryTime": "до 18:00",
                "trackingUrl": "https://www.cdek.ru/ru/tracking?order_id=1234567890",
                "deliveryDateISO": "2022-09-26T08:12:32.940Z",
                "courierPhone": "79112223344",
                "courierName": "Крутой доставщик",
                "storageDateDeadline": "2021-03-15",
                "canExtendStorageTime": true
            },
            "publicPaymentDetails": {
                "paid": true,
                "paymentComment": "Оплачено с Apple Pay"
            },
            "publicId": "М-428",
            "rating": 5,
            "comment": "Все отлично"
        }
    ]
}

• id — идентификатор заказа в вашей системе (обязательное поле)

• publicId — идентификатор заказа, видимый пользователю (опционально); будет отображаться вместо id, если передан в ответе

• typeOrder — Тип заказа. Отображается на экране заказов перед номером и в расширенной истории заказа. По-умолчанию "Заказ" (опционально)

• createdOn — дата создания заказа (обязательное поле, unix time stamp)

• status — статус заказа (обязательное поле)

• statusMessage — подробное описание статуса заказа (опционально)

• updatedOn - время последнего обновления заказа (unix timestamp в секундах) (опционально)

• inProgress - true / false - активность заказа. последний активный заказ будет отображен на главном экране приложения (опционально)

• price — цена заказа (обязательное поле)

• receiptUrl - ссылка на pdf файл для передачи чека или ссылка на ОФД-чек

• deliveryPrice - стоимость доставки (опционально)

• itemsPrice - цена товаров в заказе без учета скидок, бонусов и предложений (опционально)

• retryPaymentMethod — отдавать id оплаты если оплата возможна, если нет то null и повторная оплата будет недоступна, также чтобы кнопка повторной оплаты работала обязательно нужно передать объект publicDeliveryDetails(описание ниже) с заполненными полями title, buyerName, buyerPhone.

• trackingUrl — ссылка на страницу отслеживания почтового или курьерского отправления (необязательное поле); отображается на экране списка заказов

• cancellable - необязательно, заказ можно отменять, например, по кнопке "Отмена заказа", по-умолчнию false

• items — набор товаров в заказе (обязательное поле; массив может быть пустым)

  • privateId — идентификатор товара в системе клиента (обязательное поле)

  • configurationId —идентификатор товарного предложения (необязательное поле)

  • name — название товара (обязательное поле)

  • image — URL фото товара (обязательное поле)

  • price — цена за одну позицию (необязательное поле)

  • quantity — количество (обязательное поле)

  • discount — общая скидка (необязательное поле)

  • subtotal — итоговая стоимость (обязательное поле)

  • removed — был удалён из заказа (напр., покупатель отказался от не подошедших размеров при вручении)

    • если товар был принят частично (напр., куплено 2 из 3 единиц), необходимо передать две одинаковые конфигурации, с quantity 2 и 1 соответственно, и во второй установить "removed": true

    • при нажатии "Повторить заказ", товары, от которых покупатель отказался, в корзину добавлены не будут

• usedBonuses - количество использованных бонусов (опционально)

• appliedDiscount - примененная скидка (опционально)

• publicDeliveryDetails - детали доставки (опционально)

  • title - название свособа доставки

  • details - подробное описание доставки

  • buyerName - имя получателя

  • buyerPhone - телефон получателя

  • buyerEmail - email получателя

  • deliveryDate - ожидаемая дата доставки в формате YYYY-MM-DD

  • deliveryTime - ожидаемое время доставки в человекочитаемом виде

  • trackingUrl — ссылка на страницу отслеживания почтового или курьерского отправления (необязательное поле); отображается на экране просмотра детальной информации о заказе

  • deliveryDateISO - опционально, "2022-09-26T08:12:32.940Z" время в формате date time iso, например moment().toISOString()

  • courierPhone - опционально, Номер телефона доставщика

  • courierName - опционально, Имя доставщика

  • storageDateDeadline - опционально, срок хранения в формате YYYY-MM-DD

  • canExtendStorageTime - можно ли продлить срок хранения

• publicPaymentDetails - детали оплаты

  • paid - true если заказ оплачен

  • paymentComment - коментарий к платежу

  • receiptUrl - ссылка на чек

• ratingRequired - true/false в зависимости нужно ли собрать оценку с пользователя

• rating - Значение оценки обслуживания пользователя от 1 до 5 с ендпоинта оценки качества обслуживания

• ratingComment - Сохраненный комментарий пользователя с ендпоинта оценки качества обслуживания

Обратите внимание на параметр nextPage. Это номер следующей страницы истории заказов. nextPage должен быть целым числом. Если параметр nextPage отсутствует или является, например, false, null, undefined, то запрос на получение следующей страницы выполнен не будет.

Минимальный набор полей необходимый для отображения расширенной истории заказов

{
    "appliedDiscount": 0,
    "createdOn": 1633340823,
    "id": "MC-00415123",
    "items":
    [
        {
            "image": "https://masterclub.store/media/catalog/product/S/T/STHR323K-RU.jpg",
            "name": "Перфоратор STANLEY STHR323K, SDS-PLus, 32 мм, 1250 Вт, 3.5 Дж, 850 об/мин, 4100 уд/мин, 3 режима",
            "price": 9290,
            "privateId": "16053",
            "quantity": 1,
            "subtotal": 9290
        }
    ],
    "price": 9290,
    "publicDeliveryDetails":
    {
        "buyerEmail": "[e-mail]",
        "buyerName": "Вова",
        "buyerPhone": "[phone]",
        "details": "Курьерская служба - Доставка по г. Москва, 1 день",
        "title": "Курьерская служба - Доставка по г. Москва, 1 день"
    },
    "publicPaymentDetails":
    {
        "paid": false,
        "paymentComment": "Оплата картой онлайн (PayU)"
    },
    "retryPaymentMethod": "payu",
    "status": "Доставлен",
    "updatedOn": 1633341014,
    "usedBonuses": 0
}

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

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

Следует помнить, что этот запрос будет приходить из нашего доверенного, авторизованного сервера, это — не публичный API.

Любой другой ответ API будет расцениваться как отсутствие истории заказов.

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

От вас потребуется URL, на который наш сервер будет слать POST-запрос. Да, мы запрашиваем данные через POST, а не через GET.

Запрос на изменение срока хранения заказа

Описание формата

• id - номер заказа в системе клиента

• extendStorageTime - указание на то, что нужно продлить срок хранения

Пример

{
    "id": "12345",
    "extendStorageTime": true
}

Ответ на изменение срока хранения заказа

Описание формата

• success - флаг успешного выполнения

• storageDateDeadline - новый срок хранения в формате YYYY-MM-DD

• canExtendStorageTime - можно ли еще продлевать срок хранения

Пример ответа

{
    "success": true,
    "storageDateDeadline": "2024-09-15",
    "canExtendStorageTime": true
}