Документация для версии v75

Предварительный расчет заказа

Описание

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

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

подсказка

Метод не создает заказ в системе, а возвращает расчетное состояние заказа с примененными правилами маркета и лояльности. Для создания рассчитанного заказа после успешного выполнения preorder используйте метод preorder_commit.

URL-адрес

Метод: POST

https://example.com/api/v1.1/market/orders/preorder

Параметры запроса

Параметр	Тип	Пример	Обязательный	Описание
token	string	"abcdefghijklmnqrstuvwxyz"	Да	API-токен
external_id	string	"12"	Да	Внешний идентификатор заказа
matching	string	"email" "phone" "profile_id" "custom"	Да	Способ поиска профиля участника программы лояльности
email	string	"example@example.com"	Если `matching = email`	Email участника
phone	string	"+79000000000"	Если `matching = phone`	Телефон участника
profile_id	string	"696e304f547840a7286619e0"	Если `matching = profile_id`	Идентификатор профиля
data	JSON object	{ "endpoint": "site", "status": "new", "currency": "RUB", "total_price": "139999.00", "lines": [...] }	Да	Объект `data` содержит данные заказа

подсказка

Поле lines обязательно и должно содержать как минимум одну позицию заказа.

Объект data

Параметр	Тип	Пример	Обязательный	Описание
endpoint	string	"bot", "website"	Да	Источник заказа (точка контакта). Должен быть настроен в Маркете
status	string	"new", "confirmed", "paid"	Да	Статус заказа. Используются статусы, настроенные в платформе
currency	string	"RUB", "USD", "EUR"	Да	Валюта заказа (трехбуквенный код ISO)
total_price	string	"2500.00"	Да	Общая стоимость заказа до применения скидок
final_total_price	string	"2150.00"	Да	Итоговая стоимость заказа после применения всех скидок
delivery_cost	string	"300.00"	Нет	Стоимость доставки
create_time	string (ISO 8601)	"2026-02-18T13:01:05.141Z"	Нет	Дата и время создания заказа. Если не передано, используется текущее время сервера
region	string	"region_moscow"	Нет	Идентификатор региона для применения региональных цен и акций
lines	array	См. ниже раздел "Массив lines"	Да	Массив позиций заказа. Должен содержать минимум 1 элемент
promocodes	array	См. ниже раздел "Массив promocodes"	Нет	Массив промокодов, примененных к заказу
applied_promotions	array	См. ниже раздел "Массив applied_promotions"	Нет	Промоакции, примененные к данному заказу.
redeem_points	array	См. ниже раздел "Массив redeem_points"	Да, если указано `type="redeem_points"` в `applied_promotions`	Массив списаний баллов по типам валют
custom_fields	object	`{ "field1": "value1", "field2": "value2" }`	Нет	Дополнительные поля заказа
tags	array	`[ "summer_sale", "first_order" ]`	Нет	Теги для маркировки заказа

Массив lines

Массив содержит информацию о позициях заказа. Должен содержать минимум 1 позицию.

Каждая позиция вынесена в отдельный объект внутри массива со следующими параметрами:

Параметр	Тип	Пример	Обязательный	Описание
external_id	string	"line_1"	Да	Внешний идентификатор позиции в системе клиента
product	string	"iphone17pmb256"	Да*	Идентификатор продукта
sku	string	"IPHONE17-256-BLACK"	Да*	Идентификатор SKU
line_number	integer	1	Нет	Порядковый номер линии в заказе
count	integer	1	Да	Количество единиц товара
base_price_per_item	string	"139999.00"	Да	Базовая цена за единицу товара
min_price_per_item	string	"130000.00"	Нет	Минимально допустимая цена за единицу товара
final_price_per_item	string	"139500.00"	Да	Финальная цена за единицу после применения всех скидок
status	string	"new"	Нет	Статус позиции заказа
custom_fields	object	{"color": "black", "size": "XL"}	Нет	Дополнительные поля позиции
applied_promotions	array	См. ниже раздел "Массив applied_promotions"	Нет	Промоакции, примененные к данной позиции.

* — обязателен один из параметров: product или sku

Массив promocodes

Массив содержит объекты с информацией о промокодах.

Полное описание структуры промокода можно найти в этой статье.

Параметр	Тип	Пример	Обязательный	Описание
code	string	"SUMMER20"	Да	Код промокода
pool_id	integer	42	Да	Идентификатор пула промокодов

