Микросервис promo-orchestration

В статье описываются функции, логика работы, конфигурация и методы микросервиса promo-orchestration.

Микросервис promo-orchestration предоставляет функциональность по заведению и применению скидок.

Доступ к сервису предоставляется по запросу.

Логика работы Copy-icon

В работе микросервиса участвуют следующие сущности:

  • Скидка (Promo) - содержит информацию о скидке (id, название, метод применения, клиенты, на которых распространяется скидка, статус, дата начала и окончания действия и др.)
  • Настройка (Setting) - содержит данные о настройке скидки (ключ, значение, описание)
  • Промо продукт (PromoProduct) - содержит информацию о продукте/варианте продукта и его скидке (артикул продукта/варианта продукта, количество продукта в штуках, цена за 1 штуку, цена со скидкой за единицу товара, стоимость общего количества товара с учетом скидки, величина скидки на весь товар и др.)

Аутентификация Copy-icon

При обращении к микросервису promo-orchestration через API:

  • в запросах на создание, редактирование или удаление скидок аутентификация не требуется
  • в запросах на создание, редактирование или удаление настроек (см. раздел "Работа с настройками") (в том числе лимита скидок) требуется аутентификация

Service context path Copy-icon

/api/promo-orchestration/

Настройки и параметры конфигурации Copy-icon

Параметры конфигурации указываются в Vault.

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

По умолчанию

{
  "env": {

    "JAVA_XMS": "64m",
    "JAVA_XMX": "128m",
    "LOGGING_LEVEL": "уровень_логирования",
    "SERVER_PORT": "8458"

  }
}
Copy-icon
Указываемые на каждом отдельном стенде

// пример взят с тестового стенда


{
  "env": {
    "CATALOG_URL": "путь_к_сервису_catalog",

    "OAUTH_ECOM_CLIENT_ID": "токен_приложения_ECOM_OAuth",
    "OAUTH_ECOM_ISSUER_URI": "url_ECOM_OAuth",
    "OAUTH_ZITADEL_CLIENT_ID": "токен_приложения_Zitadel",
    "OAUTH_ZITADEL_ISSUER_URI": "url_Zitadel",
    "PROMO_URL": "путь_к_сервису"
  }
}
Copy-icon

Методы микросервиса Copy-icon

Работа с настройками Copy-icon

  • Создание настройки - POST запрос, /v1/settings
Request body sample

{
  "key": "LIMIT",
  "value": "70.0",
  "description": "Limit of the maximum promotion percentage"
}
Copy-icon
Response codes
  • 201 - операция прошла успешно
  • 409 - настройка уже существует
  • 400 - не удалось создать настройку
  • Получение настройки по ее ключу - GET запрос, /v1/settings/{key}
Request parameters

key - path-параметр, обязательный: уникальный идентификатор настройки
Copy-icon
Response sample

{
    "key": "LIMIT",
    "value": "90",
    "description": null
}
Copy-icon
Response codes
  • 200 - операция прошла успешно, получена настройка
  • 404 - настройка не найдена
  • Редактирование настройки по ее ключу - PATCH запрос, /v1/settings/{key}
Request parameters

key - path-параметр, обязательный: уникальный идентификатор настройки
Copy-icon
Request body sample

{
  "key": "LIMIT",
  "value": "70.0",
  "description": "Limit of the maximum promotion percentage"
}
Copy-icon
Response sample

{
  "key": "LIMIT",
  "value": "70.0",
  "description": "Limit of the maximum promotion percentage"
}
Copy-icon
Response codes
  • 200 - операция прошла успешно, настройка отредактирована
  • 400 - настройка не отредактирована
  • Удаление настройки по ее ключу - DELETE запрос, /v1/settings/{key}
Request parameters

key - path-параметр, обязательный: уникальный идентификатор настройки
Copy-icon
Response sample

Отсутствует. В ответе приходит только код операции, например, 204.

Response codes
  • 204 - операция выполнена успешно, настройка удалена
  • 404 - ошибка, настройка не найдена
  • Отображение скидки по id с массивом продуктов, к которым она применена -- GET запрос, /v2/promos/{id}
Request parameters

id - path-параметр, обязательный: уникальный идентификатор скидки
Copy-icon
Response sample

