Интеграции
Входящие вебхуки
Три потока данных, которые платформа принимает извне: готовые заказы, подтверждения оплаты и статусы доставки.
Приём заказа из внешней системы
Единственный вебхук, которым может пользоваться разработчик бренда. Внешняя система передаёт готовый оплаченный заказ, платформа заводит его у себя и сразу списывает товар со склада.
{
"vitrineOrderId": "V-100500",
"recipient": {
"fullName": "Петров Пётр Петрович",
"phone": "+79990000000"
},
"items": [
{ "article": "ART-1", "size": "M", "quantity": 1, "priceKopeks": 450000 }
],
"delivery": {
"city": "Москва",
"cityCode": 44,
"pvzCode": "MSK123",
"deliveryCostKopeks": 30000
}
}Обязательны номер заказа во внешней системе, имя и телефон получателя и непустой список позиций. Имя разбирается позиционно: фамилия, имя, отчество. Всё остальное — необязательно, включая трек-номер и ссылку на накладную ниже.
{
"vitrineOrderId": "V-100500",
"recipient": {
"fullName": "Петров Пётр Петрович",
"phone": "+79990000000",
"email": "ivanov@example.com"
},
"items": [
{ "article": "ART-1", "size": "M", "quantity": 1, "priceKopeks": 450000 }
],
"delivery": {
"city": "Москва",
"cityCode": 44,
"pvzCode": "MSK123",
"pvzAddress": "Москва, ул. Тверская, 1",
"deliveryCostKopeks": 30000
},
"cdekOrderUuid": "72753a1d-9862-4a6e-b1f4-7cc39e0c1234",
"cdekTrackingNumber": "1234567890",
"waybillUrl": "https://vitrine.market/docs/waybill-100500.pdf",
"promoCode": "SUMMER10",
"comment": "Позвонить за час до доставки",
"orderDate": "2026-09-01T10:15:00+03:00"
}Поля запроса
| Параметр | Тип | Обязателен | Описание |
|---|---|---|---|
vitrineOrderId | string | да | Номер заказа во внешней системе. По нему платформа отличает повтор от нового заказа. |
recipient.fullName | string | да | ФИО получателя одной строкой, через пробел. Разбирается позиционно: фамилия, имя, отчество. |
recipient.phone | string | да | Телефон получателя, в любом формате, который присылает Vitrine. |
recipient.email | string | нет | Почта получателя, для письма с чеком/статусом. |
items[].article | string | да | Артикул Витрины — сверяется с полем «Артикул Витрины» в карточке товара вашего магазина. |
items[].size | string | да | Название легаси-размера, как оно указано у товара (без учёта регистра). Для товара только на атрибутах (без исторического «Размера») сопоставить нечем — см. предупреждение ниже. |
items[].quantity | number | да | Количество, целое положительное число. |
items[].priceKopeks | number | нет | Цена позиции в копейках. Не прислали — берётся цена размера или товара из каталога. |
delivery.city | string | нетпо умолчанию "" | Город доставки. |
delivery.cityCode | number | нет | Код города СДЕК. |
delivery.pvzCode | string | нет | Код пункта выдачи СДЕК. |
delivery.pvzAddress | string | нет | Адрес пункта выдачи — показывается в карточке заказа и покупателю. |
delivery.deliveryCostKopeks | number | нетпо умолчанию 0 | Стоимость доставки в копейках, войдёт в total заказа. |
cdekOrderUuid | string | нет | ID отправления в СДЕК, если Vitrine сама регистрирует отправление. |
cdekTrackingNumber | string | нет | Трек-номер СДЕК — попадёт в карточку заказа и в личный кабинет покупателя. |
waybillUrl | string | нет | Ссылка на накладную или другой сопроводительный документ отправления. |
promoCode | string | нет | Код применённого промокода, для отчётности — повторно скидку платформа не считает. |
comment | string | нет | Комментарий к заказу, виден в админке. |
orderDate | string (ISO 8601) | нет | Дата фактического оформления заказа в Vitrine. Не прислали или дата битая — берётся момент приёма вебхука. |
Подключение магазина
Три шага, каждый делает администратор магазина сам, без участия владельца платформы.
- В админке магазина: Настройки → API-токены → выпустить ключ с правом
orders.create_vitrine. Ключ показывается один раз — сохраните его. - В карточке каждого товара, который продаётся через Vitrine.market, заполните поле «Артикул Витрины» — по нему платформа сопоставляет позиции заказа с каталогом. Артикул уникален в рамках вашего магазина: два бренда на платформе могут независимо использовать одинаковые коды.
- Отдайте команде Vitrine.market адрес
https://api.amarix.ru/orders/integrations/vitrine/webhookи ключ из первого шага — они настроят его на своей стороне под ваш магазин.
Позиции сопоставляются с товарами по отдельному полю артикула и по названию размера. Если сопоставить не удалось, заказ не создаётся вовсе — частично он не примется.
Ошибки
| Код | Ответ сервера | Когда возникает | Что делать |
|---|---|---|---|
| 200 | {"ok":true,"duplicate":true,"order":{...}} | Заказ с таким номером уже принимали. | Это не ошибка: повтор безопасен, второй заказ не создастся. |
| 201 | {"ok":true,"duplicate":false,"order":{"id":15243,"orderNumber":"...","hash":"..."}} | Заказ создан. | — |
| 400 | {"error":"..."} | Нет номера заказа внешней витрины, нет получателя, пустой список позиций или некорректное количество. | — |
| 401 | {"error":"Unauthorized"} | Ключ не принят. | — |
| 403 | {"error":"Forbidden: Missing permission orders.create_vitrine"} | У ключа нет права принимать заказы витрины. | Это отдельное право, его нужно запросить при выпуске ключа. |
| 422 | {"error":"..."} | Артикул не удалось сопоставить с товаром, либо у товара нет такого размера. | Сверьте артикулы: сопоставление идёт по отдельному полю товара, а не по названию. |
Подтверждение оплаты
Банк сообщает платформе, что заказ оплачен. Этот вебхук настроен между платформой и банком напрямую, разработчику бренда трогать его не нужно — но полезно знать, что происходит после оплаты, потому что оттуда тянется вся цепочка.
По подтверждению платформа списывает товар со склада, регистрирует отправление у перевозчика, получает трек-номер, уведомляет сотрудников и отправляет письмо покупателю.
Статусы доставки
Перевозчик присылает события о движении посылки, платформа обновляет статус доставки и, если нужно, статус самого заказа.
Полный список статусов доставки с русскими названиями — в справочнике значений.