Методы API

Обновлено: 19.09.2026

Заказы

get/newOrder Получить заказ в виде формы редактирования

Доступ: API-токен в заголовке X-Service-Token.

Отдаёт заказ в том виде, в каком его показывает форма редактирования в панели: поля заказа, состав, клиент, промокод, скидки и отдельно оплачиваемая доставка.

Права токена: «Заказы и записи на услуги» → «Чтение» (orders.orders.read).

⚠️ Для интеграций используйте GET /order. В этом ответе поле fullValue подменяется суммой позиций Σ count × price без скидок и доставки, поэтому итог к оплате по нему считать нельзя.

Метод не только читает: для способа доставки с отдельной оплатой он может создать строку доставки заказа, а по ожидающему платежу — обратиться к платёжному сервису и отметить доставку оплаченной.

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

id (целое, обязательный, в строке запроса) — iD заказа.

Ответы

200 Заказ в форме редактора. Набор полей близок к GET /order, но fullValue подменён суммой позиций, а состав приходит без снимка опций.

{
  "id": 123,
  "storeId": 1,
  "clientId": 45,
  "status": 1,
  "source": "web",
  "externalId": "CRM-5521",
  "externalSource": "amocrm",
  "fullValue": 1450,
  "discount": 50,
  "promoValue": null,
  "deliveryValue": 300,
  "paymentValue": null,
  "currency": "RUB",
  "isPayment": false,
  "isWaitClientPayment": true,
  "isWaitClientCancel": null,
  "paymentId": 3,
  "paymentMethod": "yookassa",
  "paymentLink": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2f8c",
  "contactName": "Иван Петров",
  "contactPhone": "+79990000001",
  "email": "ivan@myshop.ru",
  "comment": "Позвонить заранее",
  "deliveryType": "courier",
  "deliveryTypeId": 5,
  "pickupPointId": null,
  "courierZoneId": 2,
  "address": "г. Москва, ул. Ленина, д. 1",
  "addressEntrance": "2",
  "addressFloor": "5",
  "addressApt": "17",
  "addressComment": "Код домофона 17К",
  "deliveryDate": "2026-09-20",
  "deliverySlotFrom": "10:00:00",
  "deliverySlotTo": "12:00:00",
  "createdAt": "2026-09-16T10:00:00.123456Z",
  "updatedAt": "2026-09-16T10:04:11.882301Z",
  "client": {
    "id": 45,
    "caption": "Иван Петров",
    "firstName": "Иван",
    "lastName": "Петров",
    "phone": "+79990000001",
    "email": "ivan@myshop.ru",
    "source": "web",
    "isTelegram": false
  },
  "payment": {
    "caption": "Картой онлайн",
    "description": null,
    "icon": null,
    "color": null,
    "isPlugin": false
  },
  "delivery": {
    "caption": "Курьер",
    "description": null,
    "type": "courier",
    "kind": "courier",
    "provider": null
  },
  "discounts": {
    "promo": {
      "value": 0
    },
    "referral": {
      "discountApplied": 0
    },
    "bonus": {
      "pointsUsed": 0
    },
    "manual": {
      "value": 50
    },
    "totalDiscount": 50
  },
  "orderCompositions": [
    {
      "id": 301,
      "orderId": 123,
      "goodId": 10,
      "count": 2,
      "price": 500,
      "currency": null,
      "digitalDelivered": false,
      "optionsSnapshot": [
        {
          "groupId": 1,
          "groupCaption": "Размер",
          "valueId": 2,
          "valueCaption": "M"
        }
      ],
      "good": {
        "caption": "Футболка хлопковая",
        "article": "SHIRT-M",
        "isDigital": false,
        "photo": 77
      }
    }
  ],
  "courierZone": {
    "id": 2,
    "name": "Центр"
  },
  "marketplace": null,
  "actionCount": 2
}

400 id не передан или не является числом: id is required, invalid id. По токену нечисловой или отрицательный ID отсекается раньше: invalid resource id.
401
403
404 Заказа с таким id нет или он удалён: ответ приходит текстом Not Found, а не JSON.
429
503

post/newOrder Создать заказ

Доступ: API-токен в заголовке X-Service-Token.

Создаёт заказ со статусом 0 «Новый», валютой RUB и источником manual. Цены позиций берутся из запроса, а не из каталога.

Права токена: «Заказы и записи на услуги» → «Создание заказов, отправка клиенту и действия с записями» (orders.orders.create).

Остатки резервируются сразу, в той же транзакции. Если товара не хватает, заказ не создаётся — ответ 409. Для товаров с учётом остатка количество должно быть целым.

⚠️ Защиты от повторного создания, кроме пары externalId и externalSource, нет. Если связка может повторить шаг, всегда передавайте эту пару: повтор получит 409 externalId already exists, и дубля не будет. Перед созданием заказ можно найти запросом GET /order?externalSource=…&externalId=….

После создания отправляются события «Новый заказ» и «Изменение остатков» по каждой позиции с учётом остатка, а сотрудники получают уведомление о новом заказе.

ID способов оплаты, точек самовывоза и промокодов через API не получить. Возьмите их из уже оформленного заказа с нужными настройками: поля paymentId, pickupPointId и promo.

Тело запроса (обязательное, JSON)

{
  "clientId": 45,
  "contactName": "Иван Петров",
  "contactPhone": "+79990000001",
  "email": "ivan@myshop.ru",
  "comment": "Позвонить заранее",
  "items": [
    {
      "goodId": 10,
      "count": 2,
      "price": 500
    },
    {
      "goodId": 11,
      "count": 1,
      "price": 250
    }
  ],
  "paymentId": 3,
  "deliveryTypeId": 5,
  "deliveryType": "courier",
  "deliveryValue": 300,
  "address": "г. Москва, ул. Ленина, д. 1",
  "addressEntrance": "2",
  "addressFloor": "5",
  "addressApt": "17",
  "discount": 50,
  "externalId": "CRM-5521",
  "externalSource": "amocrm"
}

Ответы

201 Заказ создан.

{
  "id": 124,
  "fullValue": 1550,
  "status": 0,
  "message": "Заказ создан"
}

400 Ошибка в теле запроса: clientId is required, items must not be empty, each item must have goodId > 0, count > 0 and price >= 0, field "comment" exceeds max length 2000, deliveryType "X" is not enabled for this store, slot requires date and both from/to. Ошибки проверки оплаты приходят с ключом error, например {"error": "для создания платежа необходимо указать email или телефон клиента"}.
401
403
409 Конфликт, заказ не создан: externalId already exists — заказ с такой парой externalId и externalSource уже есть; orderstock: insufficient stock for good N: available=A requested=R — не хватает остатка; «Интервал доставки уже занят, выберите другой».
429
503

put/newOrder Изменить заказ и его состав

Доступ: API-токен в заголовке X-Service-Token.

Меняет поля заказа и, если передан items, его состав. Передавайте только те поля, которые нужно изменить.

Права токена: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка» (orders.orders.update).

⚠️ Тело разбирается строго: неизвестное поле возвращает 400 invalid request body: json: unknown field "…". Так метод отвечает на id, status, paymentId, deliveryValue, externalId и externalSource — изменить их через этот метод нельзя. id заказа передаётся только в адресе.

Состав меняется массивом items: поля нет — позиции не трогаются; позиция с id — у неё меняются count и price; позиция без id добавляется, для неё нужен goodId; позиции заказа, которых нет в списке, удаляются, а пустой массив [] удалит все позиции.

Ответ — строка заказа без вложенных объектов (client, orderCompositions и других). Итог пересчитывается сразу, неоплаченная ссылка на оплату сбрасывается, а платёж у провайдера отменяется. Смена даты и интервала доставки слот не бронирует и не освобождает.

Событий о заказе метод не отправляет. При изменении состава уходят события «Изменение остатков».

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

id (целое, обязательный, в строке запроса) — iD заказа. Передаётся только в адресе.

Тело запроса (обязательное, JSON)

{
  "comment": "Перезвонить после 18:00",
  "contactPhone": "+79990000002",
  "items": [
    {
      "id": 301,
      "goodId": 10,
      "count": 3,
      "price": 500
    },
    {
      "goodId": 12,
      "count": 1,
      "price": 990
    }
  ]
}

Ответы

200 Заказ с новыми значениями, без вложенных объектов.

{
  "id": 123,
  "storeId": 1,
  "clientId": 45,
  "status": 1,
  "source": "web",
  "externalId": "CRM-5521",
  "externalSource": "amocrm",
  "fullValue": 1450,
  "discount": 50,
  "promoValue": null,
  "deliveryValue": 300,
  "paymentValue": null,
  "currency": "RUB",
  "isPayment": false,
  "isWaitClientPayment": true,
  "isWaitClientCancel": null,
  "paymentId": 3,
  "paymentMethod": "yookassa",
  "paymentLink": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2f8c",
  "contactName": "Иван Петров",
  "contactPhone": "+79990000001",
  "email": "ivan@myshop.ru",
  "comment": "Позвонить заранее",
  "deliveryType": "courier",
  "deliveryTypeId": 5,
  "pickupPointId": null,
  "courierZoneId": 2,
  "address": "г. Москва, ул. Ленина, д. 1",
  "addressEntrance": "2",
  "addressFloor": "5",
  "addressApt": "17",
  "addressComment": "Код домофона 17К",
  "deliveryDate": "2026-09-20",
  "deliverySlotFrom": "10:00:00",
  "deliverySlotTo": "12:00:00",
  "createdAt": "2026-09-16T10:00:00.123456Z",
  "updatedAt": "2026-09-16T10:04:11.882301Z",
  "client": {
    "id": 45,
    "caption": "Иван Петров",
    "firstName": "Иван",
    "lastName": "Петров",
    "phone": "+79990000001",
    "email": "ivan@myshop.ru",
    "source": "web",
    "isTelegram": false
  },
  "payment": {
    "caption": "Картой онлайн",
    "description": null,
    "icon": null,
    "color": null,
    "isPlugin": false
  },
  "delivery": {
    "caption": "Курьер",
    "description": null,
    "type": "courier",
    "kind": "courier",
    "provider": null
  },
  "discounts": {
    "promo": {
      "value": 0
    },
    "referral": {
      "discountApplied": 0
    },
    "bonus": {
      "pointsUsed": 0
    },
    "manual": {
      "value": 50
    },
    "totalDiscount": 50
  },
  "orderCompositions": [
    {
      "id": 301,
      "orderId": 123,
      "goodId": 10,
      "count": 2,
      "price": 500,
      "currency": null,
      "digitalDelivered": false,
      "optionsSnapshot": [
        {
          "groupId": 1,
          "groupCaption": "Размер",
          "valueId": 2,
          "valueCaption": "M"
        }
      ],
      "good": {
        "caption": "Футболка хлопковая",
        "article": "SHIRT-M",
        "isDigital": false,
        "photo": 77
      }
    }
  ],
  "courierZone": {
    "id": 2,
    "name": "Центр"
  },
  "marketplace": null,
  "actionCount": 2
}

400 id is required / invalid id; неизвестное поле или неверный тип (invalid request body: json: unknown field "status"); field "address" exceeds max length 500; cannot edit order in final status (cancelled or completed) — отменённый и выполненный заказ менять нельзя; at least one field must be provided for update — пустое тело; goodId is required for new composition items.
401
403
404 Заказ не найден: JSON {"message": "order not found"}. При гонке ответ приходит текстом Not Found.
409 Заказ Яндекс Маркета: Yandex Market orders can only be changed through marketplace actions. Такие заказы меняются только через Маркет. Кроме того: «промокод нельзя изменить после оплаты заказа», «скидку нельзя изменить после оплаты заказа», orderstock: insufficient stock….
429
503

get/order Получить заказ или список заказов

Доступ: API-токен в заголовке X-Service-Token.

С параметром id метод возвращает объект одного заказа, без него — список заказов магазина от новых к старым. Параметр format=list в режиме одного заказа заворачивает ответ в {"count": 1, "rows": [заказ]} — это удобно, когда шаг связки ждёт список.

Права токена: «Заказы и записи на услуги» → «Чтение» (orders.orders.read).

Метод ничего не меняет. count считается по фильтрам без учёта limit и offset, постраничный перебор — параметрами limit и offset.

⚠️ У списка нет ограничения по умолчанию: запрос без limit вернёт все заказы магазина одним ответом. Всегда передавайте limit, например 50.

Заказы, созданные записями на услуги, в список не попадают — их получают методами записей. По id такой заказ доступен. Фильтров по клиенту и дате изменения нет: об изменениях удобнее узнавать из вебхуков.

Знак + в адресе декодируется как пробел, поэтому время в dateFrom и dateTo передавайте в UTC (2026-09-16T10:00:00Z) или кодируйте + как %2B.

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

id (целое, необязательный, в строке запроса) — iD заказа. Если передан — ответом будет один заказ, иначе список.
format (строка, необязательный, в строке запроса) — формат ответа в режиме одного заказа. list заворачивает заказ в {"count": 1, "rows": […]}. В режиме списка параметр не нужен.
externalId (строка, необязательный, в строке запроса) — iD заказа во внешней системе, точное совпадение.
externalSource (строка, необязательный, в строке запроса) — название внешней системы, точное совпадение.
status (строка, необязательный, в строке запроса) — коды статусов через запятую, например 0,1,2. Неизвестный код — 400 invalid status.
paymentStatus (строка, необязательный, в строке запроса) — состояние оплаты через запятую: paid — оплачен, waiting — ждёт оплаты по ссылке, unpaid — не оплачен.
dateFrom (строка, необязательный, в строке запроса) — дата создания заказа, с которой начинается выборка: 2026-09-16 или 2026-09-16T10:00:00Z.
dateTo (строка, необязательный, в строке запроса) — дата создания заказа, до которой идёт выборка. Если время не указано, день входит в выборку целиком.
source (строка, необязательный, в строке запроса) — источники через запятую: web, telegram, max, manual, yandex_market.
search (строка, необязательный, в строке запроса) — номер заказа или часть имени, телефона либо имени пользователя из профиля клиента. Контакты, введённые в самом заказе, не ищутся.
totalFrom (число, необязательный, в строке запроса) — нижняя граница итоговой суммы заказа (fullValue).
totalTo (число, необязательный, в строке запроса) — верхняя граница итоговой суммы заказа (fullValue).
waitingCancel (строка, необязательный, в строке запроса) — true — оставить только заказы, по которым клиент запросил отмену.
deliveryTypeId (целое, необязательный, в строке запроса) — iD одного способа доставки. По токену передать несколько ID через запятую нельзя — ответ 400 invalid resource id.
limit (целое, необязательный, в строке запроса) — размер страницы. Без него вернутся все заказы магазина — всегда передавайте значение.
offset (целое, необязательный, в строке запроса) — сдвиг от начала списка.

Ответы

200 Объект заказа — при запросе с id без format. В остальных случаях список {"count": …, "rows": […]}.

