API OrderPositionManagement и калькуляция заказа

Request

tenant - (mandatory) - to which tenant/system to connect, e.g. "zegoal"
order_id - (mandatory)
skip_lookup_account - (optional; default false)
position_management
- [0...n]
  - action - (mandatory) - valid values: [add, update, delete]
  - position_id - (mandatory for update/delete)
  - attributes
    - catalog_position_id - (optional)
    - position_type - (optional)
    - product_name - (mandatory for add action if catalog_position_id is not provided)
    - product_code - (optional)
    - quantity - (optional; default 1)
    - unit - (optional)
    - price - (mandatory for add action if catalog_position_id is not provided)
    - description - (optional)
    - implementation_comments - (optional)

Добавляет в заказ одну позицию, при чем указываем только id товара в каталоге. Все данные по типу, цене, количеству будут подтянуты из каталога.

Запрос

{
   "tenant": "orderingtenant885",
   "order_id": 1,
   "position_management": [{
      "action": "add",
      "attributes": {
         "catalog_position_id": 3
      }
   }]
}

CODE

{
   "processing_result":    {
      "text": "Positions are updated.",
      "status": "ok",
      "ctx_id": "Mmt2p3QP:0-PB",
      "code": 0
   },
   "processing_date": "2020-07-03 09:09:16",
   "OrderPositionManagement":    {
      "response":       {
         "tenant": "orderingtenant885",
         "skip_lookup_account": false,
         "order_total": 238.6,
         "order_id": 1,
         "old_order_positions":          [
                        {
               "unit": "шт",
               "quantity": 3,
               "product_name": "position #552",
               "price": 23.1,
               "position_type": "Goods",
               "position_total": 69.3,
               "position_id": 1,
               "order_id": 1,
               "catalog_position_id": 1
            },
                        {
               "unit": "шт",
               "quantity": 3,
               "product_name": "position #340",
               "price": 23.1,
               "position_type": "Goods",
               "position_total": 69.3,
               "position_id": 2,
               "order_id": 1,
               "catalog_position_id": 2
            }
         ],
         "new_order_positions":          [
                        {
               "unit": "шт",
               "quantity": 3,
               "product_name": "position #552",
               "price": 23.1,
               "position_type": "Goods",
               "position_total": 69.3,
               "position_id": 1,
               "order_id": 1,
               "catalog_position_id": 1
            },
                        {
               "unit": "шт",
               "quantity": 3,
               "product_name": "position #340",
               "price": 23.1,
               "position_type": "Goods",
               "position_total": 69.3,
               "position_id": 2,
               "order_id": 1,
               "catalog_position_id": 2
            },
                        {
               "unit": "шт",
               "quantity": 2,
               "product_name": "position #296",
               "price": 50,
               "position_type": "Goods",
               "position_id": 3,
               "order_id": 1,
               "catalog_position_id": 3
            }
         ],
         "TZ": "Europe/Minsk"
      },
      "request":       {
         "tenant": "orderingtenant885",
         "position_management": [         {
            "attributes": {"catalog_position_id": 3},
            "action": "add"
         }],
         "order_id": 1
      },
      "extra_logic": "",
      "enriched_request":       {
         "tenant": "orderingtenant885",
         "skip_lookup_account": false,
         "position_management": [         {
            "attributes": {"catalog_position_id": 3},
            "action": "add"
         }],
         "order_id": 1
      }
   }
}

CODE

Удаление позиции

Запрос


{
   "tenant": "orderingtenant885",
   "order_id": 1,
   "position_management": [{
      "action": "delete",
      "position_id": 3
   }]
}

CODE