{
  "id": "4b7e6hjA-107b-476b-816a-51hh256a30d1",
  "name": "Bestsellers 7%",
  "applying": "AUTO",
  "entity": "PRODUCT",
  "userIds": [
    "201539523727877663",
    "202010411006977567"
  ],
  "combination": "SUMMARIZE",
  "startDate": "17-08-2023 00:00:00",
  "endDate": "31-12-2023 23:59:59",
  "articleIds": [
    "1000009",
    "1000238DC"
  ],
  "discountType": "PERCENT",
  "discount": 4.99,
  "products": [
    {
      "id": "string",
      "externalId": "string",
      "name": "string",
      "title": "string",
      "description": "string",
      "assets": [
        {
          "id": "string",
          "media": {
            "url": "string",
            "absoluteUrl": "string",
            "name": "string",
            "type": "string",
            "size": 0,
            "resolution": "string",
            "createdDate": "2024-02-01T13:45:26.174Z"
          },
          "title": "string",
          "altAttr": "string",
          "description": "string",
          "sign": "string",
          "tags": [
            "string"
          ]
        }
      ],
      "features": [
        {
          "featureId": "string",
          "name": "string",
          "indexable": true,
          "value": "string"
        }
      ],
      "category": {
        "id": "cat00001",
        "name": "Category Name",
        "title": "Title",
        "url": "/sport",
        "media": {
          "id": "string",
          "media": {
            "url": "string",
            "absoluteUrl": "string",
            "name": "string",
            "type": "string",
            "size": 0,
            "resolution": "string",
            "createdDate": "2024-02-01T13:45:26.174Z"
          },
          "title": "string",
          "altAttr": "string",
          "description": "string",
          "sign": "string",
          "tags": [
            "string"
          ]
        },
        "features": [
          {
            "id": "1111111",
            "name": "Material",
            "values": [
              "string"
            ],
            "createdDate": "2024-02-01T13:45:26.174Z"
          }
        ],
        "type": "WITH_PRODUCTS",
        "parentCategory": "string",
        "level": 1,
        "order": 1
      },
      "status": 0,
      "variants": [
        {
          "id": "string",
          "externalId": "string",
          "barcode": "string",
          "nomenclature": "string",
          "productId": "string",
          "name": "string",
          "description": "string",
          "assets": [
            {
              "id": "string",
              "media": {
                "url": "string",
                "absoluteUrl": "string",
                "name": "string",
                "type": "string",
                "size": 0,
                "resolution": "string",
                "createdDate": "2024-02-01T13:45:26.174Z"
              },
              "title": "string",
              "altAttr": "string",
              "description": "string",
              "sign": "string",
              "tags": [
                "string"
              ]
            }
          ],
          "attributes": [
            {
              "featureId": "string",
              "name": "string",
              "indexable": true,
              "value": "string"
            }
          ],
          "status": 0
        }
      ]
    }
  ]
}
Copy-icon
Response codes

200 - операция прошла успешно, скидка отображена (вместе с массивом продуктов, к которым она применена)

  • Получение страницы скидок с возможностью фильтрации - GET запрос, /v1/promos/page
Request parameters

page - query-параметр: номер страницы
size - query-параметр: размер страницы
sort - query-параметр: сортировка скидок
searchTerm - query-параметр: поисковый запрос пользователя
name - query-параметр: обозначение скидки
applyingSet - query-параметр: метод скидки
combinationSet - query-параметр: комбинации скидки
statusSet - query-параметр: статус скидки
discountFirstValue - query-параметр: первый числовой параметр фильтра "Скидка"
discountFirstOperator - query-параметр: первый числовой оператор фильтра "Скидка" (например, "меньше")
discountFilterConnectiveType - query-параметр: тип соединения числовых параметров фильтра "Скидка" (например, "AND" или "OR")
discountSecondValue - query-параметр: второй числовой параметр фильтра "Скидка"
discountSecondOperator - query-параметр: второй числовой оператор фильтра "Скидка" (например, "больше")
productArticleId - query-параметр: артикул продукта
variantsArticleId - query-параметр: артикул варианта продукта
userId - query-параметр: идентификатор клиента
productName - query-параметр: название продукта
variantsName - query-параметр: название варианта продукта
startDate - query-параметр: дата начала действия скидки
endDate - query-параметр: дата окончания действия скидки
Copy-icon
Response sample