{
  "id": 123,
  "storeId": 1,
  "clientId": 45,
  "status": 1,
  "source": "web",
  "externalId": "CRM-5521",
  "externalSource": "amocrm",
  "fullValue": 1450,
  "discount": 50,
  "promoValue": null,
  "deliveryValue": 300,
  "paymentValue": null,
  "currency": "RUB",
  "isPayment": false,
  "isWaitClientPayment": true,
  "isWaitClientCancel": null,
  "paymentId": 3,
  "paymentMethod": "yookassa",
  "paymentLink": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2f8c",
  "contactName": "Иван Петров",
  "contactPhone": "+79990000001",
  "email": "ivan@myshop.ru",
  "comment": "Позвонить заранее",
  "deliveryType": "courier",
  "deliveryTypeId": 5,
  "pickupPointId": null,
  "courierZoneId": 2,
  "address": "г. Москва, ул. Ленина, д. 1",
  "addressEntrance": "2",
  "addressFloor": "5",
  "addressApt": "17",
  "addressComment": "Код домофона 17К",
  "deliveryDate": "2026-09-20",
  "deliverySlotFrom": "10:00:00",
  "deliverySlotTo": "12:00:00",
  "createdAt": "2026-09-16T10:00:00.123456Z",
  "updatedAt": "2026-09-16T10:04:11.882301Z",
  "client": {
    "id": 45,
    "caption": "Иван Петров",
    "firstName": "Иван",
    "lastName": "Петров",
    "phone": "+79990000001",
    "email": "ivan@myshop.ru",
    "source": "web",
    "isTelegram": false
  },
  "payment": {
    "caption": "Картой онлайн",
    "description": null,
    "icon": null,
    "color": null,
    "isPlugin": false
  },
  "delivery": {
    "caption": "Курьер",
    "description": null,
    "type": "courier",
    "kind": "courier",
    "provider": null
  },
  "discounts": {
    "promo": {
      "value": 0
    },
    "referral": {
      "discountApplied": 0
    },
    "bonus": {
      "pointsUsed": 0
    },
    "manual": {
      "value": 50
    },
    "totalDiscount": 50
  },
  "orderCompositions": [
    {
      "id": 301,
      "orderId": 123,
      "goodId": 10,
      "count": 2,
      "price": 500,
      "currency": null,
      "digitalDelivered": false,
      "optionsSnapshot": [
        {
          "groupId": 1,
          "groupCaption": "Размер",
          "valueId": 2,
          "valueCaption": "M"
        }
      ],
      "good": {
        "caption": "Футболка хлопковая",
        "article": "SHIRT-M",
        "isDigital": false,
        "photo": 77
      }
    }
  ],
  "courierZone": {
    "id": 2,
    "name": "Центр"
  },
  "marketplace": null,
  "actionCount": 2
}

400 Неверный параметр: invalid id, invalid status, invalid paymentStatus value: X, invalid dateFrom (expected YYYY-MM-DD or RFC3339), invalid totalFrom, invalid limit, invalid offset.
401
403
404 Заказа с таким id нет: {"message": "order not found"}. По токену удалённый, чужой или несуществующий заказ обычно отсекается раньше ответом 403.
429
503

put/order/cancel Отменить заказ

Доступ: API-токен в заголовке X-Service-Token.

Ставит заказу статус -1 «Отменён». Тело запроса не нужно, id передаётся в адресе.

Права токена: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка» (orders.orders.cancel).

Отменить можно заказ в любом статусе, кроме уже отменённого: повторная отмена вернёт 404 текстом Not Found. Отменённый заказ вернуть в работу нельзя.

Резерв остатка возвращается на склад, ожидающие ссылки на оплату, забронированный интервал доставки и записи на услуги по заказу отменяются. Уходят события «Отмена заказа» и «Изменение остатков», клиент получает сообщение в Telegram.

⚠️ Отмена оплаченного заказа не возвращает деньги клиенту: возврат оформляется в платёжной системе. Отметка об оплате isPayment при отмене не снимается.

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

id (целое, обязательный, в строке запроса) — iD заказа. Передаётся только в адресе.

Ответы

200 Заказ отменён.

{
  "success": true
}

400 id не передан или не является числом: id is required, invalid id. По токену нечисловой или отрицательный ID отсекается раньше: invalid resource id.
401
403
404 Заказ не найден — JSON {"message": "order not found"}; заказ уже отменён — текст Not Found.
409 Заказ Яндекс Маркета: Yandex Market orders can only be changed through marketplace actions. Такие заказы меняются только через Маркет.
429
503

put/order/changePayment Переключить отметку об оплате

Доступ: API-токен в заголовке X-Service-Token.

Переключает отметку об оплате на противоположную: неоплаченный заказ становится оплаченным, оплаченный — неоплаченным. Тело запроса не нужно, id передаётся в адресе, ответ показывает новое значение.

Права токена: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка» (orders.orders.change_payment).

⚠️ Метод не идемпотентен. Перед вызовом прочитайте заказ через GET /order?id= и убедитесь, что isPayment равен false: если связка повторит шаг, второй вызов снимет оплату.

Когда заказ становится оплаченным, отправляется событие «Оплата заказа», клиент получает сообщение в Telegram, а цифровые товары уходят автоматически, если это настроено. Событие ставится в очередь уже после ответа. Снятие отметки событий не создаёт, но пересоздаёт ссылки на оплату.

Статус заказа и остатки не меняются, ограничений по статусу нет: команда работает и для отменённого, и для выполненного заказа. Способ оплаты этим методом не меняется — параметр paymentId в адресе игнорируется, а сменить способ оплаты по токену нельзя.

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

id (целое, обязательный, в строке запроса) — iD заказа. Передаётся только в адресе.

Ответы

200 Отметка переключена. isPayment — новое значение.

{
  "success": true,
  "isPayment": true
}

400 id не передан или не является числом: id is required, invalid id. По токену нечисловой или отрицательный ID отсекается раньше: invalid resource id.
401
403
404 Заказ не найден — JSON {"message": "order not found"}; при гонке — текст Not Found.
409 Заказ Яндекс Маркета: Yandex Market orders can only be changed through marketplace actions. Такие заказы меняются только через Маркет.
429
503

put/order/confirm Подтвердить заказ

Доступ: API-токен в заголовке X-Service-Token.

Ставит заказу статус 1 «Подтверждён». Тело запроса не нужно, id передаётся в адресе.

Права токена: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка» (orders.orders.confirm).

Подтвердить можно заказ в любом статусе, кроме отменённого: отменённый заказ вернуть в работу нельзя, ответ — 409 cancelled order cannot be reopened.

Уходит событие «Изменение статуса заказа». Клиент, который писал магазину в Telegram, получит сообщение о новом статусе. Запрос клиента на отмену (isWaitClientCancel) при этом молча снимается. Если заказ не оплачен, ссылки на оплату создаются заново.

⚠️ Не переводите выполненный заказ (статус 3) обратно в другой статус: после этого состав заказа перестанет редактироваться.

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

id (целое, обязательный, в строке запроса) — iD заказа. Передаётся только в адресе.

Ответы

200 Статус изменён.

{
  "success": true
}

400 id не передан или не является числом: id is required, invalid id. По токену нечисловой или отрицательный ID отсекается раньше: invalid resource id.
401
403
404 Заказ не найден: {"message": "order not found"}.
409 cancelled order cannot be reopened — заказ отменён. Заказ Яндекс Маркета: Yandex Market orders can only be changed through marketplace actions. Такие заказы меняются только через Маркет.
429
503

put/order/done Выполнить заказ

Доступ: API-токен в заголовке X-Service-Token.

Ставит заказу статус 3 «Выполнен». Тело запроса не нужно, id передаётся в адресе.

Права токена: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка» (orders.orders.complete).

Резерв остатка списывается окончательно: сам остаток при этом не меняется и событий «Изменение остатков» не создаётся. Ожидающие ссылки на оплату отменяются, уходит событие «Изменение статуса заказа», клиент получает сообщение в Telegram. Если способ доставки цифровой, цифровые товары отправляются автоматически.

Команда неприменима к отменённому (-1) и уже выполненному (3) заказу: ответ 404 текстом Not Found.

Оплату команда не отмечает — для этого есть PUT /order/changePayment.

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

id (целое, обязательный, в строке запроса) — iD заказа. Передаётся только в адресе.

Ответы

200 Заказ выполнен.

{
  "success": true
}

400 id не передан или не является числом: id is required, invalid id. По токену нечисловой или отрицательный ID отсекается раньше: invalid resource id.
401
403
404 Заказ не найден — JSON {"message": "order not found"}; заказ уже отменён или уже выполнен — текст Not Found.
409 Заказ Яндекс Маркета: Yandex Market orders can only be changed through marketplace actions. Такие заказы меняются только через Маркет.
429
503

put/order/rejectCancel Отклонить запрос клиента на отмену

Доступ: API-токен в заголовке X-Service-Token.

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

Права токена: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка» (orders.orders.reject_cancel).

Статус заказа не меняется. Вебхуков метод не отправляет и сообщение клиенту не уходит — о решении сообщите ему сами.

Если по заказу нет активного запроса на отмену, ответ — 404 текстом Not Found. Найти такие заказы можно по полю isWaitClientCancel или фильтром waitingCancel=true в списке заказов.

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

id (целое, обязательный, в строке запроса) — iD заказа. Передаётся только в адресе.

Ответы

200 Запрос на отмену отклонён.

{
  "success": true
}

400 id не передан или не является числом: id is required, invalid id. По токену нечисловой или отрицательный ID отсекается раньше: invalid resource id.
401
403
404 Заказ не найден — JSON {"message": "order not found"}; по заказу нет запроса клиента на отмену — текст Not Found.
409 Заказ Яндекс Маркета: Yandex Market orders can only be changed through marketplace actions. Такие заказы меняются только через Маркет.
429
503

put/order/status Сменить статус заказа

Доступ: API-токен в заголовке X-Service-Token.

Ставит заказу статус из тела запроса. id передаётся в адресе.

Права токена: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка» (orders.orders.change_status).

Допустимы только 0 «Новый», 2 «В обработке» и 4 «Доставляется». Для остальных статусов есть свои команды: 1 — PUT /order/confirm, 3 — PUT /order/done, -1 — PUT /order/cancel. Иначе ответ 400 status N requires a dedicated order command.

⚠️ Тело строгое и состоит ровно из поля status: {"id": 123, "status": 2} вернёт 400 invalid request body: json: unknown field "id".

Из отменённого заказа перехода нет — 409. Уходит событие «Изменение статуса заказа», клиенту в Telegram приходит сообщение о новом статусе, запрос клиента на отмену снимается. Если заказ не оплачен, ссылки на оплату создаются заново.

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

id (целое, обязательный, в строке запроса) — iD заказа. Передаётся только в адресе.

Тело запроса (обязательное, JSON)

{
  "status": 2
}

Ответы

200 Статус изменён.

{
  "success": true
}

400 id is required / invalid id; invalid request body: … — пустое тело, неизвестное поле или строка вместо числа; status is required; status N requires a dedicated order command — для -1, 1, 3 и любых других кодов.
401
403
404 Заказ не найден: {"message": "order not found"}.
409 cancelled order cannot be reopened — заказ отменён. Заказ Яндекс Маркета: Yandex Market orders can only be changed through marketplace actions. Такие заказы меняются только через Маркет.
429
503

get/orderFilters Справочники для фильтров заказов

Доступ: API-токен в заголовке X-Service-Token.

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

Права токена: «Заказы и записи на услуги» → «Чтение» (orders.filters.read).

Магазин определяется по токену, storeId передавать не нужно. Метод ничего не меняет.

В deliveryTypes попадают и выключенные способы доставки, а в courierZones — удалённые зоны: учитывайте это, если подставляете ID в новый заказ. Строкового кода способа доставки (deliveryType) справочник не отдаёт — его можно взять из уже оформленного заказа.

Ответы

200 Справочники магазина.

{
  "courierZones": [
    {
      "id": 2,
      "name": "Центр",
      "deliveryTypeId": 5
    }
  ],
  "deliveryTypes": [
    {
      "id": 5,
      "caption": "Курьер",
      "kind": "courier",
      "provider": null
    },
    {
      "id": 6,
      "caption": "Самовывоз",
      "kind": "pickup",
      "provider": null
    }
  ],
  "marketplaceCampaigns": [],
  "marketplaceFlowKinds": [
    "FBS",
    "EXPRESS",
    "DBS_PHYSICAL",
    "DBS_DIGITAL"
  ],
  "sources": [
    "telegram",
    "max",
    "web",
    "manual",
    "yandex_market"
  ],
  "statuses": [
    {
      "value": -1,
      "label": "Отменён"
    },
    {
      "value": 0,
      "label": "Новый"
    },
    {
      "value": 1,
      "label": "Подтверждён"
    },
    {
      "value": 2,
      "label": "В обработке"
    },
    {
      "value": 3,
      "label": "Выполнен"
    },
    {
      "value": 4,
      "label": "Доставляется"
    }
  ]
}

Состав заказа

post/orderComposition Добавить позицию в заказ

Доступ: API-токен в заголовке X-Service-Token.

Добавляет в заказ одну позицию. Цена берётся из запроса, из каталога она не подставляется; выбранные опции товара записываются снимком автоматически.

⚠️ Всегда передавайте count и price. Без count резерв остатка для учитываемого товара оборвётся ошибкой, без price позиция попадёт в сумму заказа и в вебхуки с null.

Резерв остатка пересчитывается сразу и отправляет событие «Изменение остатков», а итог заказа fullValue пересчитывается в фоне, за несколько секунд. Если следующий шаг связки читает сумму заказа, добавьте перед ним паузу. Событий о заказе метод не отправляет.

Позиции отменённого (-1) и выполненного (3) заказа менять нельзя.

Тело запроса (обязательное, JSON)

{
  "orderId": 123,
  "goodId": 12,
  "count": 1,
  "price": 990
}

Ответы

201 Позиция добавлена. В ответе — созданная строка состава.

{
  "id": 305,
  "orderId": 123,
  "goodId": 12,
  "count": 1,
  "price": 990,
  "currency": null,
  "digitalDelivered": false,
  "optionsSnapshot": null,
  "isCategory": null,
  "withOutPrice": null,
  "isConsumable": null,
  "block": null,
  "exchange": null,
  "finally": null,
  "paymentId": null,
  "createdAt": "2026-09-16T10:05:00Z",
  "updatedAt": "2026-09-16T10:05:00Z",
  "deletedAt": null
}

400 orderId is required / goodId is required; invalid request body: …; field "currency" exceeds max length 10; cannot modify compositions of a cancelled or completed order; ошибка orderstock о дробном количестве учитываемого товара.
401
403
404 Заказа с таким orderId нет: {"message": "order not found"}. По токену чужой заказ отсекается раньше ответом 403.
409 Заказ Яндекс Маркета: Yandex Market orders can only be changed through marketplace actions. Такие заказы меняются только через Маркет. Либо ошибка резерва: orderstock: insufficient stock…, orderstock: order composition differs from its reservation.
429
503

put/orderComposition Изменить позицию заказа

Доступ: API-токен в заголовке X-Service-Token.

Меняет количество и цену одной позиции заказа. id — это ID позиции из orderCompositions, он передаётся только в адресе.

Права токена: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка» (orders.orders.update).

Товар позиции сменить нельзя: goodId и orderId в теле игнорируются. Нужно передать хотя бы одно поле, иначе ответ 400.

Резерв остатка пересчитывается сразу и отправляет событие «Изменение остатков», итог заказа — в фоне, за несколько секунд. Событий о заказе метод не отправляет. Позиции отменённого и выполненного заказа менять нельзя.

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

id (целое, обязательный, в строке запроса) — iD позиции заказа — поле id в orderCompositions.

Тело запроса (обязательное, JSON)

{
  "count": 2,
  "price": 950
}

Ответы

200 Позиция с новыми значениями.

{
  "id": 305,
  "orderId": 123,
  "goodId": 12,
  "count": 1,
  "price": 990,
  "currency": null,
  "digitalDelivered": false,
  "optionsSnapshot": null,
  "isCategory": null,
  "withOutPrice": null,
  "isConsumable": null,
  "block": null,
  "exchange": null,
  "finally": null,
  "paymentId": null,
  "createdAt": "2026-09-16T10:05:00Z",
  "updatedAt": "2026-09-16T10:05:00Z",
  "deletedAt": null
}

