Как добавить рекомендации размеров через API

Большинство поставщиков рекомендаций размеров продают вам виджет, а не API. Если ваша витрина построена на заказ — независимый фронтенд электронной коммерции, нативное приложение или поток оформления заказа, который не терпит встроенный iframe — это проблема. В этой статье описывается форма интеграции, которая действительно работает: что отправлять, когда вызывать, как кэшировать и что делать при сбое.

Почему API-First важен для пользовательских витрин

Готовый виджет предполагает DOM, который вы не контролируете, и цикл отрисовки, которым вы не владеете. Независимые витрины, построенные на Next.js, Remix или оболочке нативного мобильного приложения, нуждаются в том, чтобы логика рекомендаций находилась внутри собственного дерева компонентов — что означает JSON-контракт, а не тег скрипта.

Практическое различие проявляется в трёх местах: бюджет задержки, владение состоянием и согласованность дизайна. API-вызов, который вы делаете сами, может быть распараллелен с другими получениями данных о продуктах, кэширован на периметре и стилизован с помощью вашей собственной библиотеки компонентов вместо внедрённого iframe. Это то же самое рассуждение, которое подталкивает команды к использованию моделей интеграции shopify с использованием нативных блоков приложений вместо встроенных фреймов — контроль над отрисовкой стоит дополнительных работ по интеграции.

Форма запроса и ответа

Вызов API рекомендаций размеров обычно требует трёх компонентов: идентификатор продукта (с таблицей размеров или метаданными одежды), сохранённые или сессионные измерения покупателя и предпочтение локали/единицы. Минимальное тело запроса выглядит так:

{
  "productId": "sku_48213",
  "measurements": {
    "heightCm": 172,
    "weightKg": 64,
    "fitPreference": "regular"
  },
  "unit": "metric"
}

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

{
  "recommended": "M",
  "alternatives": [
    { "size": "L", "confidence": 0.31 }
  ],
  "confidence": 0.87,
  "fallback": false
}

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

Когда вызывать конечную точку

Вызов при каждой загрузке страницы тратит впустую туда и обратно; вызов только при явном клике «найти мой размер» создает трение, которое покупатели не переносят. Золотая середина, которая лучше всего работает на практике: вызывайте один раз при монтировании страницы продукта, если профиль покупателя уже существует (возвращающийся посетитель, учетная запись входа или сохраненная сессия), и вызывайте снова только когда покупатель меняет измерения или переключается на другие продукты.

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

Стратегия кэширования

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

Кэширование на периметре по только productId (исключая измерения, специфичные для покупателя) работает, если ваша модель рекомендаций детерминирована с учётом входов — кэшируйте вычисления, а не идентичность покупателя. Если ваша конечная точка смешивает сигналы в реальном времени, такие как недавняя история возвратов, держите TTL короткими и рассматривайте кэш как буфер задержки, а не источник истины.

Конфиденциальность и обработка данных

Измерения тела чувствительны по любому разумному определению, даже когда покупатель добровольно вводит их для лучшей подгонки. Храните минимум необходимого — рост, вес и предпочтение подгонки обычно достаточны; вам редко нужно сохранять необработанные ответы на опросы или данные датчиков устройства. Предоставьте покупателям видимый способ очистить сохранённые измерения и не передавайте их аналитике третьих сторон или пиксельным объявлениям по умолчанию.

Это тема, которая заслуживает рассмотрения как первоклассный дизайн API, а не как приложение к обзору конфиденциальности. Наша статья по конфиденциальности данных о теле в Virtual Try-On охватывает конкретные ожидания, которые покупатели имеют, когда бренд просит измерения тела, что стоит прочитать перед окончательным утверждением вашей схемы запроса.

Изящные резервные варианты при отказе API или отсутствии данных

API-вызов может не пройти по обычным причинам — тайм-аут, холодный кэш или покупатель без истории измерений. Контракт ответа выше включает флаг fallback: true именно для этого случая; ваш фронтенд должен рассматривать это как «нет надежной рекомендации» вместо состояния ошибки.

Разумное поведение резервного варианта по порядку предпочтения:

• Если для продукта существует статическая таблица размеров, отрисуйте её вместо пустого слота рекомендаций.
• Если покупатель вообще не имеет измерений, запросите быстрый ввод из 2 полей (рост и одно предпочтение подгонки) вместо длинной формы.
• Если API истощается, не блокируйте кнопку добавления в корзину — деградируйте до таблицы размеров молча и регистрируйте сбой для мониторинга.

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

Обработка сложности мульти-бренда и мульти-систем размеров

Если ваша витрина охватывает несколько брендов или поставщиков, не предполагайте, что одна схема таблицы размеров подходит всем. Бренды регулярно маркируют одну и ту же одежду по-разному — размер US 8 от одного бренда может сидеть как US 6 от другого, что хорошо задокументировано в отрасли и является одной из более сложных проблем интеграции для пользовательских сборок. Ваш слой API должен использовать brandId или vendorId наряду с productId, чтобы механизм рекомендаций мог применять модели подгонки, специфичные для бренда, вместо единой глобальной кривой.

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

Где YourSizer подходит

Механизм рекомендаций YourSizer доступен как прямой API, а не только как упакованный виджет, специально для команд, создающих пользовательские витрины или нативные приложения. Контракт запроса/ответа следует форме, описанной выше: продукт и профиль покупателя входит, размер с рейтингом и оценка уверенности выходят, с явным флагом резервного варианта, поэтому ваш фронтенд никогда не должен угадывать, авторитетен ли ответ.

Данные измерений обрабатываются с ограничениями удержания и четкими путями удаления, а API поддерживает пакетные запросы для страниц со списками, поэтому вы не делаете один туда и обратно на карточку продукта. Команды интеграции обычно подключают её к существующему слою получения данных о продуктах — компоненты сервера Next.js, обработчик GraphQL или сервис продуктов нативного приложения — вместо добавления отдельного скрипта на стороне клиента, что сохраняет задержку и контроль дизайна в ваших руках.

Часто задаваемые вопросы

Нужен ли API рекомендаций размеров для измерений в реальном времени или он может использовать сохранённые данные профиля?

Оба работают, и большинство интеграций используют оба. Сохранённый профиль возвращающегося покупателя (рост, вес, предпочтение подгонки) — это основной вход, тогда как новый посетитель обычно вводит быструю оценку из двух полей, которая кэшируется в его сессии. API должен принимать оба пути через один объект measurements, поэтому вашему фронтенду не нужны отдельные ветви кода для новых и постоянных покупателей.

Чем это отличается от простого встраивания виджета рекомендации размеров?

Виджет владеет собственной отрисовкой, стилизацией и часто собственной границей iframe, что быстро интегрируется, но ограничивает контроль над макетом и производительностью страницы. API-first интеграция означает, что ваша команда полностью владеет пользовательским интерфейсом и потребляет логику рекомендаций только как данные, что является правильным компромиссом для независимых витрин, нативных приложений или брендов со строгими системами дизайна, где встроенный фрейм не подходит.

Что должно произойти, если API возвращает рекомендацию с низкой уверенностью?

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

Может ли API поддерживать несколько брендов с различными системами размеров в одной витрине?

Да, при условии, что запрос включает идентификатор бренда или поставщика наряду с ID продукта, так как модели подгонки должны быть осведомлены о бренде, а не глобальны. Рынки и мульти-брендовые розничные торговцы — это наиболее распространенный случай, когда это имеет значение — один ярлык «размер M» означает разные вещи у разных поставщиков, и хорошо спроектированный API это учитывает вместо усреднения.

Заключение

Создание рекомендаций размеров в пользовательской витрине — это в основном проблема дизайна интеграции, а не машинного обучения — сложные части — это форма контракта, границы кэширования и то, что происходит при отказе вызова. Сделайте это правильно, и уровень рекомендаций становится просто ещё одной зависимостью данных, которую ваш фронтенд обрабатывает с грацией, так же как уже обрабатывает API инвентаризации или цен. По мере того как больше электронной коммерции перемещается на независимые и нативные архитектуры, API-first инструменты подгонки, вероятно, станут ожиданием по умолчанию, а не исключением.