{
  "content": [
    {
      "id": "93929a1e-033c-4716-8cda-496e027a1a6c",
      "name": "filter test",
      "applying": "AUTO",
      "entity": "PRODUCT",
      "userIds": [],
      "combination": "SUMMARIZE",
      "startDate": "03-12-2023 21:00:00",
      "endDate": null,
      "status": "ACTIVE",
      "articleIds": [
        "1001523DC",
        "1001627DC",
        "1014580DC",
        "1014586DC",
        "1014587DC",
        "1014588DC"
      ],
      "discountType": "PERCENT",
      "discount": 71
    },
    {
      "id": "e6aefb70-a231-41b7-966c-7d48d3c5cf79",
      "name": null,
      "applying": "AUTO",
      "entity": "PRODUCT",
      "userIds": [],
      "combination": "EXCLUDE",
      "startDate": null,
      "endDate": null,
      "status": "ACTIVE",
      "articleIds": [
        "1009029DC"
      ],
      "discountType": "PERCENT",
      "discount": 44
    },
    {
      "id": "cea19eb6-58d0-4014-912c-0ac1ade70ddc",
      "name": null,
      "applying": "AUTO",
      "entity": "PRODUCT",
      "userIds": [],
      "combination": "EXCLUDE",
      "startDate": null,
      "endDate": null,
      "status": "ACTIVE",
      "articleIds": [
        "1014218DC"
      ],
      "discountType": "PERCENT",
      "discount": 43
    },
    {
      "id": "1766d225-00c8-4853-b9cb-ea20df785ffd",
      "name": null,
      "applying": "AUTO",
      "entity": "PRODUCT",
      "userIds": [],
      "combination": "EXCLUDE",
      "startDate": "23-04-2024 21:00:00",
      "endDate": null,
      "status": "ACTIVE",
      "articleIds": [
        "1014218DC"
      ],
      "discountType": "PERCENT",
      "discount": 20
    }
  ],
  "number": 0,
  "size": 4,
  "totalElements": 25,
  "pageable": {
    "sort": {
      "unsorted": true,
      "sorted": false,
      "empty": true
    },
    "pageNumber": 0,
    "pageSize": 4,
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "last": false,
  "totalPages": 7,
  "sort": {
    "unsorted": true,
    "sorted": false,
    "empty": true
  },
  "first": true,
  "numberOfElements": 4,
  "empty": false
}
Copy-icon
Response codes

200 - операция выполнена успешно, получена отфильтрованная страница со скидками

  • Получение отфильтрованного списка скидок - GET запрос, /v1/promos/list
Request parameters

searchTerm - query-параметр: поисковый запрос пользователя
name - query-параметр: обозначение скидки
applyingSet - query-параметр: метод скидки
combinationSet - query-параметр: комбинации скидки
statusSet - query-параметр: статус скидки
discountFirstValue - query-параметр: первый числовой параметр фильтра "Скидка"
discountFirstOperator - query-параметр: первый числовой оператор фильтра "Скидка" (например, "меньше")
discountFilterConnectiveType - query-параметр: тип соединения числовых параметров фильтра "Скидка" (например, "AND" или "OR")
discountSecondValue - query-параметр: второй числовой параметр фильтра "Скидка"
discountSecondOperator - query-параметр: второй числовой оператор фильтра "Скидка" (например, "больше")
productArticleId - query-параметр: артикул продукта
variantsArticleId - query-параметр: артикул варианта продукта
userId - query-параметр: идентификатор клиента
productName - query-параметр: название продукта
variantsName - query-параметр: название варианта продукта
startDate - query-параметр: дата начала действия скидки
endDate - query-параметр: дата окончания действия скидки
Copy-icon
Response sample

{
  "content": [
    {
      "id": "93929a1e-033c-4716-8cda-496e027a1a6c",
      "name": "filter test",
      "applying": "AUTO",
      "entity": "PRODUCT",
      "userIds": [],
      "combination": "SUMMARIZE",
      "startDate": "03-12-2023 21:00:00",
      "endDate": null,
      "status": "ACTIVE",
      "articleIds": [
        "1001523DC",
        "1001627DC",
        "1014580DC",
        "1014586DC",
        "1014587DC",
        "1014588DC"
      ],
      "discountType": "PERCENT",
      "discount": 71
    },
    {
      "id": "e6aefb70-a231-41b7-966c-7d48d3c5cf79",
      "name": null,
      "applying": "AUTO",
      "entity": "PRODUCT",
      "userIds": [],
      "combination": "EXCLUDE",
      "startDate": null,
      "endDate": null,
      "status": "ACTIVE",
      "articleIds": [
        "1009029DC"
      ],
      "discountType": "PERCENT",
      "discount": 44
    },
    {
      "id": "cea19eb6-58d0-4014-912c-0ac1ade70ddc",
      "name": null,
      "applying": "AUTO",
      "entity": "PRODUCT",
      "userIds": [],
      "combination": "EXCLUDE",
      "startDate": null,
      "endDate": null,
      "status": "ACTIVE",
      "articleIds": [
        "1014218DC"
      ],
      "discountType": "PERCENT",
      "discount": 43
    },
    {
      "id": "1766d225-00c8-4853-b9cb-ea20df785ffd",
      "name": null,
      "applying": "AUTO",
      "entity": "PRODUCT",
      "userIds": [],
      "combination": "EXCLUDE",
      "startDate": "23-04-2024 21:00:00",
      "endDate": null,
      "status": "ACTIVE",
      "articleIds": [
        "1014218DC"
      ],
      "discountType": "PERCENT",
      "discount": 20
    }
  ]
Copy-icon
Response codes

200 - операция выполнена успешно, получен отфильтрованный список скидок

  • Создание скидки - POST запрос, /v1/promos
Request body sample

{
  "name": "Bestsellers 7%",
  "applying": "AUTO",
  "entity": "PRODUCT",
  "userIds": [
    "201539523727877663",
    "202010411006977567"
  ],
  "combination": "SUMMARIZE",
  "startDate": "17-08-2023 00:00:00",
  "endDate": "31-12-2023 23:59:59",
  "articleIds": [
    "1000009",
    "1000238DC"
  ],
  "discountType": "PERCENT",
  "discount": 4.99
}
Copy-icon
Response sample

{
  "id": "4b7e6hjA-107b-476b-816a-51hh256a30d1",
  "name": "Bestsellers 7%",
  "applying": "AUTO",
  "entity": "PRODUCT",
  "userIds": [
    "201539523727877663",
    "202010411006977567"
  ],
  "combination": "SUMMARIZE",
  "startDate": "17-08-2023 00:00:00",
  "endDate": "31-12-2023 23:59:59",
  "articleIds": [
    "1000009",
    "1000238DC"
  ],
  "discountType": "PERCENT",
  "discount": 4.99
}
Copy-icon
Response codes

201 - операция выполнена успешно, скидка создана

  • Редактирование скидки - PATCH запрос, /v1/promos/{id}
Request parameters

id - path-параметр, обязательный: уникальный идентификатор скидки
Copy-icon
Request body sample

{
  "id": "4b7e6hjA-107b-476b-816a-51hh256a30d1",
  "name": "Bestsellers 7%",
  "applying": "AUTO",
  "entity": "PRODUCT",
  "userIds": [
    "201539523727877663",
    "202010411006977567"
  ],
  "combination": "SUMMARIZE",
  "startDate": "17-08-2023 00:00:00",
  "endDate": "31-12-2023 23:59:59",
  "articleIds": [
    "1000009",
    "1000238DC"
  ],
  "discountType": "PERCENT",
  "discount": 4.99
}
Copy-icon
Response sample

{
  "id": "4b7e6hjA-107b-476b-816a-51hh256a30d1",
  "name": "Bestsellers 7%",
  "applying": "AUTO",
  "entity": "PRODUCT",
  "userIds": [
    "201539523727877663",
    "202010411006977567"
  ],
  "combination": "SUMMARIZE",
  "startDate": "17-08-2023 00:00:00",
  "endDate": "31-12-2023 23:59:59",
  "articleIds": [
    "1000009",
    "1000238DC"
  ],
  "discountType": "PERCENT",
  "discount": 4.99
}
Copy-icon
Response codes

200 - операция выполнена успешно, скидка обновлена

  • Удаление скидки - DELETE запрос, /v1/promos/{id}
Request parameters

id - path-параметр, обязательный: уникальный идентификатор скидки
Copy-icon
Response sample

Отсутствует. В ответе приходит только код операции, например, 204.

Response codes
  • 204 - операция выполнена успешно, скидка удалена
  • 404 - ошибка, скидка не найдена

Работа с калькулятором скидок Copy-icon

  • Расчет скидки для продукта (варианта) - POST запрос,/v1/promo-calculate/product
Request body sample

{
  "articleId": "article1", // id товара
  "quantity": 10, // количество товара
  "unitPrice": 10, // цена на одну единицу товара
  "price": 100, // стоимость всего количества товара
  "currencyId": "b7843131-85ae-454b-a116-794b64435eca" // id валюты, в которой исчисляется цена
}
Copy-icon
Response sample

{
  "articleId": "article1",
  "quantity": 10,
  "unitPrice": 10,
  "discountUnitPrice": 8, // цена со скидкой на единицу товара
  "price": 100,
  "discountPrice": 80, // стоимость всего количества товара с учетом скидки
  "discountSum": 20, // величина скидки на весь товар
  "currencyId": "b7843131-85ae-454b-a116-794b64435eca"
}
Copy-icon
Response codes

200 - операция выполнена успешно, скидка для продукта/варианта продукта рассчитана

Связанные статьи Copy-icon


Микросервисы