400 id is required / invalid id; invalid request body: … (пустое тело с Content-Type: application/json даёт unexpected end of JSON input); at least one field must be provided for update; cannot modify compositions of a cancelled or completed order; ошибка orderstock о дробном количестве.
401
403
404 Позиция или её заказ не найдены: ответ приходит текстом Not Found, а не JSON.
409 Заказ Яндекс Маркета: Yandex Market orders can only be changed through marketplace actions. Такие заказы меняются только через Маркет. Либо ошибка резерва: orderstock: insufficient stock….
429
503

delete/orderComposition Удалить позицию заказа

Доступ: API-токен в заголовке X-Service-Token.

Удаляет из заказа одну позицию. id — это ID позиции из orderCompositions, он передаётся только в адресе.

Права токена: «Заказы и записи на услуги» → «Удаление» (orders.orders.delete).

⚠️ Ответ приходит кодом 200 с текстом OK, а не JSON.

Остаток по удалённой позиции возвращается на склад, уходит событие «Изменение остатков», а итог заказа пересчитывается в фоне, за несколько секунд. Событий о заказе метод не отправляет. Позиции отменённого и выполненного заказа удалять нельзя.

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

id (целое, обязательный, в строке запроса) — iD позиции заказа — поле id в orderCompositions.

Ответы

200 Позиция удалена. Тело ответа — текст OK, а не JSON.

OK

400 id is required / invalid id; cannot modify compositions of a cancelled or completed order; ошибка orderstock.
401
403
404 Позиция или её заказ не найдены: ответ приходит текстом Not Found, а не JSON.
409 Заказ Яндекс Маркета: Yandex Market orders can only be changed through marketplace actions. Такие заказы меняются только через Маркет.
429
503

Клиенты и сообщения

post/clients/create Создать клиента

Доступ: API-токен в заголовке X-Service-Token.

Создаёт карточку клиента. Магазин определяется по токену, storeId передавать не нужно. Ответ — код 201 и созданный клиент с source: "manual".

Права токена: «Клиенты и сообщения» → «Создание и изменение клиентов, бонусы и сообщения» (clients.clients.create).

Дубли по телефону не проверяются. Перед созданием ищите клиента по телефону или externalId запросом GET /clients/list.

Клиента, созданного через API, нельзя связать с Telegram или MAX. Если он потом напишет боту магазина, появится отдельная карточка.

После создания отправляется событие «Новый клиент» (client.created).

Тело запроса (обязательное, JSON)

{
  "firstName": "Иван",
  "lastName": "Петров",
  "phone": "+79991234567",
  "email": "ivan@example.com",
  "externalId": "CRM-778",
  "externalSource": "amocrm"
}

Ответы

201 Клиент создан.

{
  "id": 1542,
  "caption": "Иван Петров",
  "firstName": "Иван",
  "lastName": "Петров",
  "middleName": null,
  "phone": "+79991234567",
  "email": "ivan@example.com",
  "source": "manual",
  "externalId": "CRM-778",
  "externalSource": "amocrm",
  "telegramId": null,
  "maxId": null,
  "userName": null,
  "botId": null,
  "telegramEnabled": false,
  "maxEnabled": false,
  "login": "ivan@example.com",
  "block": null,
  "createdAt": "2026-09-16T10:15:30.123456Z",
  "updatedAt": "2026-09-16T10:15:30.123456Z"
}

400 Тело не является JSON-объектом, поле длиннее допустимого, неверный формат email или пароль короче 6 символов.
401
403
409 Занятый email или логин — email already exists; повтор пары externalSource и externalId — externalId already exists.
429
503

get/clients/info Карточка клиента

Доступ: API-токен в заголовке X-Service-Token.

Возвращает профиль клиента, число его заказов orderCount и до 20 последних сообщений переписки в recentMessages, новые первыми.

Права токена: «Клиенты и сообщения» → «Чтение» (clients.clients.read).

В сообщениях from: true означает сообщение магазина (оператор, бот или API), from: false — сообщение клиента.

Полей source, externalId и externalSource в карточке нет: их отдаёт список клиентов. Файлы из переписки по токену недоступны.

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

id (целое, обязательный, в строке запроса) — iD клиента.

Ответы

200 Карточка клиента.

{
  "id": 1541,
  "caption": "Пётр Смирнов",
  "firstName": "Пётр",
  "lastName": "Смирнов",
  "phone": "+79990000001",
  "email": null,
  "userName": "petr_tg",
  "telegramId": "123456789",
  "maxId": null,
  "botId": 3,
  "telegramEnabled": true,
  "maxEnabled": false,
  "createdAt": "2026-09-10T08:00:00Z",
  "updatedAt": "2026-09-16T09:00:00Z",
  "orderCount": 2,
  "recentMessages": [
    {
      "id": 90212,
      "clientId": 1541,
      "botId": 3,
      "platform": "telegram",
      "text": "Заказ №123 передан курьеру",
      "type": null,
      "from": true,
      "createdAt": "2026-09-16T09:00:00Z"
    },
    {
      "id": 90211,
      "clientId": 1541,
      "botId": 3,
      "platform": "telegram",
      "text": "Когда доставка?",
      "type": "text",
      "from": false,
      "createdAt": "2026-09-16T08:59:00Z"
    }
  ],
  "channels": []
}

400 id не передан или не является целым числом.
401
403
404 Клиент не найден: ответ приходит текстом Not Found, а не JSON. По токену этот код почти недостижим — для чужого, удалённого и несуществующего клиента API отвечает 403.
429
503

get/clients/list Список клиентов и поиск

Доступ: API-токен в заголовке X-Service-Token.

Возвращает клиентов магазина с поиском и фильтрами. Клиенты идут от новых к старым.

Права токена: «Клиенты и сообщения» → «Чтение» (clients.clients.read).

Важно: без limit метод вернёт всех клиентов магазина одним ответом. Всегда передавайте limit, например 50, и перебирайте страницы через offset.

Телефон ищется как часть строки в том виде, в каком его сохранили, поэтому надёжнее искать по последним десяти цифрам: search=9991234567.

Только этот метод отдаёт source, externalId и externalSource: в карточке клиента их нет.

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

search (строка, необязательный, в строке запроса) — часть имени, телефона, email или имени пользователя в Telegram.
externalId (строка, необязательный, в строке запроса) — точное совпадение ID клиента во внешней системе.
externalSource (строка, необязательный, в строке запроса) — точное совпадение названия внешней системы.
hasTelegramId (строка, необязательный, в строке запроса) — true, чтобы получить только клиентов с Telegram ID: они писали боту магазина или входили через Telegram.
limit (целое, необязательный, в строке запроса) — размер страницы. Без параметра придут все клиенты магазина.
offset (целое, необязательный, в строке запроса) — сдвиг от начала списка.

Ответы

200 Список клиентов.

{
  "count": 2,
  "rows": [
    {
      "id": 1542,
      "caption": "Иван Петров",
      "firstName": "Иван",
      "lastName": "Петров",
      "phone": "+79991234567",
      "email": "ivan@example.com",
      "source": "manual",
      "externalId": "CRM-778",
      "externalSource": "amocrm",
      "telegramId": null,
      "createdAt": "2026-09-16T10:15:30.123456Z",
      "updatedAt": "2026-09-16T10:15:30.123456Z"
    },
    {
      "id": 1541,
      "caption": "Пётр Смирнов",
      "firstName": "Пётр",
      "lastName": "Смирнов",
      "phone": "+79990000001",
      "email": null,
      "source": "telegram",
      "externalId": null,
      "externalSource": null,
      "telegramId": "123456789",
      "userName": "petr_tg",
      "createdAt": "2026-09-10T08:00:00Z",
      "updatedAt": "2026-09-16T09:00:00Z"
    }
  ]
}

400 Нечисловой limit или offset.
401
403
429
503

post/clients/message Отправить сообщение клиенту

Доступ: API-токен в заголовке X-Service-Token.

Отправляет текст клиенту в Telegram через бота магазина. Клиент должен хотя бы раз написать боту: без этого у него нет Telegram-канала, и ответ будет 400 client has no Telegram channel.

Права токена: «Клиенты и сообщения» → «Создание и изменение клиентов, бонусы и сообщения» (communication.messages.send).

Ответ 201 означает, что сообщение сохранено в переписке и передано на отправку. Доставку он не гарантирует: если клиент заблокировал бота, сообщение останется в истории, но не дойдёт.

Текст отправляется в режиме HTML: можно использовать теги Telegram <b>, <i> и <a href="…">. Символы <, > и & в обычном тексте заменяйте на <, > и &, иначе Telegram не доставит сообщение.

Сообщение появится в чате с клиентом в панели. Событие «Входящее сообщение» (message.received) оно не создаёт, поэтому связка «клиент написал → ответить» не зациклится. Файлы через API не отправляются.

Ответ 503 telegram bot is not connected означает, что бот не подключён.

Важно: не отправляйте через этот метод сообщения в MAX. Правила MAX запрещают ботам сервисные, транзакционные и рекламные сообщения, поэтому в MAX магазин отправляет только ответы, которые пишет сотрудник в чате панели.

Тело запроса (обязательное, JSON)

{
  "clientId": 1541,
  "text": "Заказ <b>№123</b> передан курьеру"
}

Ответы

201 Сообщение сохранено в переписке и передано на отправку. Доставку ответ не гарантирует.

{
  "id": 90213,
  "clientId": 1541,
  "botId": 3,
  "platform": "telegram",
  "text": "Заказ <b>№123</b> передан курьеру",
  "type": null,
  "from": true,
  "fileId": null,
  "url": null,
  "readAt": null,
  "externalMessageId": null,
  "telegramMessageId": null,
  "createdAt": "2026-09-16T11:05:00Z",
  "updatedAt": "2026-09-16T11:05:00Z"
}

400 Нет clientId или text, тело не является JSON-объектом, либо у клиента нет Telegram-канала (client has no Telegram channel).
401
403
409 telegram channel is disabled: у бота выключен Telegram-канал или клиент не связан с ботом магазина.
429
503

post/clients/updateInfo Изменить клиента

Доступ: API-токен в заголовке X-Service-Token.

Изменяет карточку клиента. ID клиента передаётся в теле, в поле clientId, а не в адресе. Ответ — клиент с новыми значениями, без полей source, externalId и externalSource.

Права токена: «Клиенты и сообщения» → «Создание и изменение клиентов, бонусы и сообщения» (clients.clients.update).

Важно: каждое переданное поле перезаписывается, в том числе пустым значением. "email": "" удалит email клиента. Не передавайте поля, которые менять не нужно.

externalId, externalSource и привязку к мессенджерам этим методом изменить нельзя.

После успешного вызова отправляется событие «Изменение клиента» (client.updated), даже если значения не изменились.

Тело запроса (обязательное, JSON)

{
  "clientId": 1542,
  "phone": "+79990000010"
}

Ответы

200 Клиент изменён.

{
  "id": 1542,
  "caption": "Иван Петров",
  "firstName": "Иван",
  "lastName": "Петров",
  "middleName": null,
  "phone": "+79991234567",
  "email": "ivan@example.com",
  "source": "manual",
  "externalId": "CRM-778",
  "externalSource": "amocrm",
  "telegramId": null,
  "maxId": null,
  "userName": null,
  "botId": null,
  "telegramEnabled": false,
  "maxEnabled": false,
  "login": "ivan@example.com",
  "block": null,
  "createdAt": "2026-09-16T10:15:30.123456Z",
  "updatedAt": "2026-09-16T10:15:30.123456Z"
}

400 Нет поля clientId, тело не является JSON-объектом, не передано ни одного изменяемого поля (at least one field must be provided for update) или значение не прошло проверку.
401
403
404 Клиент не найден: ответ приходит текстом Not Found, а не JSON.
409 Новый email или логин уже занят: email already exists.
429
503

Товары

get/goods Получить товар или список товаров

Доступ: API-токен в заголовке X-Service-Token.

С параметром id метод вернёт один товар объектом без обёртки. Без id придёт список {"count": …, "rows": […]}, где count — число товаров по фильтрам без учёта страниц. Сортировка — по возрастанию id.

Права токена: «Товары и остатки» → «Чтение» (catalog.goods.read).

Важно: без limit метод вернёт весь каталог одним ответом. Всегда передавайте limit, например 50, и перебирайте страницы через offset.

Если товар не найден, придёт {"count": 0, "rows": []}. Чтобы получить один товар в форме списка, используйте ids вместо id.

physical.stockQty — остаток, доступный к продаже: резерв оформленных заказов уже вычтен. При physical.trackStock = false остаток не учитывается. У товаров с hasVariants: true остатки ведутся по вариантам: запросите их с параметром parentGoodId.

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

id (целое, необязательный, в строке запроса) — iD одного товара. Остальные фильтры не учитываются, а ответ приходит объектом без обёртки.
ids (строка, необязательный, в строке запроса) — до 200 ID через запятую, например 12,15,40. Ответ — список в том же порядке.
otherId (строка, необязательный, в строке запроса) — точное совпадение кода товара во внешней системе, например из 1С.
search (строка, необязательный, в строке запроса) — часть названия или артикула, без учёта регистра.
modelId (целое, необязательный, в строке запроса) — iD категории. Товары вложенных категорий не попадают.
parentGoodId (целое, необязательный, в строке запроса) — варианты указанного товара.
type (строка, необязательный, в строке запроса) — тип: physical — физический товар, digital — цифровой, service — услуга, category — карточка-категория.
excludeVariants (строка, необязательный, в строке запроса) — true, чтобы не показывать варианты товаров.
limit (целое, необязательный, в строке запроса) — размер страницы. Без параметра придёт весь каталог.
offset (целое, необязательный, в строке запроса) — сдвиг от начала списка.

Ответы

200 Список товаров или, при запросе с id, один товар объектом без обёртки.

{
  "count": 1,
  "rows": [
    {
      "id": 42,
      "type": "physical",
      "caption": "Футболка базовая",
      "article": "TS-001",
      "otherId": "1C-000123",
      "price": 1990.0,
      "oldPrice": 2490.0,
      "modelId": 7,
      "parentGoodId": null,
      "hasVariants": false,
      "onModeration": false,
      "stopListId": null,
      "physical": {
        "trackStock": true,
        "stockQty": 12,
        "lowStockThreshold": 3
      }
    }
  ]
}

400 Неверный фильтр: invalid ids, invalid type; нечисловой id, modelId или parentGoodId — invalid resource id.
401
403
404 Товар не найден: ответ приходит текстом Not Found, а не JSON. По токену этот код почти недостижим — для чужого, удалённого и несуществующего товара API отвечает 403.
429
503

post/goods Создать товар

Доступ: API-токен в заголовке X-Service-Token.

Создаёт карточку товара или вариант существующего товара. Ответ — код 201 и созданный товар без блока physical: остаток после создания проверяйте запросом GET /goods?id=….

Права токена: «Товары и остатки» → «Создание товаров и корректировка остатков» (catalog.goods.create).

Начальный остаток из physical.stockQty не попадает в историю движений и не создаёт событие «Изменение остатков» (stock.changed).

Если у категории есть обязательные характеристики, придёт ошибка 400 required specification "…" must be filled before publication. Создайте товар скрытым (onModeration: true), заполните характеристики в панели и после этого покажите товар на витрине.

Метод рассчитан прежде всего на физические товары. Цифровые товары и услуги удобнее создавать в панели: у них много собственных настроек. Список категорий по токену получить нельзя — возьмите modelId у любого товара нужной категории.

После создания отправляется событие «Новый товар» (good.created).

Тело запроса (обязательное, JSON)

{
  "type": "physical",
  "caption": "Футболка базовая",
  "article": "TS-001",
  "otherId": "1C-000123",
  "price": 1990,
  "modelId": 7,
  "physical": {
    "trackStock": true,
    "stockQty": 12,
    "lowStockThreshold": 3
  }
}