{
   "processing_result":    {
      "text": "Positions are updated.",
      "status": "ok",
      "ctx_id": "32fTH2mJ:0-qf",
      "code": 0
   },
   "processing_date": "2020-07-03 09:09:51",
   "OrderPositionManagement":    {
      "response":       {
         "tenant": "orderingtenant885",
         "skip_lookup_account": false,
         "order_total": 138.6,
         "order_id": 1,
         "old_order_positions":          [
                        {
               "unit": "шт",
               "quantity": 3,
               "product_name": "position #552",
               "price": 23.1,
               "position_type": "Goods",
               "position_total": 69.3,
               "position_id": 1,
               "order_id": 1,
               "catalog_position_id": 1
            },
                        {
               "unit": "шт",
               "quantity": 3,
               "product_name": "position #340",
               "price": 23.1,
               "position_type": "Goods",
               "position_total": 69.3,
               "position_id": 2,
               "order_id": 1,
               "catalog_position_id": 2
            },
                        {
               "unit": "UNITS",
               "quantity": 2,
               "product_name": "position #3.1",
               "product_code": "2694",
               "price": 50,
               "position_type": "",
               "position_total": 100,
               "position_id": 3,
               "order_id": 1,
               "implementation_comments": "set up a new water filtering system",
               "description": "pool filter parts",
               "catalog_position_id": 3
            }
         ],
         "new_order_positions":          [
                        {
               "unit": "шт",
               "quantity": 3,
               "product_name": "position #552",
               "price": 23.1,
               "position_type": "Goods",
               "position_total": 69.3,
               "position_id": 1,
               "order_id": 1,
               "catalog_position_id": 1
            },
                        {
               "unit": "шт",
               "quantity": 3,
               "product_name": "position #340",
               "price": 23.1,
               "position_type": "Goods",
               "position_total": 69.3,
               "position_id": 2,
               "order_id": 1,
               "catalog_position_id": 2
            }
         ],
         "TZ": "Europe/Minsk"
      },
      "request":       {
         "tenant": "orderingtenant885",
         "position_management": [         {
            "position_id": 3,
            "action": "delete"
         }],
         "order_id": 1
      },
      "extra_logic": "",
      "enriched_request":       {
         "tenant": "orderingtenant885",
         "skip_lookup_account": false,
         "position_management": [         {
            "position_id": 3,
            "action": "delete"
         }],
         "order_id": 1
      }
   }
}

CODE

Редактирование атрибутов позиции

Запрос

{
   "tenant": "orderingtenant885",
   "order_id": 6,
   "position_management": [{
      "action": "update",
      "position_id": 14,
      "attributes": {
         "product_name": "position #3.1",
         "position_type": "",
         "product_code": "8711",
         "unit": "UNITS",
         "description": "pool filter parts"
         
      }
   }]
}

CODE

{
   "processing_result":    {
      "text": "Positions are updated.",
      "status": "ok",
      "ctx_id": "MFHFLb3g:0-NR",
      "code": 0
   },
   "processing_date": "2020-07-03 09:44:39",
   "OrderPositionManagement":    {
      "response":       {
         "tenant": "orderingtenant885",
         "skip_lookup_account": false,
         "order_total": 238.6,
         "order_id": 6,
         "old_order_positions":          [
                        {
               "unit": "шт",
               "quantity": 3,
               "product_name": "position #552",
               "price": 23.1,
               "position_type": "Goods",
               "position_total": 69.3,
               "position_id": 12,
               "order_id": 6,
               "catalog_position_id": 1
            },
                        {
               "unit": "шт",
               "quantity": 3,
               "product_name": "position #340",
               "price": 23.1,
               "position_type": "Goods",
               "position_total": 69.3,
               "position_id": 13,
               "order_id": 6,
               "catalog_position_id": 2
            },
                        {
               "unit": "шт",
               "quantity": 2,
               "product_name": "position #425",
               "price": 50,
               "position_type": "Goods",
               "position_total": 100,
               "position_id": 14,
               "order_id": 6,
               "catalog_position_id": 7
            }
         ],
         "new_order_positions":          [
                        {
               "unit": "шт",
               "quantity": 3,
               "product_name": "position #552",
               "price": 23.1,
               "position_type": "Goods",
               "position_total": 69.3,
               "position_id": 12,
               "order_id": 6,
               "catalog_position_id": 1
            },
                        {
               "unit": "шт",
               "quantity": 3,
               "product_name": "position #340",
               "price": 23.1,
               "position_type": "Goods",
               "position_total": 69.3,
               "position_id": 13,
               "order_id": 6,
               "catalog_position_id": 2
            },
                        {
               "unit": "UNITS",
               "quantity": 2,
               "product_name": "position #3.1",
               "product_code": "8711",
               "price": 50,
               "position_type": "",
               "position_total": 100,
               "position_id": 14,
               "order_id": 6,
               "description": "pool filter parts",
               "catalog_position_id": 7
            }
         ],
         "TZ": "Europe/Minsk"
      },
      "request":       {
         "tenant": "orderingtenant885",
         "position_management": [         {
            "position_id": 14,
            "attributes":             {
               "unit": "UNITS",
               "product_name": "position #3.1",
               "product_code": "8711",
               "position_type": "",
               "description": "pool filter parts"
            },
            "action": "update"
         }],
         "order_id": 6
      },
      "extra_logic": "",
      "enriched_request":       {
         "tenant": "orderingtenant885",
         "skip_lookup_account": false,
         "position_management": [         {
            "position_id": 14,
            "attributes":             {
               "unit": "UNITS",
               "product_name": "position #3.1",
               "product_code": "8711",
               "position_type": "",
               "description": "pool filter parts"
            },
            "action": "update"
         }],
         "order_id": 6
      }
   }
}

