Кастомные commerce-интеграции
ShopStory может подключить commerce-действия к API ритейлера. Такое подключение проектируется отдельно для каждого клиента. В стандартный Public API этот endpoint не входит.
Базовый сценарий
Без отдельной разработки ShopStory использует товарные данные из синхронизированного фида:
- идентификатор и URL товара;
- название, изображение и цена, если они переданы;
- признак доступности из последней успешно обработанной версии фида.
Фид показывает состояние товара на момент последней успешной синхронизации. Текущий остаток магазина перед покупкой проверяет система ритейлера.
Кнопка «Купить» по умолчанию открывает URL карточки товара. Для добавления без перехода Web SDK использует callback корзины, а Mobile SDK передаёт типизированное действие нативному приложению. В обоих случаях текущий остаток и результат cart-команды подтверждает система ритейлера.
Поверхности вызова
| Поверхность | Передача намерения | Подтверждение результата |
|---|---|---|
| Web SDK | Callback с feedProductId или согласованным vendorCode | Ритейлер вызывает callback(true) только после изменения корзины |
| Mobile SDK | Типизированное действие со строковым feedProductId | Приложение выполняет stock/cart flow и показывает результат в своём интерфейсе; состояние player не подтверждает изменение корзины |
Координаты пакета, exact version, сигнатуры конкретной версии и клиентские routes входят в закрытый integration handoff.
Когда нужна кастомная интеграция
Обычный Web callback или native cart-команда проверяют остаток внутри операции ритейлера. Эта server-side проверка входит в базовый cart contract. Отдельная оценка нужна, когда ShopStory должен вызвать самостоятельный API остатков, показать результат preflight-проверки до cart-команды или обратиться к нестандартному merchant API.
В таком контракте могут учитываться:
- актуальный остаток в системе ритейлера;
- выбранный магазин, регион или страну;
- способ получения или доставки;
- клиентскую сессию и авторизацию;
- фактический результат добавления в корзину;
- различающиеся правила для live и записи.
Граница ответственности
| ShopStory | Commerce-система клиента |
|---|---|
| Передаёт согласованный идентификатор товара и контекст действия | Сопоставляет товар со своим каталогом |
| На web ожидает callback; в Mobile передаёт типизированное действие host app | Определяет актуальную доступность, цену и способ получения |
| На web отображает результат callback; в Mobile оставляет подтверждение merchant UI | Выполняет добавление и возвращает результат в согласованную поверхность |
| Применяет согласованный тайм-аут и безопасный fallback | Управляет сессией, авторизацией, лимитами и защитой API |
Положительный результат нельзя выводить из HTTP 200 или наличия товара в фиде. Его должна подтвердить система, которая владеет корзиной и остатками.
Что согласуется до оценки
До оценки команда ShopStory готовит с клиентом закрытое техническое приложение:
- Стабильный товарный ID и правила сопоставления с
feedProductId. - Способ определения страны, региона, магазина и способа получения.
- API проверки остатка и API корзины либо единая атомарная команда корзины.
- Модель аутентификации и место выполнения вызова: браузер, приложение или сервер.
- Значения успешной операции, отсутствия товара, ошибки валидации, тайм-аута и временного сбоя.
- Ограничения частоты, тайм-аут, допустимая задержка и правила кеширования.
- Поведение интерфейса при недоступности commerce API.
- Тестовые данные, сценарии приёмки, порядок запуска и отката.
Точные URL, схемы запросов и ответов, учётные данные, лимиты, правила магазинов и SLA не публикуются. Они фиксируются в клиентском приложении к интеграции.