Создание локаций

POST /v1/location/create

POST/v1/location/create

Создаёт локации в системе Витрины с указанием их типа: склад, точка выдачи или пункт самовывоза — для различных сценариев доставки. При этом одна локация может сочетать несколько свойств одновременно.

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

Создание и активация локации на стороне Витрины выполняются асинхронно. В ответе метода возвращаются location_id и текущий статус создания, который в дальнейшем можно отслеживать с помощью метода location/list.

Тело запроса

locations

array

required

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

LocationCreateItem

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

LocationCreateItem

merchant_location_id

string

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

location_types

array

required

Типы локации. Набор задаётся при создании и определяет допустимую схему данных и валидацию полей.

CLICK_AND_COLLECT одновременно является складом и пунктом вывоза — не нужно дублировать её отдельным складом.

WAREHOUSE: склад

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

CLICK_AND_COLLECT: пункт самовывоза (Click & Collect)

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

WAREHOUSEPICKUP_POINTCLICK_AND_COLLECT

name

string

required

Название локации.

address_tail

string

Адрес в текстовом формате. Формат: «196653, Россия, г. Санкт-Петербург, г. Колпино, ул. Октябрьская, д. 77/27, подъезд 1, этаж 3, кв. 12».

comment

string

Комментарий к доставке или адресу.

latitude

number

required

Широта.

longitude

number

required

Долгота.

provider_id

string

Принадлежность точки к сети мерчанта/партнёра. Используется витриной для отображения бренда точки выдачи/самовывоза покупателю.

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: М.Видео

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

CDEKRUSSIAN_POSTBOXBERRYYANDEX5POSTDPDHERMESIMLTOP_DELIVERYOZONKSESTRIZHDLPEKSBLMVIDEO

provider_location_id

string

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

pickup_point_type

string

Тип пункта выдачи.

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

POSTAMAT: постамат

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

PICKUP_POINTPOSTAMAT

payment_methods

array

Доступные способы оплаты на точке.

ALREADY_PAID: предоплаченные заказы

CARD: оплата картой

CASH: оплата наличными

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

ALREADY_PAIDCARDCASH

storage_period_days

integer

Число дней хранения заказа на точке.

limits

object

required

Предельные габариты и вес заказа для точки (ВГХ, см и кг).

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

length

number

required

Максимальная длина заказа, см.

width

number

required

Максимальная ширина заказа, см.

height

number

required

Максимальная высота заказа, см.

weight

number

required

Максимальный вес заказа, кг.

instruction

string

Инструкция как добраться для отображения на витрине.

pickup_services

array

Дополнительные услуги пункта выдачи.

FITTING: возможна примерка

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

FITTING

working_schedule

array

required

Расписание работы.

LocationCreateRequestWorkingSchedule

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

LocationCreateRequestWorkingSchedule

day

string

required

День недели.

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

TUESDAY: вторник

WEDNESDAY: среда

THURSDAY: четверг

FRIDAY: пятница

SATURDAY: суббота

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

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

MONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAYSUNDAY

schedule

object

required

Расписание на день.

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

time_start

string

required

Время начала, формат «00:00».

time_end

string

required

Время окончания, формат «00:00».

break

string

Перерыв, формат «13:00–14:00».

shipping_cutoff

string

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

individual_schedule

array

Индивидуальное расписание на определённые даты. К примеру, праздничные дни (при отличии от working_schedule).

LocationCreateRequestIndividualSchedule

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

LocationCreateRequestIndividualSchedule

date

string

required

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

schedule

object

required

Расписание на дату.

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

time_start

string

required

Время начала, формат «00:00».

time_end

string

required

Время окончания, формат «00:00».

break

string

Перерыв, формат «13:00–14:00».

shipping_cutoff

string

is_works

boolean

required

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

is_accepts_returns

boolean

required

Признак приёма возвратов.

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

200A successful response.

application/json

object

locations

array

Результаты по каждой локации из тела запроса create (порядок соответствует массиву locations в запросе).

Итог по одной локации из batch create: location_id — id в системе витрины (пустая строка, если не создано); name — название из запроса; errors — ошибки валидации по полям, при успехе []. Поле issue в ответе create не передаётся.

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

location_id

string

Идентификатор локации в системе витрины; пустая строка, если операция для этой позиции не выполнена.

merchant_location_id

string

Идентификатор локации продавца.

name

string

required

Название локации из запроса.

status

string

required

Статус локации после операции create.

DRAFT: создан

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

ACTIVE: включена, доступна к выбору

QUARANTINE: карантин

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

ARCHIVED: перенесён в архив

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

DRAFTPENDINGACTIVEQUARANTINEFAILEDARCHIVED

errors

array

Ошибки валидации по полям; пустой массив при успехе. Коды только из LocationMutationValidationErrorCode.

Ошибка валидации/бизнеса поля для scope «LocationMutation». Допустимые field: locations[].merchant_location_id, address_tail, latitude/longitude, working_schedule, location_types, …. Для бизнес-правил витрины: code=STOREFRONT_RULE_VIOLATION.

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

field

string

required

Путь к полю. Ожидаемые: locations[].merchant_location_id, address_tail, latitude/longitude, working_schedule, location_types, ….

code

string

required

Код ошибки.

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

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

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

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

REQUIRED_ONE_OF: Нужен хотя бы один из набора полей

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

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

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

INVALID_ADDRESS_FORMAT: Адрес не соответствует шаблону

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

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

SCHEMA_MISMATCH: Поля не соответствуют схеме сущности

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

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

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

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

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

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

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

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

REQUIREDINVALID_TYPEINVALID_FORMATINVALID_ENUMREQUIRED_ONE_OFCONDITIONALLY_REQUIREDINVALID_TIMEINVALID_TIME_RANGEINVALID_ADDRESS_FORMATINVALID_LATITUDEINVALID_LONGITUDESCHEMA_MISMATCHMIN_VALUEMAX_VALUENEGATIVE_VALUETOO_MANY_ITEMSNOT_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/location/create

1curl https://api.omninet.ru/v1/location/create \2  --request POST \3  --header 'Content-Type: application/json' \4  --data '{5  "locations": [6    {7      "merchant_location_id": "string",8      "location_types": [9        "string"10      ],11      "name": "string",12      "address_tail": "string",13      "comment": "string",14      "latitude": 0,15      "longitude": 0,16      "provider_id": "string",17      "provider_location_id": "string",18      "pickup_point_type": "string",19      "payment_methods": [20        "string"21      ],22      "storage_period_days": 0,23      "limits": {24        "length": 0,25        "width": 0,26        "height": 0,27        "weight": 028      },29      "instruction": "string",30      "pickup_services": [31        "string"32      ],33      "working_schedule": [34        {35          "day": "MONDAY",36          "schedule": {37            "time_start": "string",38            "time_end": "string",39            "break": "string",40            "shipping_cutoff": "string"41          }42        }43      ],44      "individual_schedule": [45        {46          "date": "string",47          "schedule": {48            "time_start": "string",49            "time_end": "string",50            "break": "string",51            "shipping_cutoff": "string"52          },53          "is_works": true54        }55      ],56      "is_accepts_returns": true57    }58  ]59}'

{
  "locations": [
    {
      "location_id": "string",
      "merchant_location_id": "string",
      "name": "string",
      "status": "string",
      "errors": [
        {
          "field": "address_tail",
          "code": "INVALID_ADDRESS_FORMAT",
          "message": "Адрес не соответствует ожидаемому формату"
        }
      ]
    }
  ]
}

A successful response.