Ответы

201 Товар создан. В ответе только поля товара, без блока physical.

{
  "id": 42,
  "type": "physical",
  "caption": "Футболка базовая",
  "description": "Хлопок 100%",
  "article": "TS-001",
  "otherId": "1C-000123",
  "price": 1990.0,
  "oldPrice": 2490.0,
  "modelId": 7,
  "parentGoodId": null,
  "hasVariants": false,
  "onModeration": false,
  "stopListId": null,
  "isNew": false,
  "isHot": false,
  "isPopular": false,
  "isDigital": false,
  "countryCode": "RU",
  "barcodes": [
    "4600000000017"
  ],
  "createdAt": "2026-09-01T10:00:00.123456Z",
  "updatedAt": "2026-09-16T08:30:00.654321Z",
  "deletedAt": null,
  "physical": {
    "trackStock": true,
    "stockQty": 12,
    "lowStockThreshold": 3,
    "weightGrams": 250
  },
  "digital": null,
  "service": null,
  "category": null
}

400 Не передан или неверен type; не прошли проверку countryCode, barcodes, размеры или характеристики; родитель варианта не найден либо у него уже 200 вариантов.
401
403
409 Товар с таким otherId уже есть в магазине. Для сценария «создать или обновить» сначала ищите товар по otherId, а при 409 переходите к изменению.
429
503

put/goods Изменить товар

Доступ: API-токен в заголовке X-Service-Token.

Меняются только переданные поля, остальные остаются прежними. ID товара передаётся в адресе как ?id=42. Ответ — товар с новыми значениями, без блока physical.

Права токена: «Товары и остатки» → «Редактирование» (catalog.goods.update).

Важно: не передавайте в этом методе поля остатка. Блок physical заменяется целиком: всё, что в нём не указано, обнулится, в том числе учёт остатка trackStock. А stockQty на верхнем уровне тела без trackStock отключит учёт остатка у товара. Остаток меняйте методом корректировки POST /admin/goods/{id}/stock/adjust: он же запишет движение в историю и отправит событие.

Смена цены остаток не трогает. Тип товара сменить нельзя. В теле должно быть хотя бы одно поле товара, иначе ошибка 400 no valid fields provided for update. Неизвестные ключи, например stock или quantity, молча игнорируются.

Событие «Изменение товара» (good.updated) отправляется после каждого успешного вызова, даже если значения не изменились. Если связка вызывает этот метод по событию good.updated, получится бесконечный цикл.

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

id (целое, обязательный, в строке запроса) — iD товара или варианта.

Тело запроса (обязательное, JSON)

{
  "price": 1790,
  "oldPrice": 1990
}

Ответы

200 Товар изменён. В ответе только поля товара, без блока physical.

{
  "id": 42,
  "type": "physical",
  "caption": "Футболка базовая",
  "description": "Хлопок 100%",
  "article": "TS-001",
  "otherId": "1C-000123",
  "price": 1990.0,
  "oldPrice": 2490.0,
  "modelId": 7,
  "parentGoodId": null,
  "hasVariants": false,
  "onModeration": false,
  "stopListId": null,
  "isNew": false,
  "isHot": false,
  "isPopular": false,
  "isDigital": false,
  "countryCode": "RU",
  "barcodes": [
    "4600000000017"
  ],
  "createdAt": "2026-09-01T10:00:00.123456Z",
  "updatedAt": "2026-09-16T08:30:00.654321Z",
  "deletedAt": null,
  "physical": {
    "trackStock": true,
    "stockQty": 12,
    "lowStockThreshold": 3,
    "weightGrams": 250
  },
  "digital": null,
  "service": null,
  "category": null
}

400 Нет query-параметра id (id is required); не передано ни одного поля товара (no valid fields provided for update); попытка сменить тип (type cannot be changed) или магазин (storeId cannot be changed); ошибки parentGoodId и проверок значений.
401
403
404 Товар исчез между проверкой и записью: ответ приходит текстом Not Found, а не JSON.
409 Занятый otherId — good with this otherId already exists in the store; одновременная правка товара и его вариантов — good family changed concurrently; reload the good before saving.
429
503

delete/goods Удалить товар

Доступ: API-токен в заголовке X-Service-Token.

Удаляет один товар вместе с его вариантами. ID товара передаётся в адресе как ?id=42. Ответ — {"ok": true, "deleted": 1}.

Права токена: «Товары и остатки» → «Удаление» (catalog.goods.delete).

Список ID в одном запросе токен передать не может — вызывайте метод для каждого товара. Активные записи на удалённую услугу отменяются, а код otherId снова становится свободным.

Повторное удаление того же товара вернёт ошибку 403: удалённый товар для токена уже не принадлежит магазину.

Событие «Удаление товара» (good.deleted) придёт только для указанного товара, для его вариантов событий нет. В событии одно поле — id.

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

id (целое, обязательный, в строке запроса) — iD товара.

Ответы

200 Товар удалён.

{
  "ok": true,
  "deleted": 1
}

400 Нет id (id is required), id не является целым числом (invalid resource id) или в теле передан список ID.
401
403
404 Товар исчез между проверкой и удалением: ответ приходит текстом Not Found, а не JSON.
429
503

get/goods/all Получить все товары магазина

Доступ: API-токен в заголовке X-Service-Token.

Возвращает все товары магазина вместе с вариантами одним ответом {"count": …, "rows": […]}. Параметров нет.

Права токена: «Товары и остатки» → «Чтение» (catalog.goods.read).

В строках только основные поля товара: блока остатков physical, фото и признака стоп-листа здесь нет. Для большого каталога удобнее GET /goods с limit и offset.

Ответы

200 Все товары магазина. В строках нет блока physical, фото и признака стоп-листа.

{
  "count": 1,
  "rows": [
    {
      "id": 42,
      "type": "physical",
      "caption": "Футболка базовая",
      "article": "TS-001",
      "otherId": "1C-000123",
      "price": 1990.0,
      "oldPrice": 2490.0,
      "modelId": 7,
      "parentGoodId": null,
      "hasVariants": false,
      "onModeration": false,
      "stopListId": null,
      "physical": {
        "trackStock": true,
        "stockQty": 12,
        "lowStockThreshold": 3
      }
    }
  ]
}

Остатки

post/admin/goods/{id}/stock/adjust Корректировка остатка

Доступ: API-токен в заголовке X-Service-Token.

Изменяет остаток товара или варианта на delta: положительное число — приход, отрицательное — списание. Метод работает так же, как кнопки «Приход» и «Списание» на вкладке «Склад» карточки товара. Ответ — остаток после корректировки в поле newQty.

Права токена: «Товары и остатки» → «Создание товаров и корректировка остатков» (catalog.inventory.adjust).

Важно: корректировка относится к флажку «Создание товаров и корректировка остатков». Прав «Редактирование» для неё недостаточно: токен без нужного флажка получит 403 с requiredCapability: catalog.inventory.adjust.

Движение появится в истории остатка, а магазин отправит события «Изменение остатков» (stock.changed) и, если остаток опустился до порога, «Малый остаток» (stock.low).

Ошибки этого метода приходят в поле error, а не message.

Метода «установить остаток» нет. Чтобы выставить точное значение из учётной системы, прочитайте текущий physical.stockQty запросом GET /goods, вычислите разницу и передайте её в delta. У товаров с вариантами корректируйте каждый вариант по его ID: у строки родителя обычно выключен учёт остатка.

Параметры пути

id (целое, обязательный, в пути) — iD товара или варианта.

Тело запроса (обязательное, JSON)

{
  "delta": 5,
  "reason": "income",
  "comment": "Поставка №15"
}

Ответы

200 Остаток изменён.

{
  "newQty": 17,
  "delta": 5,
  "reason": "income"
}

400 {"error": "stock_not_tracked"} — у товара не включён учёт остатка. В форме {"message": …} приходят invalid good id и delta must be non-zero, а также ошибка разбора тела, если delta не целое число.
401
403
409 Остаток ушёл бы ниже нуля: корректировка не выполнена.
429
500 goodtype: good not found — товар не физический: у цифровых товаров, услуг и категорий остатка нет. Другие ошибки 500 означают сбой записи, при котором корректировка откатывается.
503

get/admin/goods/{id}/stock/log История движений остатка

Доступ: API-токен в заголовке X-Service-Token.

Возвращает последние движения остатка товара, новые сверху. Параметр limit задаёт число записей, по умолчанию 50. Постраничного перебора нет: offset, фильтров по дате и причине у метода тоже нет.

Права токена: «Товары и остатки» → «Чтение» (catalog.inventory.audit).

Поле id совпадает с movementId в событиях остатков, count — число записей в этом ответе. В operatorUserId указан сотрудник, чьё действие в панели привело к движению; для запросов по токену и заказов с витрины там null.

У вариантов свои журналы: запрашивайте историю по ID варианта. Остаток, заданный при создании или изменении товара и при импорте каталога, в историю не попадает.

Параметры пути

id (целое, обязательный, в пути) — iD товара или варианта.

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

limit (целое, необязательный, в строке запроса) — сколько последних записей вернуть. По умолчанию 50; некорректное значение тоже даёт 50.

Ответы

200 История движений остатка.

{
  "count": 2,
  "rows": [
    {
      "id": 1235,
      "goodId": 42,
      "delta": 5,
      "stockQtyAfter": 17,
      "reason": "income",
      "comment": "Поставка №15",
      "operatorUserId": null,
      "orderId": null,
      "createdAt": "2026-09-16T08:35:00.123456Z"
    },
    {
      "id": 1234,
      "goodId": 42,
      "delta": -2,
      "stockQtyAfter": 12,
      "reason": "order_created",
      "comment": "order reservation",
      "operatorUserId": null,
      "orderId": 122,
      "createdAt": "2026-09-15T12:00:00.5Z"
    }
  ]
}

400 invalid good id или invalid resource id: ID товара в адресе не является положительным целым числом.
401
403
429
503

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

get/admin/servicePerformers Список исполнителей

Доступ: API-токен в заголовке X-Service-Token.

Возвращает исполнителей магазина в виде {"count": …, "rows": […]}. С параметром id ответ — один объект без обёртки.

Права токена: «Точки и исполнители» → «Чтение» (locations.performers.read).

Удалённые исполнители не возвращаются. Сортировка — по sortOrder, затем по id. Без limit придут все исполнители; offset работает только вместе с limit.

Если исполнителя или записи с указанным ID нет в магазине токена, API отвечает кодом 403, а не 404.

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

id (целое, необязательный, в строке запроса) — iD одного исполнителя. Ответ — объект без обёртки.
enabled (строка, необязательный, в строке запроса) — true, чтобы получить только активных исполнителей, false — только выключенных.
goodId (целое, необязательный, в строке запроса) — исполнители, привязанные к услуге с этим ID.
search (строка, необязательный, в строке запроса) — часть имени, телефона или email.
externalId (строка, необязательный, в строке запроса) — точное совпадение ID во внешней системе.
externalSource (строка, необязательный, в строке запроса) — точное совпадение названия внешней системы.
limit (целое, необязательный, в строке запроса) — размер страницы. Без limit придут все исполнители.
offset (целое, необязательный, в строке запроса) — сдвиг от начала списка.

Ответы

200 Список исполнителей или, с параметром id, один исполнитель.

{
  "count": 1,
  "rows": [
    {
      "id": 12,
      "storeId": 1,
      "fullName": "Анна Иванова",
      "photoUrl": null,
      "bio": "Мастер-парикмахер, стаж 8 лет",
      "phone": "+79990001122",
      "email": "anna@myshop.ru",
      "timezone": "Europe/Moscow",
      "color": "#FF8800",
      "enabled": true,
      "sortOrder": 0,
      "externalId": "1c-000123",
      "externalSource": "1c",
      "createdAt": "2026-09-01T09:00:00.123456Z",
      "updatedAt": "2026-09-01T09:00:00.123456Z",
      "deletedAt": null
    }
  ]
}

400 Некорректное значение параметра: invalid id, invalid goodId, enabled must be "true" or "false".
401
403
429
503

post/admin/servicePerformers Добавить исполнителя

Доступ: API-токен в заголовке X-Service-Token.

Создаёт исполнителя. Обязательное поле одно — fullName; магазин подставляется по токену.

Права токена: «Точки и исполнители» → «Создание» (locations.performers.create).

Ответ — код 201 и созданный исполнитель, после него уходит событие performer.created («Новый исполнитель»).

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

Пара externalId + externalSource должна быть уникальной, повтор завершится ошибкой.

Тело запроса (обязательное, JSON)

{
  "fullName": "Анна Иванова",
  "phone": "+79990001122",
  "email": "anna@myshop.ru",
  "timezone": "Europe/Moscow",
  "color": "#FF8800",
  "externalId": "1c-000123",
  "externalSource": "1c"
}

Ответы

201 Исполнитель создан.

{
  "id": 12,
  "storeId": 1,
  "fullName": "Анна Иванова",
  "photoUrl": null,
  "bio": "Мастер-парикмахер, стаж 8 лет",
  "phone": "+79990001122",
  "email": "anna@myshop.ru",
  "timezone": "Europe/Moscow",
  "color": "#FF8800",
  "enabled": true,
  "sortOrder": 0,
  "externalId": "1c-000123",
  "externalSource": "1c",
  "createdAt": "2026-09-01T09:00:00.123456Z",
  "updatedAt": "2026-09-01T09:00:00.123456Z",
  "deletedAt": null
}

400 fullName is required, invalid timezone: <tz>, invalid color, expected #RRGGBB или ошибка разбора тела.
401
403
429
503

put/admin/servicePerformers Изменить исполнителя

Доступ: API-токен в заголовке X-Service-Token.

Меняет только переданные поля, например {"phone": "+79990001133", "enabled": false}. Ответ — исполнитель с новыми значениями.

Права токена: «Точки и исполнители» → «Редактирование» (locations.performers.update).

Не передавайте null в timezone, enabled и sortOrder: такой запрос завершится ошибкой. Тело без единого известного поля даёт 400 no valid fields provided for update.

Событие performer.updated («Изменение исполнителя») уходит после каждого успешного вызова, даже если значения не изменились.

Если исполнителя или записи с указанным ID нет в магазине токена, API отвечает кодом 403, а не 404.

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

id (целое, обязательный, в строке запроса) — iD исполнителя.

Тело запроса (обязательное, JSON)

{
  "phone": "+79990001133",
  "enabled": false
}

Ответы

200 Исполнитель с новыми значениями.

{
  "id": 12,
  "storeId": 1,
  "fullName": "Анна Иванова",
  "photoUrl": null,
  "bio": "Мастер-парикмахер, стаж 8 лет",
  "phone": "+79990001122",
  "email": "anna@myshop.ru",
  "timezone": "Europe/Moscow",
  "color": "#FF8800",
  "enabled": true,
  "sortOrder": 0,
  "externalId": "1c-000123",
  "externalSource": "1c",
  "createdAt": "2026-09-01T09:00:00.123456Z",
  "updatedAt": "2026-09-01T09:00:00.123456Z",
  "deletedAt": null
}

400 id is required, invalid id, fullName must not be empty, invalid timezone: <tz>, invalid color, expected #RRGGBB, no valid fields provided for update.
401
403
429
503

delete/admin/servicePerformers Удалить исполнителя

Доступ: API-токен в заголовке X-Service-Token.

Удаляет исполнителя. Ответ: {"ok": true, "id": 12}.

Права токена: «Точки и исполнители» → «Удаление» (locations.performers.delete).

⚠️ Исполнитель пропадает из свободного времени для записи, но уже созданные записи к нему не отменяются — перенесите или отмените их отдельно. График, отсутствия и привязки к услугам тоже остаются на месте.

После удаления уходит событие performer.deleted («Удаление исполнителя»).

