Создание полигонов доставки

POST /v1/polygon/create

POST/v1/polygon/create

Статус создания DRAFT, но в ответ может сразу прийти статус ACTIVE — значит полигон активирован и готов к использованию. Статус обработки полигона витриной можно получить методом /polygon/list.

Один полигон может иметь множество условий доставки, если так работают условия доставки. В рамках одного полигона в зависимости от ВГХ товара можно настроить разные стоимости доставки — для этого необходимо передать несколько элементов массива в delivery_options. Для каждого элемента настраиваются условия доставки — цена, стоимость, время и тд.

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

Тело запроса

polygons
array
required

Список полигонов для создания. Максимальное количество полигонов в одном запросе — 200.

PolygonCreateItem

Показать свойства

PolygonCreateItem

name
string

Название полигона.

coordinates
number[][][]
required

Координаты полигона в формате GeoJSON (RFC 7946): массив линейных колец (number[][][]).

Линейное кольцо (LinearRing).

Позиция: [lon, lat] или [lon, lat, alt] (RFC 7946 §3.1.1).

delivery_options
array
required

Список цен доставки по объёмному весу.

Опция доставки по диапазону объёмного веса (элемент delivery_options[]). Для Express поддерживается опциональный calculation_mode — discriminator Static/Dynamic Express.

Показать свойства
volume_weight_from
number

Объёмный вес (кг) от: длина (см) × ширина (см) × высота (см) * масса брутто (кг) / 300.

volume_weight_to
number

Объёмный вес (кг) до: длина (см) × ширина (см) × высота (см) * масса брутто (кг) / 300.

price
number
required

Цена доставки, значение умноженное на 100. При calculation_mode = STATIC (или при отсутствии поля) — итоговая стоимость для заказа. При calculation_mode = DYNAMIC — конфигурационный параметр тарифа; итоговая стоимость конкретной доставки определяется ответом POST /v1/polygon/delivery-options/calculate.

currency
string
required

Валюта цены.

RUB: Российский рубль

BYN: Белорусский рубль

KZT: Тенге

EUR: Евро

USD: Доллар США

CNY: Юань

Допустимые значения
RUBBYNKZTEURUSDCNY
vat
string

НДС.

VAT_0: Ставка НДС 0%

VAT_5: Ставка НДС 5%

VAT_7: Ставка НДС 7%

VAT_10: Ставка НДС 10%

VAT_22: Ставка НДС 22%

NO_VAT: Без НДС

Допустимые значения
VAT_0VAT_5VAT_7VAT_10VAT_22NO_VAT
provider_id
string

Идентификатор провайдера доставки.

В будущем необходимо использовать справочник /v1/provider/list.

CDEK: СДЭК

RUSSIAN_POST: Почта России

BOXBERRY: Boxberry

YANDEX: Яндекс Доставка

5POST: 5Post

DPD: DPD

HERMES: Hermes

IML: IML

TOP_DELIVERY: Top Delivery

OZON: Ozon

KSE: КСЕ

STRIZH: Стриж

DL: Деловые Линии

PEK: ПЭК

SBL: Сберлогистика

MVIDEO: М.Видео

  • ELDORADO: Эльдорадо
Допустимые значения
CDEKRUSSIAN_POSTBOXBERRYYANDEX5POSTDPDHERMESIMLTOP_DELIVERYOZONKSESTRIZHDLPEKSBLMVIDEOELDORADO
delivery_time_minutes
integer
required

Минимальное (базовое) ожидаемое время доставки в минутах. Конфигурационный параметр Express SLA в polygon delivery option. При calculation_mode = STATIC (или при отсутствии поля) — используется как итоговый срок доставки. При calculation_mode = DYNAMIC — конкретный интервал доставки для заказа определяется ответом POST /v1/polygon/delivery-options/calculate.

delivery_types
array
required

Типы доставки.

Параметры типа доставки для опции.

Показать свойства
delivery_type
string
required

Тип доставки.

COURIER: доставка курьером

PICKUP_POINT: доставка в пункт выдачи

EXPRESS: срочная курьерская доставка заказа клиенту

Допустимые значения
COURIERPICKUP_POINTEXPRESS
calculation_mode
string

Режим расчёта условий Express-доставки. Поле опционально; располагается на уровне delivery option после delivery_types. При отсутствии — STATIC.

  • DYNAMIC: Dynamic Express: delivery option задаёт поддержку Express и конфигурационные параметры в полигоне; стоимость и сроки конкретной доставки для заказа рассчитываются через POST /v1/polygon/delivery-options/calculate. Business rule: допустимо только при delivery_type = EXPRESS.
Допустимые значения
STATICDYNAMIC
is_return
boolean

true — опция для возвратной логистики; false или нет поля — прямая доставка. На комбинацию delivery_types + диапазон ВГХ — один возвратный бакет.

weight_from
number

