amarix

Интеграции

Входящие вебхуки

Три потока данных, которые платформа принимает извне: готовые заказы, подтверждения оплаты и статусы доставки.

Приём заказа из внешней системы

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

POST /orders/integrations/vitrine/webhook
{
  "vitrineOrderId": "V-100500",
  "brand": "casher",
  "recipient": {
    "fullName": "Иванов Иван Иванович",
    "phone": "+79990000000",
    "email": "ivanov@example.com"
  },
  "items": [
    { "article": "ART-1", "size": "M", "quantity": 1, "priceKopeks": 450000 }
  ],
  "delivery": {
    "city": "Москва",
    "cityCode": 44,
    "pvzCode": "MSK123",
    "deliveryCostKopeks": 30000
  }
}

Обязательны номер заказа во внешней системе, имя и телефон получателя и непустой список позиций. Имя разбирается позиционно: фамилия, имя, отчество.

Позиции сопоставляются с товарами по отдельному полю артикула и по названию размера. Если сопоставить не удалось, заказ не создаётся вовсе — частично он не примется.

Ошибки

КодОтвет сервераКогда возникаетЧто делать
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":"..."}Артикул не удалось сопоставить с товаром, либо у товара нет такого размера.Сверьте артикулы: сопоставление идёт по отдельному полю товара, а не по названию.

Подтверждение оплаты

Банк сообщает платформе, что заказ оплачен. Этот вебхук настроен между платформой и банком напрямую, разработчику бренда трогать его не нужно — но полезно знать, что происходит после оплаты, потому что оттуда тянется вся цепочка.

По подтверждению платформа списывает товар со склада, регистрирует отправление у перевозчика, получает трек-номер, уведомляет сотрудников и отправляет письмо покупателю.

Статусы доставки

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

Полный список статусов доставки с русскими названиями — в справочнике значений.