CODE

Если для update не указать какую именно позицию обновлять - получим ошибку.

Запрос

{
   "tenant": "orderingTenant885",
   "order_id": 6,
   "position_management": [{
      "action": "update",
      "attributes": {
         "product_name": "position #3.1",
         "position_type": "",
         "product_code": "8659",
         "unit": "UNITS",
         "description": "pool filter parts"
         
      }
   }]
}

CODE

{
   "processing_result":    {
      "type": "business logic error",
      "text": "position_id is mandatory to provide for delete and update actions.",
      "status": "error",
      "ctx_id": "dFjdBgn8:0-Tj",
      "code": "OPM-002"
   },
   "processing_date": "2020-07-03 09:46:19",
   "OrderPositionManagement":    {
      "response": false,
      "request":       {
         "tenant": "orderingtenant885",
         "position_management": [         {
            "attributes":             {
               "unit": "UNITS",
               "product_name": "position #3.1",
               "product_code": "8659",
               "position_type": "",
               "description": "pool filter parts"
            },
            "action": "update"
         }],
         "order_id": 6
      },
      "enriched_request":       {
         "tenant": "orderingtenant885",
         "skip_lookup_account": false,
         "position_management": [         {
            "attributes":             {
               "unit": "UNITS",
               "product_name": "position #3.1",
               "product_code": "8659",
               "position_type": "",
               "description": "pool filter parts"
            },
            "action": "update"
         }],
         "order_id": 6
      }
   }
}

CODE

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

Логика работы заказа с позициями в заказе

При добавлении позиций в заказ (и при CreateOrder и при добавлении по отдельности) может быть 3 сценария:

Добавление в позиции продукта из каталога.

В этом случае мы ожидаем в атрибутах позиции атрибуты:

catalog_position_id

Атрибуты price и quantity являются не обязательными.

Логика системы:

в значение "quantity", "unit", "Position_type" для новой OrderPosition мы проставляем "default_quantity", "unit", "Position_type" из каталога.
для расчета order_total используем цену из каталога ("price", временное поле до разработки множества цен)

Если на такую позицию прилетел update и в нем добавили новое название - сохраняем его в позицию. Использование "задублированных" значений (позиция заказа - каталог) описана ниже:

Для формирования инвойса используем атрибуты со следующим приоритетом:
- Атрибуты в позиции заказа
- Атрибуты в каталоге

Т.е. если имени позиции (цены, категории) нет в заказе - берем из каталога.

Если update зачищает один из атрибутов (например, price), то мы расцениваем пустое значение ( "" ) как отсутсвие атрибута и берем его из каталога.

2. Добавление позиции без каталога

В этом случае в запросе может быть не указан catalog_position_id, но тогда обязательными снова стают атрибуты: product_name, quantity, price.

3. Гибридный вариант с позицией из каталога и перезаписанными атрибутами:

Мы позволяем создавать позицию, в которой есть catalog_position_id, но при этом передают тут же перезаписанные атрибуты (в том числе product_name, quantity, price). В этом случае из каталога будут "дотаскиваться" дополнительные атрибуты для репортов (например, категория), но в калькуляции заказа и в инвойс атрибуты будут выбираться только перезаписанные из заказа.