Ревизия 1.2.3 от 14.04.2025

ЧП «ШАТЕ-М Плюс»

Уважаемые клиенты, информируем Вас о том, что нами было введено лимитирование запросов проценки для предоставления более качественного сервиса, чтобы не нагружать нашу систему и обеспечить ее быструю и корректную работу.
Текущие лимиты на запросы цены артикула следующие:
За 15 минут B2B портал: 250
За 15 минут API: 1200
За день B2B портал: 2500
За день B2B API: 40000

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

1. Auth (Авторизация)

ВНИМАНИЕ! Прежде чем начать работу с API - уточните у Вашего менеджера о доступности функционал API Вам.

Мы используем тип авторизации Bearer

Для получения токена есть 2 способа:

●       передать login и password с телом запроса типа Content-type application/x-www-form-urlencoded;

●       передать ApiKey (получаете от Вашего менеджера) с телом запроса типа Content-type application/x-www-form-urlencoded.

Полученный в ответе токен необходимо добавлять в заголовок (Headers) всех запросов в параметр Authorization (Authorization: Bearer <access_token>).

1.1 POST /api/v1/auth/login (Авторизация по логину и паролю)

Авторизация через логин и пароль от личного кабинета.

Метод принимает на вход:

Ответ метода:

{
"access_token": "eyJhbGciOiJQUzI1NiIsInR5cCI6ImF0K2p3dCJ9",
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "",
"scope": "ShateAuth"
}

1.2 POST /api/v1/auth/loginByapiKey (Авторизация по ApiKey)

Авторизация через apikey, полученный от Вашего менеджера

Метод принимает на вход:

Ответ метода аналогичен POST /api/v1/auth/login

2. Articles (Информация по артикулу)

2.1 GET /api/v1/articles/{articleId} (Подробная информация об артикуле)

Позволяет получить информацию по идентификатору артикула.
Поля tradeMark, contents и extendedInfo добавляются в ответ только в случае передачи include.

Важно! Параметр include может значительно увеличивать время ответа (из-за объема данных).

Для получения внутреннего идентификатора товара воспользуйтесь методами - 

GET /api/v1/articles/search/{articleSearchString} или POST /api/v1/articles/search

Метод принимает на вход:

Ответ метода:

{
"article": {
  "id": 1248288,
  "code": "OC100",
  "tradeMarkName": "KNECHT",
  "name": "Фильтр масляный",
  "description": "Замена - OC976. BX 82-93",
  "unitOfMeasure": "ШТ"
},
"tradeMark": {
  "name": "KNECHT",
  "country": "Германия",
  "description": "Торговая марка KNECHT принадлежит концерну...",
  "url": "http://www.mahle.com",
  "catalogUrl": "http://www.mahle.com",
  "extendedWarranty": false
},
"contents": [
  {
    "sortOrder": 0,
    "contentId": "17BD2871DF2E9294E85B12E039929D5791EE8A0303728BFA9A22B6B0E8F8DFCB",
    "contentType": "ImageTwoDimensional"
  }
],
"extendedInfo": {
  "extendedDescription": "Описание",
  "originals": [
    {
      "articleCodes": [
        "string"
      ],
      "tradeMarkName": "KNECHT"
    }
  ],
  "characteristics": [
    {
      "key": "Внутренний диаметр 2 (мм)",
      "value": "62,0"
    }
  ],
  "applicability": [
    {
      "name": "CITROEN",
      "models": [
        {
          "name": "JUMPER фургон (230L)",
          "modifications": [
            {
              "name": "CITROEN JUMPER Фургон (230L) 2.0",
              "mnEngineCode": "RFW (XU10J2U)",
              "beginDate": "199403",
              "endDate": "200204",
              "kWt": "80",
              "hPower": "109",
              "cylinders": "4",
              "vol": "1998"
            }
          ]
        }
      ]
    }
  ]
}
}

2.2 GET /api/v1/articles/{articleId}/analogs (Получение аналогов)

Получение информации об аналогах товара по его идентификатору.

Если результат аналогов содержит более одного артикула, параметры contents и extended_Info не учитываются, соответствующие поля не заполняются.

