Изменения API
Что добавилось и изменилось в API v1.
Изменения обратно совместимы, если не сказано иначе. Новые поля в ответах появляются без предупреждения: не падайте на незнакомых ключах.
1 октября 2026
Статусы по ID. В заказе у status и paymentStatus появилось поле id.
PATCH /api/v1/orders/{id} принимает statusId и paymentStatusId вместо
системных кодов: так выставляются статусы, которые магазин создал сам, в том
числе через POST /api/v1/references/order-statuses. Код и ID одного статуса
вместе передавать нельзя, ответ 400. В GET /api/v1/orders добавлены фильтры
filter[statusId] и filter[paymentStatusId]: ID через запятую.
isActive способов оплаты и доставки. Работает как переключатель в
настройках магазина. Способ, доступный во всех магазинах владельца,
выключается во всех. Раньше PATCH с isActive: false такой способ не
выключал, хотя отвечал 200.
30 сентября 2026, вечер
Запись товаров. POST /api/v1/products создаёт товар,
PUT /api/v1/products/external/{externalId} создаёт или обновляет его по вашему
ID, PATCH и DELETE /api/v1/products/{id} меняют и удаляют. Ищут товар так же,
как GET: по ID, by=externalId или by=sku. Цены в копейках. Действует лимит
товаров тарифа: при превышении ответ 402. Занятый артикул или externalId
даёт 409. У вариантов через API меняются только price, stockQuantity и sku.
Право products:write.
Запись клиентов. POST /api/v1/customers находит клиента по telegramId,
телефону или email, как при создании заказа, и создаёт нового, только если
никого не нашёл: 201 для нового, 200 для найденного. PATCH и
DELETE /api/v1/customers/{id} меняют и удаляют клиента. Право customers:write.
Запись справочников. Новое право references:write. Статусы заказа и
оплаты, склады, способы оплаты и доставки создаются через POST и меняются
через PATCH /{id}. Появился справочник категорий товаров
GET /api/v1/references/categories, категории создаются и меняются через
PUT /api/v1/references/categories/external/{externalId}.
Способы оплаты и доставки в ответе на запись. В GET-списках isActive
по-прежнему всегда true. Ответ на PATCH показывает фактическое состояние,
в том числе false после выключения.
Незнакомые поля. Все новые методы записи отвечают 400 на поле, которого
нет в контракте, как PATCH /api/v1/orders/{id}.
30 сентября 2026
Ссылка на оплату через ProOnline. POST /api/v1/orders/{id}/payment-link
выдаёт ссылку через подключённый способ оплаты: PayAnyWay или анкету школы
ProOnline. Если у магазина подключены оба, передайте provider=payanyway или
provider=proonline. Без него ответ 409 с причиной provider_required. При
одном подключённом способе параметр не нужен.
28 сентября 2026, вечер
Telegram ID покупателя. В POST /api/v1/orders появилось поле
customer.telegramId: ID пользователя из Bot API строкой. Заказы с одним
Telegram ID попадают в одну карточку клиента, даже без телефона и email.
Раньше каждый такой заказ создавал нового клиента. В GET /api/v1/customers
добавлены поле telegramId и фильтр filter[telegramId]. PATCH /api/v1/orders/{id}
отвечает 400 на customer.telegramId и на незнакомые поля в customer.
Ошибки стали точнее. Некорректный id в GET и PATCH /api/v1/orders/{id}
отвечает 404, а не 500. Некорректная дата в filter[...][from|to]
отвечает 400. Сбой базы при записи отвечает 500 вместо 400, его можно
повторить. Неизвестный код статуса в PATCH теперь validation_error. Текст
внутренних ошибок базы в ответ больше не попадает.
PATCH отклоняет лишние поля. Раньше externalId или delivery.cost в
теле молча отбрасывались и ответ был 200. Теперь 400.
Лимиты. Не больше 200 позиций в заказе, тело запроса до 1 МБ, 20 запросов в секунду на все ключи магазина. Подробнее.
Ключ без orders:read. Повтор POST и PATCH отдают такому ключу только
id и externalId, без данных покупателя.
Отключение магазина. API перестаёт работать, если магазин или его владелец отключены. Раньше проверялся только тариф.
28 сентября 2026
Вебхуки приходят при любой смене. order.payment_status_changed теперь
отправляется и при онлайн-оплате, и при изменениях из Тильды, AI-ассистента и
возвратов. order.status_changed приходит и тогда, когда статус меняет
автоматизация. order.created приходит для заказов из всех источников.
Повтор POST /api/v1/orders не меняет заказ. Раньше параллельные запросы с
одним externalId могли перезаписать позиции. Теперь второй получает 200 и
заказ в исходном виде. Если externalId занят заказом из Тильды или созданным
вручную, ответ 409 с кодом conflict. Код conflict новый.
referralCode не мешает созданию. С неизвестным или неактивным кодом заказ
создаётся без партнёра. Раньше ответ был 400.
Справочники совпадают с тем, что принимает заказ. Способы оплаты и
доставки из /references/* всегда проходят в POST /api/v1/orders. Раньше
список показывал отключённые способы и скрывал доступные во всех магазинах
владельца.
delivery.includedInTotal. Показывает, входит ли доставка в
totalAmount. Если доставку оплачивает магазин, флаг false.
Название позиции на момент заказа. items[].name берётся из заказа, а не
из текущей карточки товара. Переименование товара больше не меняет старые
заказы.
27 сентября 2026
Вебхуки. События order.created, order.status_changed и
order.payment_status_changed приходят на ваш сервер POST-запросом с подписью
HMAC-SHA256. Подключаются в настройках магазина.
Подробнее.
Инкрементальная синхронизация. У заказов появилось поле updatedAt.
Списки заказов, товаров и клиентов принимают filter[updatedAt][from|to] и
сортировку order=updatedAt:asc. Подробнее.
Товары и клиенты. Новые методы GET /api/v1/products,
GET /api/v1/products/{id} (по ID, внешнему ID или артикулу),
GET /api/v1/customers и GET /api/v1/customers/{id}.
Позиции заказа по артикулу. В POST /api/v1/orders товар в позиции можно
указать через sku или externalProductId. Без unitPrice берётся цена из
каталога.
Права ключей. Права products:write и customers:write больше не
выдаются: методов записи для товаров и клиентов пока нет.
25 сентября 2026
referralCode в POST /api/v1/orders. Код партнёра, который покупатель
принёс до ухода на внешнюю оплату. Заказ засчитывается партнёру этого магазина.
14 сентября 2026
Скидки в заказе. Меняет смысл поля. items[].lineTotal теперь сумма строки
после скидки: quantity × unitPrice − discount. Раньше это было
quantity × unitPrice. Если вы сверяли lineTotal с ценой из каталога,
учитывайте items[].discount.
Новые поля: items[].discount, discountTotal, promoCode,
delivery.discount. Как складывается итог.
Июнь 2026
Первая версия API: заказы (список, получение, создание, изменение), справочники, проверка ключа.