Масса брутто (кг) от.

weight_to
number

Масса брутто (кг) до.

order_value_from
integer

Нижняя граница стоимости корзины (умноженная на 100), включительно. Корзина — совокупность всех merchant_order_ids в рамках одного client_order_id; её стоимость — арифметическая сумма стоимостей этих заказов после скидок, без учёта промокодов и бонусов.

order_value_to
integer

Верхняя граница стоимости корзины (умноженная на 100), не включительно. Необязательный параметр: если не задан — верхнего ограничения нет. Корзина и её стоимость определяются так же: все merchant_order_ids одного client_order_id, сумма их стоимостей после скидок, без промокодов и бонусов.

time_slots
array

Доступные интервалы доставки по времени. Конфигурационный параметр delivery option. При calculation_mode = DYNAMIC конкретные интервалы для заказа определяются ответом POST /v1/polygon/delivery-options/calculate.

Интервал времени доставки в течение дня (локальное время).

Показать свойства
from
string

Начало интервала, формат «HH:MM» (например, «10:00»).

to
string

Конец интервала, формат «HH:MM» (например, «12:00»).

trunk_schedule
object

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

Показать свойства
working_schedule
array

Расписание по дням недели; в каждом элементе — day и shipping_cutoff для магистрали.

PolygonWorkingSchedule

Показать свойства

PolygonWorkingSchedule

day
string

День недели.

MONDAY: понедельник

TUESDAY: вторник

WEDNESDAY: среда

THURSDAY: четверг

FRIDAY: пятница

SATURDAY: суббота

SUNDAY: воскресенье

Допустимые значения
MONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAYSUNDAY
shipping_cutoff
string

Время, после которого отсчёт слота доставки начнётся со следующего дня магистральной перевозки. Формат «16:30». Если пустое — не применяется.

individual_schedule
array

Индивидуальное расписание на даты; в каждом элементе — date, shipping_cutoff для магистрали, is_works.

PolygonIndividualSchedule

Показать свойства

PolygonIndividualSchedule

date
string

Дата, формат «YYYY-MM-DD».

shipping_cutoff
string

Время, после которого отсчёт слота доставки начнётся со следующего дня магистральной перевозки. Формат «16:30». Если пустое — не применяется.

is_works
boolean

Признак работы в дату.

delivery_time_minutes_max
integer

Максимальное ожидаемое время доставки в минутах (Express SLA). Конфигурационный параметр; вместе с delivery_time_minutes задаёт интервал N–M минут в polygon delivery option. При calculation_mode = DYNAMIC не заменяет сроки конкретной доставки из POST /v1/polygon/delivery-options/calculate.

order_cutoff
string

Время, после которого данную опцию доставки нельзя заказать. Формат «HH:MM» (например, «17:30»). Конфигурационный параметр Express в polygon delivery option.

additional_options
array

Дополнительные опции доставки в рамках этой delivery option. Поле опционально; отсутствие массива — доп. опций нет.

Известные option_name: is_fitting, fitting_duration_minutes, unloading, first_minutes_free, delivery_time_minutes. Другие имена — по договорённости с витриной.

Универсальная доп. опция. Одна форма на всех уровнях: option_name + value, вложенные опции — тот же объект.

value — boolean, number или string (флаг, минуты, произвольное значение).

Универсальная доп. опция. Одна форма на всех уровнях: option_name + value, вложенные опции — тот же объект.

value — boolean, number или string (флаг, минуты, произвольное значение).

Показать свойства
option_name
string
required

Машинное имя опции. Не закрытый enum.

Известные значения: is_fitting (примерка), fitting_duration_minutes (время на примерку в минутах), unloading (разгрузка), first_minutes_free (первые бесплатные минуты), delivery_time_minutes (время доставки в минутах).

Другие имена — по договорённости с витриной.

value
any
required

Значение опции: boolean, number или string.

options
object[]

Вложенные опции той же формы. Опционально; нет массива, если опция самодостаточна.

Circular Reference to PolygonAdditionalOption

location_id
string

Идентификатор склада.

Успешный ответ

200A successful response.
application/json
object
polygons
array

Список созданных полигонов.

PolygonCreateResult

Показать свойства

PolygonCreateResult

polygon_id
string

Идентификатор созданного полигона.

name
string

Название полигона из запроса на создание.

status
string

Статус полигона.

DRAFT: создан

PENDING: в обработке

ACTIVE: активен

FAILED: не прошёл модерацию

DELETED: удалён

Допустимые значения
DRAFTPENDINGACTIVEFAILEDDELETED
errors
array

Ошибки, из-за которых полигон не был создан или не прошёл модерацию. Коды только из PolygonCreateValidationErrorCode.

Ошибка валидации/бизнеса поля для scope «PolygonCreate». Допустимые field: polygons[].name, coordinates, delivery_options, delivery_options[].additional_options[].option_name, options[].option_name. Для бизнес-правил витрины: code=STOREFRONT_RULE_VIOLATION.

