Инструменты и примеры

Файлы для интеграции​

• OpenAPI YAML — машиночитаемая схема публичных API-методов.
• OpenAPI viewer — чтение схемы в браузере.
• Postman collection — запросы со служебными значениями вместо данных production-клиентов.
• CSS-пример бейджа — необязательный вариант оформления для собственного интерфейса.

OpenAPI определяет публичные поля и обязательные параметры. Руководства описывают порядок интеграции и смысл ответов API.

Быстрая локальная проверка​

Для проверки первого запроса нужны curl и jq:

export SHOPSTORY_APPLICATION_ID="assigned-application-id"

curl --silent --show-error --get \
  "https://app.shopstory.live/v3/streams" \
  --data-urlencode "applicationId=${SHOPSTORY_APPLICATION_ID}" \
  --data-urlencode "limit=1" \
  | jq '{status, body}'

Сначала проверьте HTTP и JSON-контракт из терминала или с сервера клиента. Браузерный тест запускайте после регистрации origin.

Postman​

После импорта создайте локальное окружение:

Не публикуйте environment-файл и не записывайте в коллекцию cookies, пароли или access tokens. applicationId не является секретом. Реальные клиентские идентификаторы в общедоступном примере не нужны.

Автоматическая проверка клиента​

Автоматический contract test должен проверять:

1. Тело ответа содержит JSON с числовым полем status верхнего уровня.
2. Клиент различает транспортную HTTP-ошибку и бизнес-ошибку внутри конверта.
3. availableStreams и plannedStreams обрабатываются как массивы.
4. Пустая выдача отображается как отдельное состояние интерфейса.
5. Идентификаторы сохраняются строками.
6. Незнакомое необязательное поле не ломает десериализацию.
7. Timeout или недоступность ShopStory не блокируют основной интерфейс клиента.

В тестах используйте выданный тестовый контур или локальные fixtures. Не связывайте CI с конкретным production-эфиром или фиксированным количеством записей.

Проверка Mobile SDK​

Postman и OpenAPI проверяют HTTP-контракт. Нативную интеграцию проверяйте отдельно для версии пакета из integration handoff:

1. feedProductId остаётся строкой между каталогом мобильного приложения, SDK и commerce-системой.
2. SDK передаёт приложению типизированное product action с идентификатором выбранного товара.
3. Выбранное действие открывает native PDP либо, для прямой корзины, приложение проверяет актуальный остаток и изменяет корзину в системе ритейлера.
4. Состояние плеера и событие аналитики не определяют результат операции.
5. Ошибка SDK или commerce API не блокирует PDP, navigation и checkout.

Web callback(boolean) относится только к Web SDK. Mobile host получает типизированное действие. Его обработка описана в руководстве для соответствующей версии пакета. Координаты пакета, точная версия и клиентские routes остаются в handoff. Публичный контракт: Mobile SDK.

Проверка OpenAPI​

Подключите спецификацию к линтеру и генератору типов. После генерации клиента отдельно проверяйте body.status, no_active_stream и пустые массивы.

Подходящие инструменты:

• Redocly CLI — проверка и сборка OpenAPI;
• Spectral — правила схемы;
• Schemathesis — contract-based tests.

Закрепите версию генератора и проверяйте diff сгенерированного клиента при code review.

Данные для обращения​

В обращении на support@shopstory.live укажите:

• endpoint и очищенные query-параметры;
• HTTP-код и status из JSON;
• время с часовым поясом;
• URL страницы и origin для CORS-проблемы;
• браузер, ОС и короткие шаги воспроизведения.

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