Массив redeem_points

Массив с инфомацией о списании баллов лояльности. Каждый объект описывает отдельное списание.

Полное описание структуры списания баллов можно найти в этой статье.

Параметр	Тип	Пример	Обязательный	Описание
points_currency_iid	integer	1	Да*	Внутренний идентификатор типа баллов
points_currency_eid	string	"bonus1"	Да*	Внешний идентификатор типа баллов
name	string	"Бонусные баллы"	Нет	Название типа баллов
amount	integer	499	Да	Количество баллов для списания

* — обязателен один из параметров: points_currency_iid или points_currency_eid

Массив applied_promotions

подсказка

Массив applied_promotions может содержаться как в объекте data, так и в массиве lines внутри этого объекта. В первом случае в массиве будут переданы промоакции, применяемые к продуктам, во втором — акции, применяемые к заказу.

Массив применяемых к заказу промоакций. Каждый объект массива описывает отдельную промоакцию.

Параметр	Тип	Пример	Обязательный	Описание
type	string	"discount", "accrue_points", "redeem_points", "code_issue", "message"	Да	Тип промоакции
promotion	object	`"promotion": { "external_id": "promo_1", "name": "Summer Sale" }`	Да	Объект с идентификатором и названием промоакции
amount	string	"150.00"	Да, если `type` равен `discount`,`accrue_points` или `redeem_points`	Размер скидки или количество баллов
points_info	object	`"points_info": { "points_currency_iid": 1, "points_currency_eid": "bonus1", "name": "Бонусные баллы", "amount": "50" }`	Да, если `type` равен `accrue_points` или `redeem_points`	Объект с информацией о баллах

Структура объекта points_info выглядит следующим образом:

Параметр	Тип	Пример	Обязательный	Описание
points_currency_iid	integer	1	Да*	Внутренний идентификатор типа баллов
points_currency_eid	string	"bonus1"	Да*	Внешний идентификатор типа баллов
name	string	"Бонусные баллы"	Нет	Название типа баллов
amount	string	"6999"	Да	Количество баллов
expiration_date	string (ISO 8601)	"2027-02-18T00:00:00.000Z"	Нет	Дата сгорания начисленных баллов

* — обязателен один из параметров: points_currency_iid или points_currency_eid

Пример запроса

JSON
XML

{
  "token": "abcdefghijklmnqrstuvwxyz",
  "external_id": "12",
  "matching": "email",
  "email": "example@example.com",
  "data": {
    "endpoint": "site",
    "status": "new",
    "delivery_cost": "0.00",
    "total_price": "139999.00",
    "currency": "RUB",
    "redeem_points": [
      {
        "points_currency_iid": 1,
        "amount": 499
      }
    ],
    "lines": [
      {
        "external_id": "line___ASTGRf",
        "product": "iphone17pmb256",
        "base_price_per_item": "139999.00",
        "min_price_per_item": "0.00",
        "final_price_per_item": "139999.00",
        "count": 1,
        "custom_fields": {},
        "currency": "RUB"
      }
    ]
  }
}

<xml>
  <token>abcdefghijklmnqrstuvwxyz</token>
  <external_id>12</external_id>
  <matching>email</matching>
  <email>example@example.com</email>
  <data>
    <endpoint>site</endpoint>
    <status>new</status>
    <delivery_cost>0.00</delivery_cost>
    <total_price>139999.00</total_price>
    <currency>RUB</currency>
    <redeem_points>
      <points_currency_iid>1</points_currency_iid>
      <amount>499</amount>
    </redeem_points>
    <lines>
      <external_id>line___ASTGRf</external_id>
      <product>iphone17pmb256</product>
      <base_price_per_item>139999.00</base_price_per_item>
      <min_price_per_item>0.00</min_price_per_item>
      <final_price_per_item>139999.00</final_price_per_item>
      <count>1</count>
      <currency>RUB</currency>
    </lines>
  </data>
</xml>

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

JSON
XML