Ошибка валидации/бизнеса поля для scope «PolygonCreate». Допустимые field: polygons[].name, coordinates, delivery_options, delivery_options[].additional_options[].option_name, options[].option_name. Для бизнес-правил витрины: code=STOREFRONT_RULE_VIOLATION.

Показать свойства
field
string
required

Путь к полю. Ожидаемые: polygons[].name, coordinates, delivery_options, delivery_options[].additional_options[].option_name, options[].option_name.

code
string
required

Код ошибки.

REQUIRED: Поле отсутствует или пустое, но обязательно

INVALID_TYPE: Неверный JSON-тип

INVALID_FORMAT: Неверный формат значения

INVALID_ENUM: Значение не из допустимого набора

CONDITIONALLY_REQUIRED: Поле обязательно при выполнении условия

INVALID_TIME: Не формат HH:MM

INVALID_TIME_RANGE: Некорректный диапазон времени

INVALID_DATE: Не формат YYYY-MM-DD

INVALID_DATE_TIME: Не RFC3339 или нет timezone

MIN_VALUE: Значение ниже минимума

MAX_VALUE: Значение выше максимума

NEGATIVE_VALUE: Отрицательное значение недопустимо

INVALID_RANGE: Некорректный диапазон

TOO_MANY_ITEMS: Превышен лимит элементов

INVALID_COORDINATES: Некорректная геометрия / GeoJSON

RING_TOO_SHORT: LinearRing короче 4 позиций

RING_NOT_CLOSED: Кольцо не замкнуто

POSITION_SIZE: Позиция не 2–3 числа

INVALID_LATITUDE: Широта вне диапазона

INVALID_LONGITUDE: Долгота вне диапазона

NOT_FOUND: Сущность не найдена (уточняется полем field)

CONFLICT: Конфликт состояния

STOREFRONT_RULE_VIOLATION: Отклонено бизнес-правилом витрины (детали в message)

Допустимые значения
REQUIREDINVALID_TYPEINVALID_FORMATINVALID_ENUMCONDITIONALLY_REQUIREDINVALID_TIMEINVALID_TIME_RANGEINVALID_DATEINVALID_DATE_TIMEMIN_VALUEMAX_VALUENEGATIVE_VALUEINVALID_RANGETOO_MANY_ITEMSINVALID_COORDINATESRING_TOO_SHORTRING_NOT_CLOSEDPOSITION_SIZEINVALID_LATITUDEINVALID_LONGITUDENOT_FOUNDCONFLICTSTOREFRONT_RULE_VIOLATION
message
string
required

Текст для клиента. Для STOREFRONT_RULE_VIOLATION — описание правила.

Ошибки

400Некорректный запрос
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
401Ошибка авторизации
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
429Превышен лимит запросов
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
500Внутренняя ошибка сервера
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
POST/v1/polygon/create
1curl https://api.example.com/v1/polygon/create \2  --request POST \3  --header 'Content-Type: application/json' \4  --data '{5  "polygons": [6    {7      "name": "string",8      "coordinates": [9        [10          [11            100,12            013          ],14          [15            101,16            017          ],18          [19            101,20            121          ],22          [23            100,24            125          ],26          [27            100,28            029          ]30        ]31      ],32      "delivery_options": [33        {34          "volume_weight_from": 0,35          "volume_weight_to": 0,36          "price": 0,37          "currency": "RUB",38          "vat": "string",39          "provider_id": "string",40          "delivery_time_minutes": 0,41          "delivery_types": [42            {43              "delivery_type": "COURIER"44            }45          ],46          "calculation_mode": "STATIC",47          "is_return": true,48          "weight_from": 0,49          "weight_to": 0,50          "order_value_from": 0,51          "order_value_to": 0,52          "time_slots": [53            {54              "from": "string",55              "to": "string"56            }57          ],58          "trunk_schedule": {59            "working_schedule": [60              {61                "day": "MONDAY",62                "shipping_cutoff": "string"63              }64            ],65            "individual_schedule": [66              {67                "date": "string",68                "shipping_cutoff": "string",69                "is_works": true70              }71            ]72          },73          "delivery_time_minutes_max": 0,74          "order_cutoff": "string",75          "additional_options": [76            {77              "option_name": "is_fitting",78              "value": true,79              "options": [80                {81                  "option_name": "fitting_duration_minutes",82                  "value": 1583                }84              ]85            }86          ]87        }88      ],89      "location_id": "string"90    }91  ]92}'
{
  "polygons": [
    {
      "polygon_id": "string",
      "name": "string",
      "status": "string",
      "errors": [
        {
          "field": "coordinates",
          "code": "INVALID_COORDINATES",
          "message": "Некорректная геометрия полигона"
        }
      ]
    }
  ]
}

A successful response.