Если исполнителя или записи с указанным ID нет в магазине токена, API отвечает кодом 403, а не 404.

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

id (целое, обязательный, в строке запроса) — iD исполнителя.

Ответы

200 Исполнитель удалён.

{
  "ok": true,
  "id": 12
}

400 id is required или invalid id.
401
403
429
503

get/admin/servicePerformers/{id}/absences Список отсутствий

Доступ: API-токен в заголовке X-Service-Token.

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

Права токена: «Точки и исполнители» → «Чтение» (locations.performers.read).

Параметры from и to необязательны и принимают только дату со временем. Постраничного перебора нет, прошедшие отсутствия тоже возвращаются.

Время передавайте в формате ISO 8601 с часовым поясом: 2026-10-01T09:00:00Z или 2026-10-01T12:00:00+03:00. В адресе запроса знак + кодируйте как %2B, иначе время не распознается.

Параметры пути

id (целое, обязательный, в пути) — iD исполнителя.

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

from (строка, необязательный, в строке запроса) — начало периода, только дата со временем в ISO 8601.
to (строка, необязательный, в строке запроса) — конец периода, только дата со временем в ISO 8601.

Ответы

200 Отсутствия, пересекающиеся с периодом.

{
  "count": 1,
  "rows": [
    {
      "id": 41,
      "performerId": 12,
      "startAt": "2026-10-01T00:00:00+03:00",
      "endAt": "2026-10-08T00:00:00+03:00",
      "reason": "Отпуск",
      "createdAt": "2026-09-16T10:00:00.5Z",
      "updatedAt": "2026-09-16T10:00:00.5Z",
      "deletedAt": null
    }
  ]
}

400 invalid performer id, invalid from: expected ISO 8601, invalid to: expected ISO 8601. Незакодированный + в смещении тоже даёт эту ошибку.
401
403
429
503

post/admin/servicePerformers/{id}/absences Добавить отсутствие

Доступ: API-токен в заголовке X-Service-Token.

Добавляет исполнителю отсутствие. Поля startAt и endAt обязательны, конец должен быть позже начала.

Права токена: «Точки и исполнители» → «Создание» (locations.performers.create).

Флажка «весь день» нет: чтобы закрыть целый день, укажите полночь этого дня и полночь следующего с часовым поясом исполнителя.

Если на это время у исполнителя есть записи на подтверждении или подтверждённые, отсутствие не создастся: ответ — 409 с телом {"error": "conflicts", "conflicts": [...]}. Чтобы создать отсутствие и отменить эти записи, повторите запрос с параметром ?force=true. Записи получат статус «Отменено магазином», клиенты с Telegram — уведомление, а по каждой записи уйдёт событие booking.cancelled («Отмена записи»); список отменённых вернётся в поле cancelledBookingIds. Записи, которые ждут оплаты, конфликтом не считаются и не отменяются.

Ответ — код 201 и созданное отсутствие, затем уходит событие absence.created («Новое отсутствие исполнителя»). Пересекающиеся отсутствия и отсутствия в прошлом разрешены.

Параметры пути

id (целое, обязательный, в пути) — iD исполнителя.

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

force (строка, необязательный, в строке запроса) — true — создать отсутствие и отменить пересекающиеся записи. Значение сравнивается точно, подходит только строка true.

Тело запроса (обязательное, JSON)

{
  "startAt": "2026-10-01T00:00:00+03:00",
  "endAt": "2026-10-08T00:00:00+03:00",
  "reason": "Отпуск"
}

Ответы

201 Отсутствие создано.

{
  "id": 41,
  "performerId": 12,
  "startAt": "2026-10-01T00:00:00+03:00",
  "endAt": "2026-10-08T00:00:00+03:00",
  "reason": "Отпуск",
  "createdAt": "2026-09-16T10:00:00.5Z",
  "updatedAt": "2026-09-16T10:00:00.5Z",
  "deletedAt": null,
  "cancelledBookingIds": [
    501
  ]
}

400 startAt is required, endAt is required, invalid startAt: expected ISO 8601 (e.g. 2026-05-01T00:00:00Z), endAt must be after startAt или ошибка разбора тела.
401
403
409 Пересечение с записями, а force=true не передан. Отсутствие не создано.
429
503

delete/admin/servicePerformers/{id}/absences/{absenceId} Удалить отсутствие

Доступ: API-токен в заголовке X-Service-Token.

Удаляет отсутствие исполнителя. Ответ — код 200 и текст OK, а не JSON.

Права токена: «Точки и исполнители» → «Удаление» (locations.performers.delete).

⚠️ Записи, отменённые при создании отсутствия, не восстанавливаются.

После удаления уходит событие absence.deleted («Удаление отсутствия»).

Если отсутствие с таким ID принадлежит другому исполнителю, ответ — 404 текстом Not Found.

Параметры пути

id (целое, обязательный, в пути) — iD исполнителя.
absenceId (целое, обязательный, в пути) — iD отсутствия.

Ответы

200 Отсутствие удалено. Тело ответа — текст OK, а не JSON.

OK

400 invalid performer id или invalid absence id.
401
403
404 Отсутствие не найдено или принадлежит другому исполнителю: ответ приходит текстом Not Found, а не JSON.
429
503

get/admin/servicePerformers/{id}/schedule Получить график

Доступ: API-токен в заголовке X-Service-Token.

График — недельный шаблон: для каждого дня недели задаются интервалы работы по времени исполнителя. Дни обозначаются числами: 0 — воскресенье, 1 — понедельник и так далее до 6 — субботы.

Права токена: «Точки и исполнители» → «Чтение» (locations.performers.read).

Перерыв на обед выглядит как два интервала в один день. Дни без интервалов в ответе отсутствуют, у пустого графика schedule — пустой список.

Если связке удобнее плоский список, добавьте ?format=list: придёт {"count": …, "rows": […]}, где каждая строка — один интервал с полями dayOfWeek, timeFrom и timeTo.

Выходные и отпуска на конкретные даты оформляются отсутствиями.

Параметры пути

id (целое, обязательный, в пути) — iD исполнителя.

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

format (строка, необязательный, в строке запроса) — list — плоский список интервалов вместо группировки по дням.

Ответы

200 График исполнителя: по умолчанию сгруппированный по дням, с ?format=list — плоский список.

{
  "performerId": 12,
  "schedule": [
    {
      "dayOfWeek": 1,
      "intervals": [
        {
          "timeFrom": "09:00",
          "timeTo": "13:00"
        },
        {
          "timeFrom": "14:00",
          "timeTo": "18:00"
        }
      ]
    },
    {
      "dayOfWeek": 2,
      "intervals": [
        {
          "timeFrom": "10:00",
          "timeTo": "16:00"
        }
      ]
    }
  ]
}

400 Некорректный ID исполнителя.
401
403
429
503

put/admin/servicePerformers/{id}/schedule Задать график

Доступ: API-токен в заголовке X-Service-Token.

Задаёт недельный график исполнителя.

Права токена: «Точки и исполнители» → «Редактирование» (locations.performers.update).

Метод заменяет весь график. Дни, которых нет в запросе, станут нерабочими, а пустой список schedule удалит график целиком.
Время пишите с ведущим нулём: 09:00, а не 9:00. Конец интервала должен быть позже начала, поэтому работа через полночь не поддерживается. Максимум — 23:59.
Интервалы одного дня не должны пересекаться, иначе ответ 400 с текстом overlap.
Перерыв на обед задаётся двумя интервалами в один день.

⚠️ Существующие записи не проверяются и не отменяются. Событий смена графика не создаёт: связка узнает о новом графике только следующим запросом.

Ответ всегда приходит во вложенном формате, параметр format здесь не действует.

Параметры пути

id (целое, обязательный, в пути) — iD исполнителя.

Тело запроса (обязательное, JSON)

{
  "schedule": [
    {
      "dayOfWeek": 1,
      "intervals": [
        {
          "timeFrom": "09:00",
          "timeTo": "13:00"
        },
        {
          "timeFrom": "14:00",
          "timeTo": "18:00"
        }
      ]
    },
    {
      "dayOfWeek": 3,
      "intervals": [
        {
          "timeFrom": "10:00",
          "timeTo": "16:00"
        }
      ]
    }
  ]
}

Ответы

200 Новый график исполнителя.

{
  "performerId": 12,
  "schedule": [
    {
      "dayOfWeek": 1,
      "intervals": [
        {
          "timeFrom": "09:00",
          "timeTo": "13:00"
        },
        {
          "timeFrom": "14:00",
          "timeTo": "18:00"
        }
      ]
    },
    {
      "dayOfWeek": 2,
      "intervals": [
        {
          "timeFrom": "10:00",
          "timeTo": "16:00"
        }
      ]
    }
  ]
}

400 invalid performer id; dayOfWeek 7 is out of range [0, 6]; dayOfWeek 1: invalid timeFrom "9-00", expected HH:MM; dayOfWeek 1: timeTo "09:00" must be after timeFrom "10:00"; dayOfWeek 1: intervals "09:00"–"13:00" and "12:00"–"15:00" overlap.
401
403
429
503

Записи на услуги

get/admin/serviceBookings Список записей

Доступ: API-токен в заголовке X-Service-Token.

Возвращает записи клиентов на услуги. Запись создаёт клиент на витрине, отдельного метода создания записи в API нет: через API записи получают, подтверждают, завершают, отменяют и переносят.

Права токена: «Заказы и записи на услуги» → «Чтение» (bookings.bookings.read).

Записи отсортированы по времени начала. С параметрами from и to записи async (без фиксированного времени) в выборку не попадают. Фильтров по точке, клиенту и дате изменения нет.

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

from (строка, необязательный, в строке запроса) — записи, пересекающиеся с периодом. Дата со временем или дата 2026-09-20, которая означает полночь по UTC.
to (строка, необязательный, в строке запроса) — конец периода в том же формате, что from.
status (строка, необязательный, в строке запроса) — статусы через запятую, например pending_confirmation,confirmed.
performerId (целое, необязательный, в строке запроса) — записи одного исполнителя.
goodId (целое, необязательный, в строке запроса) — записи на одну услугу.
limit (целое, необязательный, в строке запроса) — размер страницы: по умолчанию 100, максимум 500. Большее значение молча обрезается до 500.
offset (целое, необязательный, в строке запроса) — сдвиг от начала списка.

Ответы

200 Записи, подходящие под фильтры.

{
  "count": 1,
  "rows": [
    {
      "id": 501,
      "orderId": 9001,
      "orderCompositionId": 12001,
      "goodId": 310,
      "goodCaption": "Стрижка",
      "performerId": 12,
      "performerName": "Анна Иванова",
      "performerColor": "#FF8800",
      "serviceMode": "on_site",
      "status": "pending_confirmation",
      "startAt": "2026-09-20T07:00:00Z",
      "endAt": "2026-09-20T08:00:00Z",
      "dueBy": null,
      "meetingUrl": "",
      "address": "",
      "lat": null,
      "lng": null,
      "zoneId": null,
      "locationId": 3,
      "venueId": 3,
      "clientNotes": "Позвоню заранее",
      "performerNotes": null,
      "cancellationReason": null,
      "confirmedAt": null,
      "completedAt": null,
      "cancelledAt": null,
      "createdAt": "2026-09-16T10:15:30.123456Z",
      "updatedAt": "2026-09-16T10:15:30.123456Z",
      "performer": {
        "id": 12,
        "fullName": "Анна Иванова",
        "photoUrl": null,
        "bio": null,
        "phone": "+79990001122",
        "email": "anna@myshop.ru",
        "timezone": "Europe/Moscow",
        "color": "#FF8800",
        "enabled": true
      },
      "clientId": 777,
      "storeId": 1,
      "fullValue": 1500,
      "isPayment": false,
      "prepaidAmount": 0,
      "outstandingAmount": 1500,
      "paymentMethod": null,
      "paymentLink": null,
      "venue": {
        "id": 3,
        "name": "Салон на Ленина",
        "address": "ул. Ленина, 1",
        "lat": 55.7558,
        "lng": 37.6173,
        "phone": "+74950000000",
        "workingHours": "10:00-20:00",
        "timezone": "Europe/Moscow",
        "description": null,
        "color": null
      },
      "zone": null
    }
  ]
}

400 invalid performerId, invalid goodId или invalid from: expected RFC3339 or YYYY-MM-DD, got "…" — так выглядит незакодированный +.
401
403
429
503

get/admin/serviceBookings/{id} Получить запись

Доступ: API-токен в заголовке X-Service-Token.

Возвращает ту же запись, что и список, и добавляет контакты клиента: clientName, clientPhone и clientEmail, а также объект clientContacts с контактами, которые клиент оставил при оформлении.

Права токена: «Заказы и записи на услуги» → «Чтение» (bookings.bookings.read).

Если исполнителя или записи с указанным ID нет в магазине токена, API отвечает кодом 403, а не 404.

Параметры пути

id (целое, обязательный, в пути) — iD записи.

Ответы

200 Запись с контактами клиента.

{
  "id": 501,
  "orderId": 9001,
  "orderCompositionId": 12001,
  "goodId": 310,
  "goodCaption": "Стрижка",
  "performerId": 12,
  "performerName": "Анна Иванова",
  "performerColor": "#FF8800",
  "serviceMode": "on_site",
  "status": "pending_confirmation",
  "startAt": "2026-09-20T07:00:00Z",
  "endAt": "2026-09-20T08:00:00Z",
  "dueBy": null,
  "meetingUrl": "",
  "address": "",
  "lat": null,
  "lng": null,
  "zoneId": null,
  "locationId": 3,
  "venueId": 3,
  "clientNotes": "Позвоню заранее",
  "performerNotes": null,
  "cancellationReason": null,
  "confirmedAt": null,
  "completedAt": null,
  "cancelledAt": null,
  "createdAt": "2026-09-16T10:15:30.123456Z",
  "updatedAt": "2026-09-16T10:15:30.123456Z",
  "performer": {
    "id": 12,
    "fullName": "Анна Иванова",
    "photoUrl": null,
    "bio": null,
    "phone": "+79990001122",
    "email": "anna@myshop.ru",
    "timezone": "Europe/Moscow",
    "color": "#FF8800",
    "enabled": true
  },
  "clientId": 777,
  "storeId": 1,
  "fullValue": 1500,
  "isPayment": false,
  "prepaidAmount": 0,
  "outstandingAmount": 1500,
  "paymentMethod": null,
  "paymentLink": null,
  "venue": {
    "id": 3,
    "name": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "lat": 55.7558,
    "lng": 37.6173,
    "phone": "+74950000000",
    "workingHours": "10:00-20:00",
    "timezone": "Europe/Moscow",
    "description": null,
    "color": null
  },
  "zone": null,
  "clientName": "Мария",
  "clientPhone": "+79991234567",
  "clientEmail": "maria@example.com",
  "clientContacts": {
    "name": "Мария",
    "phone": "+79991234567",
    "email": "maria@example.com"
  }
}

400 Некорректный ID записи.
401
403
429
503

patch/admin/serviceBookings/{id} Перенести запись или сменить исполнителя

Доступ: API-токен в заголовке X-Service-Token.

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

Права токена: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка» (bookings.bookings.update).

⚠️ Важно: если в запросе нет meetingUrl или performerNotes, метод очистит эти поля. Перед изменением прочитайте запись и передайте текущие значения вместе с новыми.

Если выбранное время занято или не совпадает с сеткой записи, ответ — 409 slot_unavailable. Свободное время показывает публичный метод витрины GET https://myshop.ru/api/v2/services/slots?goodId=310&performerId=14&date=2026-09-21&days=1. Отправляйте его без заголовка X-Service-Token: с токеном публичный метод ответит 403.
Завершённые и отменённые записи менять нельзя: 409 booking can no longer be edited. У записи, которая ждёт оплаты, нельзя сменить исполнителя.
Новый исполнитель должен быть активен и привязан к услуге и точке.
У записей async (без фиксированного времени) меняются только dueBy и performerNotes.