{
    "data": {
        "profile": {
            "profile_id": "696e304f547840a7286619e0"
        },
        "order": {
            "processing_target": "calculated",
            "total_price": "139999.00",
            "final_total_price": "139500.00",
            "delivery_cost": "0.00",
            "currency": "RUB",
            "lines": [
                {
                    "external_id": "line___ASTGRf",
                    "line_number": 0,
                    "count": 1,
                    "product": "iphone17pmb256",
                    "base_price_per_item": "139999.00",
                    "min_price_per_item": "0.00",
                    "final_price_per_item": "139500.00",
                    "custom_fields": {},
                    "applied_promotions": [
                        {
                            "type": "accrue_points",
                            "promotion": {
                                "external_id": "bonus",
                                "name": "Начисление баллов"
                            },
                            "points_info": {
                                "points_currency_iid": 1,
                                "points_currency_eid": "bonus1",
                                "name": "Основной балл ",
                                "amount": "6999"
                            }
                        },
                        {
                            "type": "redeem_points",
                            "promotion": {
                                "external_id": "bonus",
                                "name": "Списание баллов"
                            },
                            "points_info": {
                                "points_currency_iid": 1,
                                "points_currency_eid": "bonus1",
                                "name": "Основной балл ",
                                "amount": "499"
                            }
                        }
                    ]
                }
            ],
            "custom_fields": {},
            "applied_promotions": [],
            "points_info": [
                {
                    "points_currency_iid": 1,
                    "points_currency_eid": "bonus1",
                    "name": "Основной балл ",
                    "status": "success",
                    "active_amount_for_current_order": "20999",
                    "accrue_points_amount_for_current_order": "6999",
                    "redeemed_points_amount_for_current_order": "499"
                }
            ],
            "promocodes_info": []
        }
    },
    "error": 0,
    "error_text": "Successful operation"
}

<xml>
  <data>
    <profile>
      <profile_id>696e304f547840a7286619e0</profile_id>
    </profile>
    <order>
      <processing_target>calculated</processing_target>
      <total_price>139999.00</total_price>
      <final_total_price>139500.00</final_total_price>
      <delivery_cost>0.00</delivery_cost>
      <currency>RUB</currency>
      <lines>
        <external_id>line___ASTGRf</external_id>
        <line_number>0</line_number>
        <count>1</count>
        <product>iphone17pmb256</product>
        <base_price_per_item>139999.00</base_price_per_item>
        <min_price_per_item>0.00</min_price_per_item>
        <final_price_per_item>139500.00</final_price_per_item>
        <custom_fields/>
        <applied_promotions>
          <type>accrue_points</type>
          <promotion>
            <external_id>bonus</external_id>
            <name>Начисление баллов</name>
          </promotion>
          <points_info>
            <points_currency_iid>1</points_currency_iid>
            <points_currency_eid>bonus1</points_currency_eid>
            <name>Основной балл </name>
            <amount>6999</amount>
          </points_info>
        </applied_promotions>
        <applied_promotions>
          <type>redeem_points</type>
          <promotion>
            <external_id>bonus</external_id>
            <name>Начисление баллов</name>
          </promotion>
          <points_info>
            <points_currency_iid>1</points_currency_iid>
            <points_currency_eid>bonus1</points_currency_eid>
            <name>Основной балл </name>
            <amount>499</amount>
          </points_info>
        </applied_promotions>
      </lines>
      <custom_fields/>
      <applied_promotions/>
      <points_info>
        <points_currency_iid>1</points_currency_iid>
        <points_currency_eid>bonus1</points_currency_eid>
        <name>Основной балл </name>
        <status>success</status>
        <active_amount_for_current_order>20999</active_amount_for_current_order>
        <accrue_points_amount_for_current_order>6999</accrue_points_amount_for_current_order>
        <redeemed_points_amount_for_current_order>499</redeemed_points_amount_for_current_order>
      </points_info>
      <promocodes_info/>
    </order>
  </data>
  <error>0</error>
  <error_text>Successful operation</error_text>
</xml>

Возвращаемые параметры

Параметр	Тип	Описание
data	object	Данные результата расчета
error	int	Код ошибки
error_text	string	Текст ошибки

Объект data содержит следующую структуру.

Параметр	Тип	Описание
profile	object	Профиль участника. Содержит идентификатор профиля
order	object	Рассчитанный заказ. Подробнее

Описание​

URL-адрес​

Параметры запроса​

Объект data​

Массив lines​

Массив promocodes​

Массив redeem_points​

Массив applied_promotions​

Пример запроса​

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

Возвращаемые параметры​

Описание

URL-адрес

Параметры запроса

Объект data

Массив lines

Массив promocodes

Массив redeem_points

Массив applied_promotions

Пример запроса

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

Возвращаемые параметры