<!-- Canonical: https://docs.shopstory.live/docs/reference/openapi -->

# OpenAPI и Postman

## Файлы

- [OpenAPI YAML](<https://docs.shopstory.live/downloads/public-openapi.yaml>) — схема публичных методов.
- [Postman collection](<https://docs.shopstory.live/examples/postman/ShopStory%20Public%20API.postman_collection.json>) — запросы и проверки ответов.
- [OpenAPI viewer](<https://docs.shopstory.live/swagger/>) — просмотр схемы в браузере.

В спецификации указаны структура ответов, обязательные поля и правила обработки ошибок:

- `/v3/streams` и `/v3/translation/quick-state` передают ошибки приложения внутри конверта при HTTP `200`;
- `/v2/mini-player/*` выставляет HTTP-код ошибки и повторяет его в поле `status`.

## Доступность товара и API остатков

`body.products[].feedProductAvailable` в ответе `GET /v3/streams` содержит булевый снимок доступности из фида. Он не передаёт количество единиц, остаток выбранного магазина или время обновления товара. `serverTime` — время ответа API.

Public API не вызывает stock API клиента и не содержит метода проверки текущего остатка: остаток по магазину — данные ритейлера, и запрашивает их его собственный код. В Web SDK это делает штатный обработчик наличия, при интеграции через Public API — интерфейс клиента. Контракт обработчика и приоритет источников описаны в разделе [Наличие товара и остатки](<https://docs.shopstory.live/docs/guide/product-availability>).

## Использование Postman

Переменные приложения, товара и эфира оставлены пустыми. Коллекция не содержит идентификаторов реальных клиентов или демонстрационных данных.

После импорта заполните:

| Переменная | Значение |
| --- | --- |
| `applicationId` | Идентификатор приложения, выданный ShopStory. |
| `feedProductId` | Строковый идентификатор тестового товара из согласованного фида. |
| `productCode` | Артикул товара, если для проекта согласован поиск по `vendorCode`. |
| `categoryId` | Категория из ответа `/v3/streams`, если проверяется фильтр. |
| `translationId` | Идентификатор тестового эфира. |

`applicationId` выбирает область данных и не авторизует запрос. Не добавляйте в публичную коллекцию токены, cookie, реквизиты фида или реальные пользовательские данные.

Перед запуском

Коллекция обращается к рабочему API в режиме чтения. Используйте только назначенное вам приложение и заранее согласованные тестовые данные.

## Связанные разделы

- [Quickstart](<https://docs.shopstory.live/docs/guide/quickstart>) — примеры первых запросов к API
- [Каталог эфиров](<https://docs.shopstory.live/docs/guide/catalog-streams>) — семантика фильтров и пагинации
- [Mini-player](<https://docs.shopstory.live/docs/guide/mini-player>) — состояния по товару и текущий live
- [Товарный фид](<https://docs.shopstory.live/docs/guide/feed-requirements>) — идентификаторы и снимок доступности