⚠️ Метод не отправляет событий и не уведомляет клиента. Сообщите клиенту о переносе сами, например методом отправки сообщения. Связка узнаёт о переносе, сделанном в панели, только опросом списка записей.

Параметры пути

id (целое, обязательный, в пути) — iD записи.

Тело запроса (обязательное, JSON)

{
  "performerId": 14,
  "startAt": "2026-09-21T08:00:00Z",
  "performerNotes": "Перенос по звонку клиента"
}

Ответы

200 Запись с новыми значениями.

{
  "id": 501,
  "orderId": 9001,
  "orderCompositionId": 12001,
  "goodId": 310,
  "goodCaption": "Стрижка",
  "performerId": 14,
  "performerName": "Ольга Петрова",
  "performerColor": "#FF8800",
  "serviceMode": "on_site",
  "status": "pending_confirmation",
  "startAt": "2026-09-21T08:00:00Z",
  "endAt": "2026-09-21T09:00:00Z",
  "dueBy": null,
  "meetingUrl": null,
  "address": "",
  "lat": null,
  "lng": null,
  "zoneId": null,
  "locationId": 3,
  "venueId": 3,
  "clientNotes": "Позвоню заранее",
  "performerNotes": "Перенос по звонку клиента",
  "cancellationReason": null,
  "confirmedAt": null,
  "completedAt": null,
  "cancelledAt": null,
  "createdAt": "2026-09-16T10:15:30.123456Z",
  "updatedAt": "2026-09-16T10:15:30.123456Z",
  "performer": {
    "id": 12,
    "fullName": "Анна Иванова",
    "photoUrl": null,
    "bio": null,
    "phone": "+79990001122",
    "email": "anna@myshop.ru",
    "timezone": "Europe/Moscow",
    "color": "#FF8800",
    "enabled": true
  },
  "clientId": 777,
  "storeId": 1,
  "fullValue": 1500,
  "isPayment": false,
  "prepaidAmount": 0,
  "outstandingAmount": 1500,
  "paymentMethod": null,
  "paymentLink": null,
  "venue": {
    "id": 3,
    "name": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "lat": 55.7558,
    "lng": 37.6173,
    "phone": "+74950000000",
    "workingHours": "10:00-20:00",
    "timezone": "Europe/Moscow",
    "description": null,
    "color": null
  },
  "zone": null
}

400 invalid body (невалидный JSON, нет заголовка Content-Type: application/json, startAt или dueBy не в ISO 8601); performerNotes is too long (максимум 5000 байт, кириллица занимает 2 байта); meetingUrl must start with http:// or https://; meetingUrl is only valid for online services; future startAt is required when changing the schedule; venueId is required: this service has multiple venues; performer not assigned to this service or venue.
401
403
409 slot_unavailable — выбранное время занято или не совпадает с сеткой записи; booking can no longer be edited — запись завершена или отменена; performer cannot be changed while payment is pending.
429
503

post/admin/serviceBookings/{id}/cancel Отменить запись

Доступ: API-токен в заголовке X-Service-Token.

Переводит запись из любого незавершённого статуса, включая «Ожидает оплаты», в «Отменено магазином» (cancelled_by_store) и ставит cancelledAt. Причину можно передать в теле: {"reason": "Мастер заболел"}; тело необязательно.

Права токена: «Заказы и записи на услуги» → «Создание заказов, отправка клиенту и действия с записями» (bookings.bookings.cancel).

Флажка «Редактирование» для команд над записями недостаточно: нужен именно флажок создания. При нехватке права придёт 403 с полем requiredCapability.

Время освобождается, клиент с Telegram получает сообщение, уходит событие booking.cancelled («Отмена записи»). Ограничение по сроку отмены, которое действует для клиента, для магазина не применяется.

⚠️ Важно: отмена записи не отменяет заказ и не возвращает предоплату. Если клиент уже заплатил, оформите возврат в платёжной системе.

Команда, отправленная связкой, вернётся в Альбато событием. Защитите сценарий от зацикливания: не вызывайте команду в ответ на её же событие.

Параметры пути

id (целое, обязательный, в пути) — iD записи.

Тело запроса (необязательное, JSON)

{
  "reason": "Мастер заболел"
}

Ответы

200 Запись отменена.

{
  "id": 501,
  "orderId": 9001,
  "orderCompositionId": 12001,
  "goodId": 310,
  "goodCaption": "Стрижка",
  "performerId": 12,
  "performerName": "Анна Иванова",
  "performerColor": "#FF8800",
  "serviceMode": "on_site",
  "status": "cancelled_by_store",
  "startAt": "2026-09-20T07:00:00Z",
  "endAt": "2026-09-20T08:00:00Z",
  "dueBy": null,
  "meetingUrl": "",
  "address": "",
  "lat": null,
  "lng": null,
  "zoneId": null,
  "locationId": 3,
  "venueId": 3,
  "clientNotes": "Позвоню заранее",
  "performerNotes": null,
  "cancellationReason": "Мастер заболел",
  "confirmedAt": null,
  "completedAt": null,
  "cancelledAt": "2026-09-19T12:00:00.42Z",
  "createdAt": "2026-09-16T10:15:30.123456Z",
  "updatedAt": "2026-09-16T10:15:30.123456Z",
  "performer": {
    "id": 12,
    "fullName": "Анна Иванова",
    "photoUrl": null,
    "bio": null,
    "phone": "+79990001122",
    "email": "anna@myshop.ru",
    "timezone": "Europe/Moscow",
    "color": "#FF8800",
    "enabled": true
  },
  "clientId": 777,
  "storeId": 1,
  "fullValue": 1500,
  "isPayment": false,
  "prepaidAmount": 0,
  "outstandingAmount": 1500,
  "paymentMethod": null,
  "paymentLink": null,
  "venue": {
    "id": 3,
    "name": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "lat": 55.7558,
    "lng": 37.6173,
    "phone": "+74950000000",
    "workingHours": "10:00-20:00",
    "timezone": "Europe/Moscow",
    "description": null,
    "color": null
  },
  "zone": null
}

400 Некорректный ID записи.
401
403
409 Переход из текущего статуса невозможен, например запись уже завершена или отменена: {"message": "invalid_transition"}.
429
503

post/admin/serviceBookings/{id}/complete Завершить запись

Доступ: API-токен в заголовке X-Service-Token.

Переводит запись из статуса «Подтверждено» (confirmed) в «Завершено» (completed) и ставит completedAt. Тело запроса не нужно. Ответ — запись с новым статусом.

Права токена: «Заказы и записи на услуги» → «Создание заказов, отправка клиенту и действия с записями» (bookings.bookings.complete).

Уходит событие booking.completed («Завершение записи»), клиенту сообщение не отправляется. Запись «На подтверждении» завершить нельзя: сначала подтвердите её.

Параметры пути

id (целое, обязательный, в пути) — iD записи.

Ответы

200 Запись завершена.

{
  "id": 501,
  "orderId": 9001,
  "orderCompositionId": 12001,
  "goodId": 310,
  "goodCaption": "Стрижка",
  "performerId": 12,
  "performerName": "Анна Иванова",
  "performerColor": "#FF8800",
  "serviceMode": "on_site",
  "status": "completed",
  "startAt": "2026-09-20T07:00:00Z",
  "endAt": "2026-09-20T08:00:00Z",
  "dueBy": null,
  "meetingUrl": "",
  "address": "",
  "lat": null,
  "lng": null,
  "zoneId": null,
  "locationId": 3,
  "venueId": 3,
  "clientNotes": "Позвоню заранее",
  "performerNotes": null,
  "cancellationReason": null,
  "confirmedAt": "2026-09-16T10:15:30.123456Z",
  "completedAt": "2026-09-20T08:05:00.1Z",
  "cancelledAt": null,
  "createdAt": "2026-09-16T10:15:30.123456Z",
  "updatedAt": "2026-09-16T10:15:30.123456Z",
  "performer": {
    "id": 12,
    "fullName": "Анна Иванова",
    "photoUrl": null,
    "bio": null,
    "phone": "+79990001122",
    "email": "anna@myshop.ru",
    "timezone": "Europe/Moscow",
    "color": "#FF8800",
    "enabled": true
  },
  "clientId": 777,
  "storeId": 1,
  "fullValue": 1500,
  "isPayment": false,
  "prepaidAmount": 0,
  "outstandingAmount": 1500,
  "paymentMethod": null,
  "paymentLink": null,
  "venue": {
    "id": 3,
    "name": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "lat": 55.7558,
    "lng": 37.6173,
    "phone": "+74950000000",
    "workingHours": "10:00-20:00",
    "timezone": "Europe/Moscow",
    "description": null,
    "color": null
  },
  "zone": null
}

400 Некорректный ID записи.
401
403
409 Переход из текущего статуса невозможен, например запись уже завершена или отменена: {"message": "invalid_transition"}.
429
503

post/admin/serviceBookings/{id}/confirm Подтвердить запись

Доступ: API-токен в заголовке X-Service-Token.

Переводит запись из статуса «На подтверждении» (pending_confirmation) в «Подтверждено» (confirmed) и ставит confirmedAt. Тело запроса не нужно. Ответ — запись с новым статусом.

Права токена: «Заказы и записи на услуги» → «Создание заказов, отправка клиенту и действия с записями» (bookings.bookings.confirm).

Клиент с Telegram получает сообщение, уходит событие booking.confirmed («Подтверждение записи»). Запись в статусе «Ожидает оплаты» подтвердить нельзя — она подтверждается сама после оплаты, и события при этом не будет.

Параметры пути

id (целое, обязательный, в пути) — iD записи.

Ответы

200 Запись подтверждена.

{
  "id": 501,
  "orderId": 9001,
  "orderCompositionId": 12001,
  "goodId": 310,
  "goodCaption": "Стрижка",
  "performerId": 12,
  "performerName": "Анна Иванова",
  "performerColor": "#FF8800",
  "serviceMode": "on_site",
  "status": "confirmed",
  "startAt": "2026-09-20T07:00:00Z",
  "endAt": "2026-09-20T08:00:00Z",
  "dueBy": null,
  "meetingUrl": "",
  "address": "",
  "lat": null,
  "lng": null,
  "zoneId": null,
  "locationId": 3,
  "venueId": 3,
  "clientNotes": "Позвоню заранее",
  "performerNotes": null,
  "cancellationReason": null,
  "confirmedAt": "2026-09-16T10:15:30.123456Z",
  "completedAt": null,
  "cancelledAt": null,
  "createdAt": "2026-09-16T10:15:30.123456Z",
  "updatedAt": "2026-09-16T10:15:30.123456Z",
  "performer": {
    "id": 12,
    "fullName": "Анна Иванова",
    "photoUrl": null,
    "bio": null,
    "phone": "+79990001122",
    "email": "anna@myshop.ru",
    "timezone": "Europe/Moscow",
    "color": "#FF8800",
    "enabled": true
  },
  "clientId": 777,
  "storeId": 1,
  "fullValue": 1500,
  "isPayment": false,
  "prepaidAmount": 0,
  "outstandingAmount": 1500,
  "paymentMethod": null,
  "paymentLink": null,
  "venue": {
    "id": 3,
    "name": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "lat": 55.7558,
    "lng": 37.6173,
    "phone": "+74950000000",
    "workingHours": "10:00-20:00",
    "timezone": "Europe/Moscow",
    "description": null,
    "color": null
  },
  "zone": null
}

400 Некорректный ID записи.
401
403
409 Переход из текущего статуса невозможен, например запись уже завершена или отменена: {"message": "invalid_transition"}.
429
503

patch/admin/serviceBookings/{id}/meetingUrl Ссылка на онлайн-встречу

Доступ: API-токен в заголовке X-Service-Token.

Меняет только ссылку на встречу: {"meetingUrl": "https://meet.example.com/abc"}. Пустая строка удаляет ссылку. Ответ — запись с новой ссылкой.

Права токена: «Заказы и записи на услуги» → «Редактирование, статусы, оплата и доставка» (bookings.bookings.update).

В отличие от общего PATCH, метод не трогает остальные поля, в том числе performerNotes. Режим и статус записи не проверяются.

Событий и уведомлений клиенту нет.

Параметры пути

id (целое, обязательный, в пути) — iD записи.

Тело запроса (обязательное, JSON)

{
  "meetingUrl": "https://meet.example.com/abc"
}

Ответы

200 Запись с новой ссылкой.

{
  "id": 501,
  "orderId": 9001,
  "orderCompositionId": 12001,
  "goodId": 310,
  "goodCaption": "Стрижка",
  "performerId": 12,
  "performerName": "Анна Иванова",
  "performerColor": "#FF8800",
  "serviceMode": "online",
  "status": "pending_confirmation",
  "startAt": "2026-09-20T07:00:00Z",
  "endAt": "2026-09-20T08:00:00Z",
  "dueBy": null,
  "meetingUrl": "https://meet.example.com/abc",
  "address": "",
  "lat": null,
  "lng": null,
  "zoneId": null,
  "locationId": 3,
  "venueId": 3,
  "clientNotes": "Позвоню заранее",
  "performerNotes": null,
  "cancellationReason": null,
  "confirmedAt": null,
  "completedAt": null,
  "cancelledAt": null,
  "createdAt": "2026-09-16T10:15:30.123456Z",
  "updatedAt": "2026-09-16T10:15:30.123456Z",
  "performer": {
    "id": 12,
    "fullName": "Анна Иванова",
    "photoUrl": null,
    "bio": null,
    "phone": "+79990001122",
    "email": "anna@myshop.ru",
    "timezone": "Europe/Moscow",
    "color": "#FF8800",
    "enabled": true
  },
  "clientId": 777,
  "storeId": 1,
  "fullValue": 1500,
  "isPayment": false,
  "prepaidAmount": 0,
  "outstandingAmount": 1500,
  "paymentMethod": null,
  "paymentLink": null,
  "venue": {
    "id": 3,
    "name": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "lat": 55.7558,
    "lng": 37.6173,
    "phone": "+74950000000",
    "workingHours": "10:00-20:00",
    "timezone": "Europe/Moscow",
    "description": null,
    "color": null
  },
  "zone": null
}

400 invalid body (пустое тело или отсутствует заголовок Content-Type: application/json), meetingUrl must start with http:// or https://, meetingUrl is too long (max 2048 chars).
401
403
429
503

post/admin/serviceBookings/{id}/noShow Отметить неявку

Доступ: API-токен в заголовке X-Service-Token.

Переводит запись из статуса «Подтверждено» (confirmed) в «Не пришёл» (no_show). Тело запроса не нужно. Ответ — запись с новым статусом.

Права токена: «Заказы и записи на услуги» → «Создание заказов, отправка клиенту и действия с записями» (bookings.bookings.no_show).

Клиент с Telegram получает сообщение, уходит событие booking.no_show («Неявка клиента»). Отдельной метки времени у неявки нет, меняется только updatedAt.

Параметры пути

id (целое, обязательный, в пути) — iD записи.

Ответы

200 Запись отмечена как неявка.