Для получения внутреннего идентификатора товара воспользуйтесь методами - 

GET /api/v1/articles/search/{articleSearchString} или POST /api/v1/articles/search.

Метод принимает на вход:

Ответ аналогичен предыдущему методу GET /api/v1/articles/{articleId}

2.3 GET /api/v1/articles/search (Поиск по строке поиска)

Получение информации о товаре по артикулу товара.

Если результат содержит более одного артикула, параметры contents и extended_Info не учитываются, соответствующие поля не заполняются.

Метод принимает на вход:

Ответ метода аналогичен GET /api/v1/articles/{articleId}.

2.4 POST /api/v1/articles/search (Поиск артикулов (по фильтру)

Получение информации о массиве артикулов, используя внутренние идентификаторы или каталожные номера.

Если результат содержит более одного артикула, параметры contents и extended_Info не учитываются, соответствующие поля не заполняются.

Для получения внутреннего идентификатора товара воспользуйтесь методами:

GET /api/v1/articles/search/{articleSearchString} или POST /api/v1/articles/search.

Метод принимает на вход:

Ответ аналогичен предыдущему методу GET /api/v1/articles/{articleId}.

3. CartItems (Корзина)

3.1 GET /api/v1/cartitems/{cartItemId} (Получение строки корзины)

Получение информации о строке корзины

Идентификатор строки корзины Вы получаете в ответе метода POST /api/v1/cartitems.

Метод принимает на вход:

Ответ метода:

{
"id": 1,
"locationCode": "SHATE-01",
"locationCodeReal": "SHATE-01",
"agreementCode": "SAGR1",
"article": {
  "id": 1248288,
  "code": "OC100",
  "tradeMarkName": "KNECHT",
  "name": "Фильтр масляный",
  "description": "Замена - OC976. BX 82-93",
  "unitOfMeasure": "ШТ"
},
"price": 8.5,
"priceWithMargin": 8.5,
"priceType": "Internal",
"priceMax": 12.32,
"importAllowance": 15,
"currencyCode": "USD",
"quantity": 1,
"quantityInfo": {
  "available": 5,
  "availableType": "Equal",
  "multiplicity": 1,
  "minimum": 1,
  "maximum": 100
},
"addInfo": {
  "city": "Минск",
  "isSale": true,
  "comment": "Царапины справа",
  "isReturnAllowed": true,
  "warningText": "Возврат запрещен. Нельзя заказывать масла моторные и тех. жидкости"
},
"createDateTime": "2022-12-19T08:39:15.525Z",
"comment": "Comment",
"deliveryDateTime": "2022-12-19T08:39:15.525Z",
"shippingDateTime": "2022-12-19T08:39:15.525Z",
"hash": 123456789,
"isImport": true,
"isFree": true
}

3.2 PATCH /api/v1/cartitems/{cartItemId} (Обновление строки корзины)

Обновление данных строки корзины (количество, цена, комментарий).

Можно изменять не все значения, а, например, только quantity.

Метод принимает на вход:

Ответ аналогичен предыдущему методу GET /api/v1/cartitems/{cartItemId}.

3.3 DEL /api/v1/cartitems/{cartItemId} (Удаление строки корзины)

Удаление строки корзины по ее идентификатору.

Идентификатор корзины Вы получаете в ответе метода POST /api/v1/cartitems.

Метод принимает на вход:

Ответом будет код статуса http.

3.4 GET /api/v1/cartitems (Получение всех строк корзины)

Получение всех строк корзины.

Метод принимает на вход:

Ответ аналогичен предыдущему методу GET /api/v1/cartitems/{cartItemId}.

Ответ при возникновении ошибки:

{
    "code" : "DefaultAgreementNotFound",
    "description" : "Договор по умолчанию не найден",
    "messages": [
        "Внимание! Договор по умолчанию не найден. Пожалуйста, свяжитесь с вашим менеджером."
    ]
}
          

3.5 POST /api/v1/cartitems (Добавление строк в корзину)

Добавление строки в корзину.

Предварительно требуется проценка товара для получения параметра priceId (взять из ответа методов POST /api/v1/prices/search и POST /api/v1/prices/search/with_article_info параметр Id (из коллекции Prices)).

Входящие параметры:

Ответ аналогичен предыдущему методу GET /api/v1/cartitems/{cartItemId}.

3.6 DEL /api/v1/cartitems (Удаление всех строк корзины)

Удаление всех строк из корзины.

Входящих параметров нет.

Ответом будет код статуса http.

4. Contents (Медиаконтент)

4.1 POST /api/v1/contents/search (Получение контента)

Получение ссылки на изображение товара.

Предварительно требуется получить параметр ContentId из методов информации об артикуле (см. гл. 2 – Articles).

Метод принимает на вход:

Ответ метода:

[
{
  "id": "17BD2871DF2E9294E85B12E039929D5791EE8A0303728BFA9A22B6B0E8F8DFCB",
  "value": "data:image/webp;base64..."
} 
]

5. Customer (ПОЛЬЗОВАТЕЛЬ)

5.1 GET /api/v1/customer/agreements (Получение договоров)

Получение активных договоров пользователя (кроме договоров по программе лояльности и экваирингу).

Внутренний номер договора используется при оформлении заказа.

Входных параметров нет.

Ответ метода:

[
{
  "code": "SAGR1",
  "agreementGroup": "НАЛ",
  "description": "Физ. лицо",
  "locationCode": "SHATE-01",
  "currencyCode": "USD",
  "isActive": true,
  "isEnabledPickup": true,
  "isEnabledDelivery": true
}
]

5.2 GET /api/v1/customer/info

Получение информации о клиенте

Данная информация отображается в личном кабинете в разделе «Персональные данные».

Входящих параметров нет.

Ответ метода:

[
{
  "login": "Test123",
  "code": "S0001",
  "name": "Тест",
  "phone": "+123456789",
  "email": "test@gmail.com",
  "defaultDeliveryAddressCode": "Д1"
}
]

6. Delivery (ДОСТАВКА)

6.1 GET /api/v1/delivery/addresses (Получение адресов доставок)

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

Входящих параметров нет.

Ответ метода:

[
{
  "code": "Д1",
  "city": "Минск",
  "address": "ул. Мира, д. 2А",
  "deliveryZoneCode": "MINSK01"
}
]

6.2 GET /api/v1/delivery/availableDateTimes (Получение доступных дат для доставки)

Получение даты и времени доступных услуг по доставкам.

Предварительно требуется получить код склада или из справочника складов (GET /api/v1/locations), или из корзины (GET /api/v1/cartitems/)

Полученную дату можно использовать в параметре DeliveryDate при оформлении доставки.

Метод принимает на вход:

Ответ метода: массив дат формата 2020-12-02T22:00:00.

7. Locations (Склады)

7.1 GET /api/v1/locations (Получение списка складов)

Получение списка складов компании, на которых находится товар и с которых возможна отгрузка товара.

Нужно использовать для метода получения доступных дат доставки (GET /api/v1/delivery/availableDateTimes).

Входящих параметров у метода нет.

Ответ метода:

[
{
  "code": "SHATE-S01",
  "name": "Центральный склад Привольный",
  "city": "Привольный"
}
]

8. OrderItems (Строки заказа)

8.1 GET /api/v1/orderitems/{orderItemId}/statuseshistory (Получение движения по строке заказа)

Просмотр текущего статуса строки заказа.

Предварительно требуется получить идентификатор строки заказа (из метода GET /api/v1/orders).

Метод принимает на вход:

Ответ метода:

[
{
  "statusCode": 30,
  "dateTime": "2022-12-19T09:03:51.240Z"
}
]

9. OrderItemStatusCodes (Статусы заказов)

9.1 GET /api/v1/orderItemStatusCodes

Получение справочника возможных статусов заказов.

Входящих параметров нет.

Ответ метода:

[
{
  "code": 30,
  "name": "В работе",
  "description": "Заказ успешно обработан"
  "isFinal": false
}
]

10. Orders (Заказы)

Заказ можно оформить 2-мя методами:

●        упрощенно (без размещения в корзину) после проценки товара;

●        после добавления строк в корзину

10.1 GET /api/v1/orders (Получение строк заказа)

Получение списка заказов с возможностью фильтрации по дате, артикулу, бренду, номеру заказа или статусу.

Для фильтрации по статусу нужно получить код статусов из справочника (GET /api/v1/orderItemStatusCodes).

Метод принимает на вход:

Ответ метода:

[
{
  "id": 1,
  "createDateTime": "2022-12-19T09:05:02.945Z",
  "deliveryInfo": {
    "deliveryAddressCode": "Д1"
  },
  "agreementCode": "SAGR1",
  "currencyCode": "USD",
  "totalSum": 8.5,
  "comment": "Comment",
  "note": "Note",
  "orderItems": [
    {
      "id": 1,
      "article": {
        "id": 1248288,
        "code": "OC100",
        "tradeMarkName": "KNECHT",
        "name": "Фильтр масляный",
        "description": "Замена - OC976. BX 82-93",
        "unitOfMeasure": "ШТ"
      },
      "quantity": 1,
      "quantityToShip": 0,
      "quantityShipped": 0,
      "deliveryDateTime": "2022-12-19T09:05:02.945Z",
      "price": 8.5,
      "totalSum": 8.5,
      "statusCode": 0,
      "comment": "Comment"
      "сanReturn": true
    }
  ]
}
]

10.2 POST /api/v1/orders/byPriceItems (Оформление заказа без корзины через ценовое предложение)

Быстрое оформление заказа минуя этап добавления в корзину.

Условия:

●        Все строки заказа должны быть из одного locationCode, иначе заказ не будет оформлен.

●        Если deliveryInfo (информация о доставке) == null или не передан, то заказ будет оформлен на самовывоз.

●        Если deliveryDateTime == null, то заказ будет оформлен на ближайшую возможную доставку (в зависимости от deliveryType).

●        expectedDateTimeOfArrivalAllItems - дата и время (UTC) прибытия всех строк заказа к клиенту, к которой все строки должны быть отгружены/доставлены. Все строки заказа будут валидироваться на возможность отгрузки/доставки (в зависимости от параметров заказа) к указанной дате и времени. И если хоть одна строка не будет отгружена/доставлена к данному времени (дата и время отгрузки/доставки по строке больше переданного значения),то заказ не будет создан. Не обязательно к заполнению. Если не заполнено, то дата и время доставки/отгрузки не будут валидироваться.

●        Если код группы договора == "НАЛ", "ЭКВАИР" или "МАГ", то поля fio и phone обязательны к заполнению.

Метод принимает на вход параметры (идентификатор прайса, дату доставки) из ответа проценки POST /api/v1/prices/search.

В случае изменения цены в меньшую сторону в пределах допустимого отклонения появится сообщение (поле warnings) об изменении цены и значения старой и новой цены (Пример: "Произошло изменение цены в пределах допустимого отклонения. oldPrice : 3.72 ; newPrice : 3.44 ")

Метод принимает на вход:

Ответ метода:

{
"id": 1,
"createDateTime": "2022-12-19T09:10:30.131Z",
"deliveryInfo": {
  "deliveryAddressCode": "Д1"
},
"agreementCode": "SAGR1",
"currencyCode": "USD",
"totalSum": 8.5,
"comment": "Comment",
"note": "Note",
"orderItems": [
  {
    "id": 1,
    "article": {
      "id": 1248288,
      "code": "OC100",
      "tradeMarkName": "KNECHT",
      "name": "Фильтр масляный",
      "description": "Замена - OC976. BX 82-93",
      "unitOfMeasure": "ШТ"
    },
    "quantity": 1,
    "quantityToShip": 0,
    "quantityShipped": 0,
    "deliveryDateTime": "2022-12-19T09:10:30.131Z",
    "price": 8.5,
    "totalSum": 8.5,
    "statusCode": 0,
    "comment": "Comment"
    "warnings": null
  }
]
}

Ответ при возникновении ошибки:

{
"errors": [
  "Товар не оформлен в заказ. По договору 100% предоплата."
],
"errorDescriptions": {
  "additionalProp1": "Ошибка валидации строк заказа"
},
"priceItemErrors": [
  {
    "priceId": 58A82086838AA9FFDE305539C21BA3DF659E574C43A3058EF4D6B84A8FB364ACACFA835B359EFE5D9E2A930A542E0C9106F909B401DA240DDD8C287201AB37B05C5AE2DC36495098494CA7118FE3B5BF,
    "hash": 0,
    "current": {
      "price": 8.5,
      "priceWithMargin": 8.5,
      "quantityInfo": {
        "available": 5,
        "availableType": "Equal",
        "multiplicity": 1,
        "minimum": 1,
        "maximum": null
      },
      "deliveryDateTime": "2022-12-19T09:13:32.262Z",
      "shippingDateTime": "2022-12-19T09:13:32.262Z"
    },
    "errors": [
      "Unknown"
    ]
  }
]
}

10.3 POST /api/v1/orders/byCartItems (оформление заказа через строки корзины)

Оформление в заказ строк, находящихся в корзине.

Условия

●        Все строки заказа должны быть из одного locationCode, иначе заказ не будет оформлен.

●        Если deliveryInfo (информация о доставке) == null или не передан, то заказ будет оформлен на самовывоз.

●        Если deliveryDateTime == null, то заказ будет оформлен на ближайшую возможную доставку (в зависимости от deliveryType).

●        expectedDateTimeOfArrivalAllItems - дата и время (UTC) прибытия всех строк заказа к клиенту,к которой все строки должны быть отгружены/доставлены.Все строки заказа будут валидироваться на возможность отгрузки/доставки(в зависимости от параметров заказа) к указанной дате и времени.И если хоть одна строка не будет отгружена/доставлена к данному времени(дата и время отгрузки/доставки по строке больше переданного значения),то заказ не будет создан. Не обязательно к заполнению. Если не заполнено, то дата и время доставки/отгрузки не будут валидироваться.

●        Если код группы договора == "НАЛ" или "ЭКВАИР" или "МАГ", то поля fio и phone обязательны к заполнению.

В случае изменения цены в меньшую сторону в пределах допустимого отклонения появится сообщение (поле warnings) об изменении цены и значения старой и новой цены (Пример: "Произошло изменение цены в пределах допустимого отклонения. oldPrice : 3.72 ; newPrice : 3.44 ")

Метод принимает на вход параметры из ответа получения строк корзины GET /api/v1/cartitems.

Метод принимает на вход:

Ответ метода аналогичен предыдущему методу.

11. Prices (Проценка)

Поиск ценовых предложений (проценка)

Условия:

При превышении допустимого количества запросов к нашей базе Вы будете получать в ответе ошибку 429 (Too Many Requests). Ограничение в проценке действует до конца дня. Для уточнения лимитов обратитесь к Вашему менеджеру либо в нашу техподдержку через форму обратной связи.

Для проценки артикула предварительно требуется получить внутренний идентификатор артикула (из метода POST /api/v1/articles/search или GET /api/v1/articles/search/{articleSearchString})

• Если у пользователя несколько адресов, то для получения даты доставки до конкретного адреса, нужно указать код адреса доставки (взять из метода GET /api/v1/delivery/addresses).

• Если у пользователя несколько номеров договоров, то нужно указать конкретный номер (взять из метода GET /api/v1/customer/agreements). в противном случае будет выбран номер договора по умолчанию (личный кабинет – персональные данные).

• У Вашего менеджера можно запросить ограничения на вывод предложений наличия и под заказ.

11.1 POST /api/v1/prices/search (Поиск ценовых предложений)

Метод принимает на вход:

Ответ метода (коллекция ценовых предложений):

[
{
  "id": "EA0A241990CBE80CD928445ADB1146A81861AFA2B69CC0F1C59EEBCEA5B67A12608B2F0799466CC6B019C63056DDB2565D9E288D38DE21BCC5CB706019FF029E",
  "articleId": 1248288,
  "locationCode": "SHATE-01",
  "locationCodeReal": "SHATE-01",
  "agreementCode": "SAGR1",
  "type": "Internal",
  "price": {
    "value": 8.5,
    "valueWithMargin": 8.5,
    "valueRecommended": null,
    "currencyCode": "USD"
    "priceMax": 12.32,
    "importAllowance": 15,
  },
  "quantity": {
    "available": 5,
    "availableType": "Equal",
    "multiplicity": 1,
    "minimum": 1,
    "maximum": null
  },
  "supplyProbability": {
    "lastUpdateDateTime": "2022-12-19T09:22:08.260Z",
    "rating": 99
  },
  "addInfo": {
    "city": "Минск",
    "isSale": true,
    "comment": "Царапины справа",
    "isReturnAllowed": true,
    "warningText": "Возврат запрещен. Нельзя заказывать масла моторные и тех. жидкости"
  },
  "priority": 1,
  "hash": 123456789,
  "deliveryDateTimes": [
    {
      "deliveryAddressCode": "Д1",
      "deliveryDateTime": "2022-12-19T09:22:08.260Z"
    }
  ],
  "shippingDateTime": "2022-12-19T09:22:08.260Z",
  "isImport": true,
  "isFree": true
}
]

11.2 POST /api/v1/prices/search/with_article_info (Поиск ценовых предложений (с группировкой по артикулу и информацией об артикуле)).

Входящие параметры аналогичны предыдущему методу.

Ответ метода (коллекция ценовых предложений):

[
{
  "article": {
    "id": 1248288,
    "code": "OC100",
    "tradeMarkName": "KNECHT",
    "name": "Фильтр масляный",
    "description": "Замена - OC976. BX 82-93",
    "unitOfMeasure": "ШТ"
  },
  "prices": [
    {
      "id": "EA0A241990CBE80CD928445ADB1146A81861AFA2B69CC0F1C59EEBCEA5B67A12608B2F0799466CC6B019C63056DDB2565D9E288D38DE21BCC5CB706019FF029E",
      "articleId": 1248288,
      "locationCode": "SHATE-01",
      "locationCodeReal": "SHATE-01",
      "agreementCode": "SAGR1",
      "type": "Internal",
      "price": {
        "value": 8.5,
        "valueWithMargin": 8.5,
        "valueRecommended": null,
        "currencyCode": "USD"
        "priceMax": 12.32,
        "importAllowance": 15,
      },
      "quantity": {
        "available": 5,
        "availableType": "Equal",
        "multiplicity": 1,
        "minimum": 1,
        "maximum": null
      },
      "supplyProbability": {
        "lastUpdateDateTime": "2022-12-19T09:23:41.595Z",
        "rating": 99
      },
      "addInfo": {
        "city": "Минск",
        "isSale": true,
        "comment": "Царапины справа",
        "isReturnAllowed": true,
        "warningText": "Возврат запрещен. Нельзя заказывать масла моторные и тех. жидкости"
      },
      "priority": 1,
      "hash": 123456789,
      "deliveryDateTimes": [
        {
          "deliveryAddressCode": "Д1",
          "deliveryDateTime": "2022-12-19T09:23:41.595Z"
        }
      ],
      "shippingDateTime": "2022-12-19T09:23:41.595Z",
      "isImport": true,
      "isFree": true
    }
  ]
}
]

12. Trademarks (Торговые марки)

12.1 GET /api/v1/trademarks

Получение информации по всем брендам из портфеля компании “Шате-М Плюс”.

Входных параметров нет.

Ответ метода:

{
"name": "KNECHT",
"country": "Германия",
"description": "Торговая марка KNECHT принадлежит концерну...",
"url": "http://www.mahle.com",
"catalogUrl": "http://www.mahle.com",
"extendedWarranty": false
}

12.2 GET /api/v1/trademarks/{tradeMarkName}

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

Метод принимает на вход:

Ответ метода:

{
"name": "KNECHT",
"country": "Германия",
"description": "Торговая марка KNECHT принадлежит концерну...",
"url": "http://www.mahle.com",
"catalogUrl": "http://www.mahle.com",
"extendedWarranty": false
}

Уважаемые клиенты!

Если у вас есть замечания или предложения к документации нашего сервиса, мы готовы рассмотреть их. Присылайте их по адресу andrey.gapanyuk@100soft.by;

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