{
  "id": 501,
  "orderId": 9001,
  "orderCompositionId": 12001,
  "goodId": 310,
  "goodCaption": "Стрижка",
  "performerId": 12,
  "performerName": "Анна Иванова",
  "performerColor": "#FF8800",
  "serviceMode": "on_site",
  "status": "no_show",
  "startAt": "2026-09-20T07:00:00Z",
  "endAt": "2026-09-20T08:00:00Z",
  "dueBy": null,
  "meetingUrl": "",
  "address": "",
  "lat": null,
  "lng": null,
  "zoneId": null,
  "locationId": 3,
  "venueId": 3,
  "clientNotes": "Позвоню заранее",
  "performerNotes": null,
  "cancellationReason": null,
  "confirmedAt": "2026-09-16T10:15:30.123456Z",
  "completedAt": null,
  "cancelledAt": null,
  "createdAt": "2026-09-16T10:15:30.123456Z",
  "updatedAt": "2026-09-16T10:15:30.123456Z",
  "performer": {
    "id": 12,
    "fullName": "Анна Иванова",
    "photoUrl": null,
    "bio": null,
    "phone": "+79990001122",
    "email": "anna@myshop.ru",
    "timezone": "Europe/Moscow",
    "color": "#FF8800",
    "enabled": true
  },
  "clientId": 777,
  "storeId": 1,
  "fullValue": 1500,
  "isPayment": false,
  "prepaidAmount": 0,
  "outstandingAmount": 1500,
  "paymentMethod": null,
  "paymentLink": null,
  "venue": {
    "id": 3,
    "name": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "lat": 55.7558,
    "lng": 37.6173,
    "phone": "+74950000000",
    "workingHours": "10:00-20:00",
    "timezone": "Europe/Moscow",
    "description": null,
    "color": null
  },
  "zone": null
}

400 Некорректный ID записи.
401
403
409 Переход из текущего статуса невозможен, например запись уже завершена или отменена: {"message": "invalid_transition"}.
429
503

Управление интеграцией

get/integrations/albato Настройки, токены и журнал доставок

Доступ: только из панели магазина, по токену администратора. Связке Альбато этот метод недоступен.

Возвращает настройки отправки событий, список выданных токенов и 20 последних доставок. Секрет подписи в ответ не попадает.

Права сотрудника: «Просмотр настроек» (store.settings.read).

Пока услуга Альбато не подключена суперадминистратором, метод отвечает 403 Albato integration requires a paid add-on. Исключение — отзыв токена: он работает и с отключённой услугой.

Метод доступен только сотруднику с JWT. Запрос с заголовком X-Service-Token получит 403: интеграция не может читать свои настройки и выпускать себе токены.

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

storeId (целое, необязательный, в строке запроса) — iD магазина. Если не передать, берётся основной магазин инстанса.

Ответы

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

{
  "storeId": 0,
  "settings": {
    "enabled": true,
    "webhookUrl": "https://webhook.albato.ru/wh/…",
    "webhookSecretSet": true,
    "events": [
      "order.created",
      "order.paid",
      "order.status_changed"
    ],
    "configured": true
  },
  "settingsSource": "store",
  "tokenPermissionGroups": {},
  "tokens": [
    {
      "id": 7,
      "caption": "Альбато — чтение заказов",
      "sections": "[{\"name\":\"orders\",\"create\":false,\"update\":false,\"delete\":false}]",
      "createdAt": "2026-09-16T10:00:00Z",
      "lastUsedAt": "2026-09-19T08:12:04Z",
      "expiresAt": null
    }
  ],
  "deliveries": [
    {
      "id": 1201,
      "deliveryId": "22222222-2222-4222-8222-222222222222",
      "event": "order.created",
      "status": "sent",
      "attempts": 0,
      "lastError": null,
      "createdAt": "2026-09-19T08:00:00Z"
    }
  ],
  "defaultEvents": [
    "string"
  ]
}

401
403
404 Магазин не найден.
429
503

put/integrations/albato Изменить адрес, секрет и события

Доступ: только из панели магазина, по токену администратора. Связке Альбато этот метод недоступен.

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

Права сотрудника: «Изменение настроек» (store.settings.update).

Пауза (enabled: false) сохраняет уже поставленные в очередь события: они уйдут после включения, попытки на них не тратятся. События, которые произошли во время паузы, не создаются и задним числом не восстанавливаются.

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

storeId (целое, необязательный, в строке запроса) — iD магазина. Если не передать, берётся основной магазин инстанса.

Тело запроса (обязательное, JSON)

{
  "enabled": true,
  "webhookUrl": "https://webhook.albato.ru/wh/…",
  "webhookSecret": "0f5f2f2c2f0a4f9a8f1d6c3b7e2a9d40",
  "events": [
    "order.created",
    "order.paid",
    "order.status_changed"
  ]
}

Ответы

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

{
  "storeId": 0,
  "settings": {
    "enabled": true,
    "webhookUrl": "https://webhook.albato.ru/wh/…",
    "webhookSecretSet": true,
    "events": [
      "order.created",
      "order.paid",
      "order.status_changed"
    ],
    "configured": true
  }
}

400 Неверное тело: адрес не похож на URL, неизвестный код события или включение без адреса (webhookUrl is required when enabled is true).
401
403
404 Магазин не найден.
429
503

get/integrations/albato/access Состояние платной услуги

Доступ: только из панели магазина, по токену администратора. Связке Альбато этот метод недоступен.

Показывает, подключена ли магазину услуга Альбато. Метод работает и до подключения, поэтому с него начинают проверку.

Права сотрудника: «Просмотр настроек» (store.settings.read).

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

storeId (целое, необязательный, в строке запроса) — iD магазина. Если не передать, берётся основной магазин инстанса.

Ответы

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

{
  "storeId": 1,
  "enabled": true
}

401
403
404 Магазин не найден.
429
503

post/integrations/albato/test Отправить тестовое событие

Доступ: только из панели магазина, по токену администратора. Связке Альбато этот метод недоступен.

Синхронно отправляет на сохранённый адрес событие integration.test и возвращает ответ получателя. Ожидание ответа — до 10 секунд.

Права сотрудника: «Проверка настроек» (store.settings.test).

Код 200 у самого метода ещё не означает успех: смотрите поля success и statusCode. Тестовое событие не попадает в журнал доставок и не содержит полей заказа, поэтому для настройки полей связки оформите настоящий тестовый заказ.

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

storeId (целое, необязательный, в строке запроса) — iD магазина. Если не передать, берётся основной магазин инстанса.

Ответы

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

{
  "success": true,
  "statusCode": 200,
  "response": "ok",
  "url": "https://webhook.albato.ru/wh/…",
  "deliveryId": "11111111-1111-4111-8111-111111111111"
}

400 Адрес не задан или отправка выключена: webhook is not configured or disabled for this store.
401
403
404 Магазин не найден.
429
503

post/integrations/albato/token Выпустить API-токен

Доступ: только из панели магазина, по токену администратора. Связке Альбато этот метод недоступен.

Создаёт токен для сценария Альбато. Значение токена возвращается только в этом ответе: в базе хранится его отпечаток.

Права сотрудника: «Изменение настроек» (store.settings.update) и все права, которые выдаются токену.

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

storeId (целое, необязательный, в строке запроса) — iD магазина. Если не передать, берётся основной магазин инстанса.

Тело запроса (обязательное, JSON)

{
  "caption": "Альбато — чтение заказов",
  "sections": "[{\"name\":\"orders\"}]",
  "expiresAt": "2027-01-01T00:00:00Z"
}

Ответы

201 Объект создан.

{
  "id": 8,
  "caption": "Альбато — чтение заказов",
  "sections": "[{\"name\":\"orders\"}]",
  "storeId": 1,
  "createdAt": "2026-09-19T09:00:00Z",
  "expiresAt": null,
  "token": "6f1c2b0e8a4d4e7b9c1a2f3e4d5c6b7a…"
}

400 Неверные права в sections или дата expiresAt в прошлом.
401
403
404 Магазин не найден.
429
503

delete/integrations/albato/token Отозвать API-токен

Доступ: только из панели магазина, по токену администратора. Связке Альбато этот метод недоступен.

Отзывает токен. Со следующего запроса API отвечает по нему 401. Вернуть токен нельзя, для восстановления связки выпустите новый.

Права сотрудника: «Изменение настроек» (store.settings.update). Отзыв работает и при отключённой услуге.

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

id (целое, обязательный, в строке запроса) — iD токена из списка tokens.
storeId (целое, необязательный, в строке запроса) — iD магазина. Если не передать, берётся основной магазин инстанса.

Ответы

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

{
  "success": true
}

400 Не передан или неверный id.
401
403
404 Токен не найден или уже отозван.
429
503

Заказы

событиеorder.created Новый заказ

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Заказ оформлен на сайте, в боте Telegram или MAX, создан в панели или через API.

Не отправляется, если оформление сорвалось, например не удалось забронировать интервал доставки. Заказы Яндекс Маркета и заказы, созданные записью на услугу, это событие не создают.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "order.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "order": {
    "id": 123,
    "status": 0,
    "total": 1175,
    "currency": "RUB",
    "source": "web",
    "storeId": 1,
    "clientId": 45,
    "createdAt": "2026-09-15T10:00:00Z",
    "contactName": "Тестовый покупатель",
    "contactPhone": "+79990000001",
    "email": "order@example.invalid",
    "comment": "Позвонить перед доставкой",
    "items": [
      {
        "id": 301,
        "goodId": 10,
        "name": "Футболка",
        "article": "SHIRT-M",
        "type": "physical",
        "quantity": 2,
        "price": 500,
        "total": 1000,
        "currency": "RUB",
        "options": [
          {
            "groupId": 1,
            "groupCaption": "Размер",
            "valueId": 2,
            "valueCaption": "M"
          }
        ],
        "optionsJson": "[{\"groupId\":1,\"groupCaption\":\"Размер\",\"valueId\":2,\"valueCaption\":\"M\"}]"
      }
    ],
    "payment": {
      "id": 2,
      "name": "При получении",
      "method": null,
      "paid": false,
      "status": "unpaid",
      "fee": 0
    },
    "delivery": {
      "typeId": 3,
      "type": "courier",
      "name": "Курьер",
      "kind": "courier",
      "provider": null,
      "price": 100,
      "includedValue": 100,
      "priceStatus": "calculated",
      "paymentMode": "included",
      "address": "Тестовая улица, 10",
      "date": "2026-09-20",
      "slotFrom": "10:00:00",
      "slotTo": "12:00:00",
      "pickupPoint": null
    },
    "discounts": {
      "promo": 50,
      "promoCode": "WELCOME",
      "referral": 25,
      "bonusPointsUsed": 50,
      "manual": 50,
      "total": 175
    }
  }
}

событиеorder.status_changed Изменение статуса заказа

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Заказ подтвердили, перевели в другой статус или выполнили — в панели или через API.

Автоматический перевод в «В обработке» после оплаты через Telegram отправляет только «Оплата заказа».

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "order.status_changed",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "order": {
    "id": 123,
    "status": 0,
    "total": 1175,
    "currency": "RUB",
    "source": "web",
    "storeId": 1,
    "clientId": 45,
    "createdAt": "2026-09-15T10:00:00Z",
    "contactName": "Тестовый покупатель",
    "contactPhone": "+79990000001",
    "email": "order@example.invalid",
    "comment": "Позвонить перед доставкой",
    "items": [
      {
        "id": 301,
        "goodId": 10,
        "name": "Футболка",
        "article": "SHIRT-M",
        "type": "physical",
        "quantity": 2,
        "price": 500,
        "total": 1000,
        "currency": "RUB",
        "options": [
          {
            "groupId": 1,
            "groupCaption": "Размер",
            "valueId": 2,
            "valueCaption": "M"
          }
        ],
        "optionsJson": "[{\"groupId\":1,\"groupCaption\":\"Размер\",\"valueId\":2,\"valueCaption\":\"M\"}]"
      }
    ],
    "payment": {
      "id": 2,
      "name": "При получении",
      "method": null,
      "paid": false,
      "status": "unpaid",
      "fee": 0
    },
    "delivery": {
      "typeId": 3,
      "type": "courier",
      "name": "Курьер",
      "kind": "courier",
      "provider": null,
      "price": 100,
      "includedValue": 100,
      "priceStatus": "calculated",
      "paymentMode": "included",
      "address": "Тестовая улица, 10",
      "date": "2026-09-20",
      "slotFrom": "10:00:00",
      "slotTo": "12:00:00",
      "pickupPoint": null
    },
    "discounts": {
      "promo": 50,
      "promoCode": "WELCOME",
      "referral": 25,
      "bonusPointsUsed": 50,
      "manual": 50,
      "total": 175
    },
    "previousStatus": 0,
    "statusChangedAt": "2026-09-19T12:30:00+03:00"
  }
}

событиеorder.paid Оплата заказа

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Оплату подтвердили ЮKassa, Яндекс Пэй или Telegram либо сотрудник поставил отметку об оплате.

Снятие отметки об оплате события не создаёт.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "order.paid",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "order": {
    "id": 123,
    "status": 0,
    "total": 1175,
    "currency": "RUB",
    "source": "web",
    "storeId": 1,
    "clientId": 45,
    "createdAt": "2026-09-15T10:00:00Z",
    "contactName": "Тестовый покупатель",
    "contactPhone": "+79990000001",
    "email": "order@example.invalid",
    "comment": "Позвонить перед доставкой",
    "items": [
      {
        "id": 301,
        "goodId": 10,
        "name": "Футболка",
        "article": "SHIRT-M",
        "type": "physical",
        "quantity": 2,
        "price": 500,
        "total": 1000,
        "currency": "RUB",
        "options": [
          {
            "groupId": 1,
            "groupCaption": "Размер",
            "valueId": 2,
            "valueCaption": "M"
          }
        ],
        "optionsJson": "[{\"groupId\":1,\"groupCaption\":\"Размер\",\"valueId\":2,\"valueCaption\":\"M\"}]"
      }
    ],
    "payment": {
      "id": 2,
      "name": "При получении",
      "method": null,
      "paid": false,
      "status": "unpaid",
      "fee": 0
    },
    "delivery": {
      "typeId": 3,
      "type": "courier",
      "name": "Курьер",
      "kind": "courier",
      "provider": null,
      "price": 100,
      "includedValue": 100,
      "priceStatus": "calculated",
      "paymentMode": "included",
      "address": "Тестовая улица, 10",
      "date": "2026-09-20",
      "slotFrom": "10:00:00",
      "slotTo": "12:00:00",
      "pickupPoint": null
    },
    "discounts": {
      "promo": 50,
      "promoCode": "WELCOME",
      "referral": 25,
      "bonusPointsUsed": 50,
      "manual": 50,
      "total": 175
    },
    "paid": true
  }
}

событиеorder.cancelled Отмена заказа

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Заказ отменили в панели или через API. Запрос клиента на отмену сам по себе события не создаёт.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "order.cancelled",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "order": {
    "id": 123,
    "status": 0,
    "total": 1175,
    "currency": "RUB",
    "source": "web",
    "storeId": 1,
    "clientId": 45,
    "createdAt": "2026-09-15T10:00:00Z",
    "contactName": "Тестовый покупатель",
    "contactPhone": "+79990000001",
    "email": "order@example.invalid",
    "comment": "Позвонить перед доставкой",
    "items": [
      {
        "id": 301,
        "goodId": 10,
        "name": "Футболка",
        "article": "SHIRT-M",
        "type": "physical",
        "quantity": 2,
        "price": 500,
        "total": 1000,
        "currency": "RUB",
        "options": [
          {
            "groupId": 1,
            "groupCaption": "Размер",
            "valueId": 2,
            "valueCaption": "M"
          }
        ],
        "optionsJson": "[{\"groupId\":1,\"groupCaption\":\"Размер\",\"valueId\":2,\"valueCaption\":\"M\"}]"
      }
    ],
    "payment": {
      "id": 2,
      "name": "При получении",
      "method": null,
      "paid": false,
      "status": "unpaid",
      "fee": 0
    },
    "delivery": {
      "typeId": 3,
      "type": "courier",
      "name": "Курьер",
      "kind": "courier",
      "provider": null,
      "price": 100,
      "includedValue": 100,
      "priceStatus": "calculated",
      "paymentMode": "included",
      "address": "Тестовая улица, 10",
      "date": "2026-09-20",
      "slotFrom": "10:00:00",
      "slotTo": "12:00:00",
      "pickupPoint": null
    },
    "discounts": {
      "promo": 50,
      "promoCode": "WELCOME",
      "referral": 25,
      "bonusPointsUsed": 50,
      "manual": 50,
      "total": 175
    },
    "previousStatus": 0,
    "cancelledAt": "2026-09-19T12:30:00+03:00"
  }
}

Клиенты и сообщения

событиеclient.created Новый клиент

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

В магазине появился клиент: его создали в панели или через API, он зарегистрировался на сайте, впервые зашёл на сайт, впервые написал боту Telegram или MAX либо открыл мини-приложение.

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

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "client.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "client": {
    "id": 1542,
    "storeId": 1,
    "caption": "Иван Петров",
    "firstName": "Иван",
    "lastName": "Петров",
    "middleName": null,
    "phone": "+79991234567",
    "email": "ivan@example.com",
    "source": "manual",
    "externalId": "CRM-778",
    "externalSource": "amocrm",
    "createdAt": "2026-09-16T10:15:30Z",
    "updatedAt": "2026-09-16T10:15:30Z"
  }
}

событиеclient.updated Изменение клиента

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

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

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

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "client.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "client": {
    "id": 1542,
    "storeId": 1,
    "caption": "Иван Петров",
    "firstName": "Иван",
    "lastName": "Петров",
    "middleName": null,
    "phone": "+79991234567",
    "email": "ivan@example.com",
    "source": "manual",
    "externalId": "CRM-778",
    "externalSource": "amocrm",
    "createdAt": "2026-09-16T10:15:30Z",
    "updatedAt": "2026-09-16T10:15:30Z"
  }
}

событиеmessage.received Входящее сообщение

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Клиент написал боту в Telegram или MAX, включая команду /start и ответы на вопросы сценария.

Нажатия кнопок, кнопка «Начать» в MAX, сообщения сотрудников, ответы сценариев и рассылки события не создают, поэтому связка «клиент написал → ответить» не зациклится.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "message.received",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "message": {
    "id": 90211,
    "clientId": 1541,
    "text": "Когда доставка?",
    "type": "text",
    "platform": "telegram",
    "botId": 3
  }
}

Товары и остатки

событиеgood.created Новый товар

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Товар создали в карточке панели или через API.

Импорт каталога из файла событий не создаёт.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "good.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "good": {
    "id": 42,
    "storeId": 1,
    "caption": "Футболка базовая",
    "article": "TS-001",
    "otherId": "1C-000123",
    "price": 1790,
    "type": "physical"
  }
}

событиеgood.updated Изменение товара

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

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

Если связка по этому событию сама вызывает изменение товара, она зациклится.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "good.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "good": {
    "id": 42,
    "storeId": 1,
    "caption": "Футболка базовая",
    "article": "TS-001",
    "otherId": "1C-000123",
    "price": 1790,
    "type": "physical"
  }
}

событиеgood.deleted Удаление товара

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Товар удалили в панели или через API. Для вариантов удалённого товара отдельных событий нет.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "good.deleted",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "good": {
    "id": 42
  }
}

событиеstock.changed Изменение остатков

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Остаток изменился: резерв при оформлении заказа, пересчёт состава, возврат при отмене, приход или списание на вкладке «Склад» либо корректировка через API.

При оплате и выполнении заказа остаток не меняется, поэтому событий нет. Остаток, заданный при создании или изменении товара, и импорт каталога событий не создают.

Для синхронизации используйте stockQtyAfter, а не прибавляйте delta: при повторной доставке разница применится дважды.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "stock.changed",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "stock": {
    "goodId": 42,
    "article": "SKU-42",
    "delta": -2,
    "stockQtyBefore": 10,
    "stockQtyAfter": 8,
    "reason": "order_created",
    "movementId": 1234,
    "orderId": 122
  }
}

событиеstock.low Малый остаток

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Остаток перешёл из состояния «выше порога» в «равен порогу или ниже». Порог задаётся в карточке товара и должен быть больше нуля.

Дальнейшие списания ниже порога событие не повторяют. После пополнения выше порога следующее пересечение снова его создаст.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "stock.low",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "stock": {
    "goodId": 42,
    "caption": "Футболка базовая",
    "article": "SKU-42",
    "stockQty": 2,
    "lowStockThreshold": 3,
    "delta": -2,
    "stockQtyBefore": 4,
    "reason": "order_created",
    "movementId": 1235,
    "orderId": 123
  }
}

Исполнители и записи

событиеperformer.created Новый исполнитель

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Исполнителя добавили в панели или через API.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "performer.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "performer": {
    "id": 12,
    "storeId": 1,
    "fullName": "Анна Иванова",
    "phone": "+79990001122",
    "email": "anna@example.com"
  }
}

событиеperformer.updated Изменение исполнителя

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Данные исполнителя изменили. Событие уходит после каждого сохранения.

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

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "performer.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "performer": {
    "id": 12,
    "storeId": 1,
    "fullName": "Анна Иванова",
    "phone": "+79990001122",
    "email": "anna@example.com"
  }
}

событиеperformer.deleted Удаление исполнителя

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Исполнителя удалили. Его записи при этом не отменяются.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "performer.deleted",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "performer": {
    "id": 12
  }
}

событиеabsence.created Новое отсутствие исполнителя

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Исполнителю добавили отсутствие: отпуск, больничный или другой перерыв.

Если отсутствие добавили с отменой пересекающихся записей, по каждой записи сначала приходит «Отмена записи», а затем это событие.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "absence.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "absence": {
    "id": 41,
    "performerId": 12,
    "startAt": "2026-10-02T00:00:00Z",
    "endAt": "2026-10-03T00:00:00Z",
    "reason": "Больничный"
  }
}

событиеabsence.deleted Удаление отсутствия

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Отсутствие удалили. Записи, отменённые при его создании, не восстанавливаются.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "absence.deleted",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "absence": {
    "id": 41,
    "performerId": 12
  }
}

событиеbooking.created Новая запись на услугу

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Клиент записался на услугу на витрине. Событие приходит сразу после оформления, в том числе для записи со статусом pending_payment.

Запись, созданную сотрудником в панели, это событие не описывает: отдельного метода создания записи в API нет.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "booking.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "booking": {
    "id": 501,
    "storeId": 1,
    "status": "confirmed",
    "serviceMode": "on_site",
    "goodId": 310,
    "goodName": "Стрижка",
    "performerId": 12,
    "performerName": "Анна Иванова",
    "startAt": "2026-09-20T07:00:00+00:00",
    "endAt": "2026-09-20T08:00:00+00:00",
    "dueBy": null,
    "timezone": "Europe/Moscow",
    "clientId": 777,
    "clientName": "Мария",
    "clientPhone": "+79991234567",
    "clientEmail": "maria@example.com",
    "locationId": 3,
    "locationName": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "clientNotes": "",
    "orderId": 9001,
    "orderCompositionId": 12001,
    "price": 1500,
    "quantity": 1,
    "total": 1500,
    "currency": "RUB",
    "orderTotal": 1500,
    "paid": false,
    "prepaidAmount": 0,
    "paymentMethod": null,
    "cancellationReason": "",
    "confirmedAt": "2026-09-16T10:15:30Z",
    "completedAt": null,
    "cancelledAt": null,
    "createdAt": "2026-09-16T09:00:00Z",
    "updatedAt": "2026-09-16T10:15:30Z"
  }
}

событиеbooking.confirmed Подтверждение записи

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Запись подтвердили в панели или через API.

Перевод записи из «Ожидает оплаты» в рабочий статус после оплаты события не создаёт.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "booking.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "booking": {
    "id": 501,
    "storeId": 1,
    "status": "confirmed",
    "serviceMode": "on_site",
    "goodId": 310,
    "goodName": "Стрижка",
    "performerId": 12,
    "performerName": "Анна Иванова",
    "startAt": "2026-09-20T07:00:00+00:00",
    "endAt": "2026-09-20T08:00:00+00:00",
    "dueBy": null,
    "timezone": "Europe/Moscow",
    "clientId": 777,
    "clientName": "Мария",
    "clientPhone": "+79991234567",
    "clientEmail": "maria@example.com",
    "locationId": 3,
    "locationName": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "clientNotes": "",
    "orderId": 9001,
    "orderCompositionId": 12001,
    "price": 1500,
    "quantity": 1,
    "total": 1500,
    "currency": "RUB",
    "orderTotal": 1500,
    "paid": false,
    "prepaidAmount": 0,
    "paymentMethod": null,
    "cancellationReason": "",
    "confirmedAt": "2026-09-16T10:15:30Z",
    "completedAt": null,
    "cancelledAt": null,
    "createdAt": "2026-09-16T09:00:00Z",
    "updatedAt": "2026-09-16T10:15:30Z"
  }
}

событиеbooking.completed Завершение записи

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Запись отметили завершённой.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "booking.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "booking": {
    "id": 501,
    "storeId": 1,
    "status": "confirmed",
    "serviceMode": "on_site",
    "goodId": 310,
    "goodName": "Стрижка",
    "performerId": 12,
    "performerName": "Анна Иванова",
    "startAt": "2026-09-20T07:00:00+00:00",
    "endAt": "2026-09-20T08:00:00+00:00",
    "dueBy": null,
    "timezone": "Europe/Moscow",
    "clientId": 777,
    "clientName": "Мария",
    "clientPhone": "+79991234567",
    "clientEmail": "maria@example.com",
    "locationId": 3,
    "locationName": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "clientNotes": "",
    "orderId": 9001,
    "orderCompositionId": 12001,
    "price": 1500,
    "quantity": 1,
    "total": 1500,
    "currency": "RUB",
    "orderTotal": 1500,
    "paid": false,
    "prepaidAmount": 0,
    "paymentMethod": null,
    "cancellationReason": "",
    "confirmedAt": "2026-09-16T10:15:30Z",
    "completedAt": null,
    "cancelledAt": null,
    "createdAt": "2026-09-16T09:00:00Z",
    "updatedAt": "2026-09-16T10:15:30Z"
  }
}

событиеbooking.cancelled Отмена записи

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Запись отменил магазин — в панели, через API или добавлением отсутствия с отменой записей — либо клиент на витрине.

Отмена из-за неоплаты, истёкшего срока оплаты и отмена записей вместе с заказом событий не создают.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "booking.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "booking": {
    "id": 501,
    "storeId": 1,
    "status": "confirmed",
    "serviceMode": "on_site",
    "goodId": 310,
    "goodName": "Стрижка",
    "performerId": 12,
    "performerName": "Анна Иванова",
    "startAt": "2026-09-20T07:00:00+00:00",
    "endAt": "2026-09-20T08:00:00+00:00",
    "dueBy": null,
    "timezone": "Europe/Moscow",
    "clientId": 777,
    "clientName": "Мария",
    "clientPhone": "+79991234567",
    "clientEmail": "maria@example.com",
    "locationId": 3,
    "locationName": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "clientNotes": "",
    "orderId": 9001,
    "orderCompositionId": 12001,
    "price": 1500,
    "quantity": 1,
    "total": 1500,
    "currency": "RUB",
    "orderTotal": 1500,
    "paid": false,
    "prepaidAmount": 0,
    "paymentMethod": null,
    "cancellationReason": "",
    "confirmedAt": "2026-09-16T10:15:30Z",
    "completedAt": null,
    "cancelledAt": null,
    "createdAt": "2026-09-16T09:00:00Z",
    "updatedAt": "2026-09-16T10:15:30Z"
  }
}

событиеbooking.no_show Неявка клиента

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Запись отметили как неявку.

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "booking.created",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "booking": {
    "id": 501,
    "storeId": 1,
    "status": "confirmed",
    "serviceMode": "on_site",
    "goodId": 310,
    "goodName": "Стрижка",
    "performerId": 12,
    "performerName": "Анна Иванова",
    "startAt": "2026-09-20T07:00:00+00:00",
    "endAt": "2026-09-20T08:00:00+00:00",
    "dueBy": null,
    "timezone": "Europe/Moscow",
    "clientId": 777,
    "clientName": "Мария",
    "clientPhone": "+79991234567",
    "clientEmail": "maria@example.com",
    "locationId": 3,
    "locationName": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "clientNotes": "",
    "orderId": 9001,
    "orderCompositionId": 12001,
    "price": 1500,
    "quantity": 1,
    "total": 1500,
    "currency": "RUB",
    "orderTotal": 1500,
    "paid": false,
    "prepaidAmount": 0,
    "paymentMethod": null,
    "cancellationReason": "",
    "confirmedAt": "2026-09-16T10:15:30Z",
    "completedAt": null,
    "cancelledAt": null,
    "createdAt": "2026-09-16T09:00:00Z",
    "updatedAt": "2026-09-16T10:15:30Z"
  }
}

событиеbooking.rescheduled Перенос записи

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Клиент перенёс запись на витрине. Перенос создаёт новую запись, и событие описывает именно её: прежняя запись указана в rescheduledFromBookingId.

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

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "booking.rescheduled",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "booking": {
    "id": 501,
    "storeId": 1,
    "status": "confirmed",
    "serviceMode": "on_site",
    "goodId": 310,
    "goodName": "Стрижка",
    "performerId": 12,
    "performerName": "Анна Иванова",
    "startAt": "2026-09-20T07:00:00+00:00",
    "endAt": "2026-09-20T08:00:00+00:00",
    "dueBy": null,
    "timezone": "Europe/Moscow",
    "clientId": 777,
    "clientName": "Мария",
    "clientPhone": "+79991234567",
    "clientEmail": "maria@example.com",
    "locationId": 3,
    "locationName": "Салон на Ленина",
    "address": "ул. Ленина, 1",
    "clientNotes": "",
    "orderId": 9001,
    "orderCompositionId": 12001,
    "price": 1500,
    "quantity": 1,
    "total": 1500,
    "currency": "RUB",
    "orderTotal": 1500,
    "paid": false,
    "prepaidAmount": 0,
    "paymentMethod": null,
    "cancellationReason": "",
    "confirmedAt": "2026-09-16T10:15:30Z",
    "completedAt": null,
    "cancelledAt": null,
    "createdAt": "2026-09-16T09:00:00Z",
    "updatedAt": "2026-09-16T10:15:30Z",
    "rescheduledFromBookingId": 0,
    "previousStartAt": "2026-09-19T12:30:00+03:00",
    "previousEndAt": "2026-09-19T12:30:00+03:00",
    "previousPerformerId": 0
  }
}

Остальные события

событиеintegration.test Тестовое событие

Запрос: POST на адрес вебхука, указанный на вкладке «Альбато».

Отправляется кнопкой «Отправить тестовое событие» на вкладке «Альбато». Проверяет адрес и доступность получателя.

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

Одно событие может прийти дважды, поэтому отсеивайте повторы по deliveryId.

Заголовки запроса

X-Webhook-Event (строка, обязательный, заголовок) — код события, например order.created.
X-Webhook-Delivery (строка, обязательный, заголовок) — iD доставки, то же значение, что в поле deliveryId. При повторной попытке не меняется.
X-Webhook-Signature (строка, обязательный, заголовок) — подпись тела: sha256= и HMAC-SHA256 от тела запроса с ключом-секретом, в шестнадцатеричном виде.

Тело запроса

{
  "event": "integration.test",
  "deliveryId": "5b0e7a2c-3f1d-4c8e-9a6b-1d2e3f4a5b6c",
  "timestamp": "2026-09-19T12:30:00+03:00",
  "integration": {
    "storeId": 1,
    "message": "test delivery from shop backend"
  }
}