# Сценарии для commerce API: семь проектов, которые не сделать виджетом

> Когда виджет-витрина не подходит по форме: встроенная коммерция в SaaS, каталог на нескольких поверхностях, white-label магазины, собственный UX, ИИ-агенты, свой BI. Плюс примеры кода из JS SDK Shoprocket.

Ryan Badger - 4 августа 2025 г. - 5 мин чтения

## Для чего нужен e-commerce API для встраивания

Большинство платформ для e-commerce дают вам виджет. Вставляете скрипт, получаете витрину. Для 95% магазинов этого достаточно.

Commerce API - это то, к чему вы обращаетесь, когда хотите сделать то, чего виджет не умеет: показать товары внутри собственного интерфейса, встроить оформление заказа в панель SaaS, распространить каталог на несколько поверхностей (веб + мобильное приложение + голос) или построить собственные сценарии покупки, которых нет ни в одной платформе из коробки.

Shoprocket предлагает оба варианта. [Виджет](https://v3.shoprocket.io/ru/blog/headless-commerce-the-three-tiers-the-real-options-and-which-one-you-probably-actually-want.md) - вариант по умолчанию. [SDK `@shoprocket/core`](https://github.com/shoprocket/shoprocket-js) нужен, когда вы переросли виджет или он вам никогда не был нужен.

## Сценарии, где нужен API, а не виджет

Это ситуации, где виджета недостаточно. Если ваша идея в этом списке, вы на территории API.

### 1. Коммерция внутри вашего SaaS-продукта

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

Виджет здесь не подходит по форме: он ничего не знает о ваших пользователях, не соответствует вашей дизайн-системе и предполагает витрину на всю страницу. API позволяет отрисовать карточки товаров вашими компонентами, вызвать `cart.addItem()` по нажатию кнопки и открыть собственную панель оформления заказа (или перенаправить на размещённое оформление, если хотите отложить работу по соответствию требованиям).

```
import { ShoprocketCore } from '@shoprocket/core'

const sr = new ShoprocketCore({ publicKey: 'pk_...' })

// Отрисовать плитки дополнений внутри панели вашего SaaS
const addons = await sr.products.list({ category: 'addons' })

// Пользователь нажимает кнопку // User clicks "Add credits" buttonquot;Добавить кредиты// User clicks "Add credits" buttonquot;
await sr.cart.addItem(addon.id, 1)
```

### 2. Каталог на нескольких поверхностях (веб + нативное приложение + голос + чат)

Один каталог товаров, в каждом месте отображаемый по-своему. Веб-витрина показывает полное описание товара, нативное приложение для iOS - компактный список, голосовой помощник описывает товары вслух, интеграция с чатом отвечает ссылкой, по которой можно купить.

Все четыре поверхности обращаются к одному и тому же API. Когда вы меняете цену товара в панели Shoprocket, каждая поверхность отражает это при следующем запросе. Никакой синхронизации контента по каждой поверхности.

### 3. White-label и партнёрские витрины

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

Сайт каждого партнёра работает на вашем фреймворке, но обращается к commerce API со своим `publicKey`. Их товары, их заказы, их выплаты - всё разграничено по аккаунтам. Виджет не мешает их брендингу.

### 4. Полностью собственный пользовательский опыт покупателя

Интерактивные конфигураторы товаров (сборка ПК на заказ, персонализированные украшения, мебель под заказ). 3D-просмотр товаров. Фотогалереи «купи интерьер», где клик по пикселям на изображении добавляет товар в корзину. Кнопки быстрого повторного заказа внутри письма.

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

### 5. ИИ-агенты и агентная коммерция

ИИ-агент (ChatGPT, Claude, собственный агент), который может просматривать товары и совершать покупки от имени пользователя. Агенту нужен программный доступ к вашему каталогу и корзине, а не DOM-виджет, который приходится разбирать.

Shoprocket предоставляет фиды для протоколов ИИ-коммерции наряду со стандартным доступом по API. Агент, которого спросили «что есть в наличии дешевле $50 с бесплатной доставкой», получает структурированный ответ, а не скрейпинг экрана.

### 6. Встроенная коммерция в инструментах для контента

Страница в Notion, где блоки можно купить. Дизайн во Framer с горячими точками для покупки по клику. Инструмент рассылок, где подписчики могут нажать на карточку товара и заплатить, не выходя из письма. Всё это строится поверх API.

### 7. Собственная отчётность и BI-панели

Панель Shoprocket показывает выручку, конверсию, главные товары. Чего она не показывает - *ваши* собственные метрики: пожизненная ценность по когортам покупателей, заказы по источникам рекомендаций, маржа после себестоимости у поставщика. API отдаёт данные о заказах и покупателях, чтобы вы могли направить их в собственный BI-инструмент, таблицу или внутреннюю панель.

## Что SDK даёт сегодня

Из `@shoprocket/core`:

```
// Products
sr.products.list({ limit, offset, sort, category })
sr.products.get(productId)

// Корзина
sr.cart.get()
sr.cart.addItem(productId, quantity)
sr.cart.updateItem(itemId, quantity)
sr.cart.removeItem(itemId)

// Сессия
sr.session.create()
sr.setSessionToken(token)
```

Плюс полный REST API для всего, что SDK пока не оборачивает (заказы, покупатели, скидки, запись товаров). Полную справку смотрите на [api.shoprocket.io/docs](https://api.shoprocket.io/docs).

## Где подход «API прежде всего» - ошибка

Несколько случаев, когда правильный выбор - виджет, а API избыточен:

- **Простая витрина с 10-200 товарами.** Виджет отрисовывает это отлично; писать собственный интерфейс каталога - переделывать уже решённую работу.
- **У вас нет выделенных мощностей фронтенд-разработки.** Подход «API прежде всего» требует выпускать и поддерживать собственные состояния загрузки, интерфейс вариантов, обработку ошибок, доступность, i18n для 21 языка. Это недели работы, которые виджет даёт бесплатно.
- **Для вас главное - скорость запуска.** Виджет - это минуты; «API прежде всего» - минимум недели.

По умолчанию выбирайте виджет. Обращайтесь к API, когда упрётесь в то, чего виджет не умеет.

## Реалистичный первый проект

Самый частый проект «мне нужен API»: SaaS-продукт, который хочет продавать кредиты, подписки или разовые дополнения внутри собственной панели.

Порядок действий:

1. Установите `@shoprocket/core` во фронтенд
2. Создайте в Shoprocket категорию «Дополнения» или похожую
3. Добавьте товары с нужными ценами и описаниями
4. Отобразите список товаров в панели с помощью собственной библиотеки компонентов
5. По нажатию добавьте в корзину и перенаправьте на размещённое оформление заказа Shoprocket (или встройте оформление прямо в страницу, если готовы к дополнительной работе)
6. Настройте endpoint вебхука для получения событий `order.paid`, чтобы выдать то, что открывает покупка (кредиты, доступ, отправку)

Вот и всё. Несколько файлов, день работы для того, кто привык вызывать API. Без виджета, без iframe, без компромиссов в интерфейсе вашего продукта.

## Чего мы не рекомендуем

Не пересобирайте интерфейс полного каталога, близко повторяющий то, что виджет уже делает. Если вы неделями возитесь с «сеткой товаров с фильтрами и поиском», вы пишете то, что виджет даёт за минуты. Используйте виджет для такой формы, а API - для действительно других форм.

> **Совет:** если вы думаете об API-подходе, потому что стиль виджета по умолчанию не подходит вашему бренду, сначала попробуйте [хуки стилизации виджета](https://github.com/shoprocket/shoprocket-js). Виджет допускает гораздо больше настройки CSS, чем кажется. Полная пересборка на API - куда более тяжёлая работа.

## Коротко

- **Виджет** = вариант по умолчанию, подходит 95% магазинов
- **API / SDK** = когда виджет не подходит по форме (встроенная коммерция в SaaS, несколько поверхностей, white-label, собственный UX, ИИ-агенты, собственный BI)
- **Возможности SDK сегодня:** товары, корзина, сессии; плюс полный REST API для заказов / покупателей / скидок
- **Шаблон первого проекта:** панель SaaS, продающая кредиты или дополнения через SDK, с выдачей по вебхуку
- **Не пересобирайте на API** то, что виджет и так делает хорошо; выберите свою форму

[Начните бесплатный пробный период](https://app-v3.shoprocket.io/signup) и получите публичный ключ; SDK бесплатен на любом тарифе Shoprocket. 14 дней, без карты.

---

- HTML version: https://v3.shoprocket.io/ru/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget
- Language: Русский (ru)
- Also in: [العربية](https://v3.shoprocket.io/ar/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Deutsch](https://v3.shoprocket.io/de/blog/commerce-api-anwendungsfaelle-sieben-builds-ohne-widget.md), [Ελληνικά](https://v3.shoprocket.io/el/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [English](https://v3.shoprocket.io/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Español](https://v3.shoprocket.io/es/blog/casos-de-uso-api-de-comercio-siete-proyectos-que-un-widget-no-puede-hacer.md), [Français](https://v3.shoprocket.io/fr/blog/api-commerce-sept-cas-usage-impossibles-avec-un-widget.md), [עברית](https://v3.shoprocket.io/he/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [हिन्दी](https://v3.shoprocket.io/hi/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Bahasa Indonesia](https://v3.shoprocket.io/id/blog/kasus-penggunaan-commerce-api-tujuh-hal-yang-tidak-bisa-dilakukan-widget.md), [Italiano](https://v3.shoprocket.io/it/blog/api-commerce-sette-casi-duso-che-un-widget-non-copre.md), [日本語](https://v3.shoprocket.io/ja/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Lietuvių](https://v3.shoprocket.io/lt/tinklarastis/prekybos-api-panaudojimo-atvejai-septyni-sprendimai-kuriu-nepadarysite-su-valdykle.md), [Norsk](https://v3.shoprocket.io/nb/blogg/handels-api-sju-ting-du-ikke-kan-bygge-med-en-widget.md), [Nederlands](https://v3.shoprocket.io/nl/blog/commerce-api-use-cases-zeven-projecten-zonder-widget.md), [Polski](https://v3.shoprocket.io/pl/blog/api-do-e-commerce-siedem-zastosowan-ktorych-nie-zrobisz-widzetem.md), [Português](https://v3.shoprocket.io/pt/blog/casos-de-uso-api-de-commerce-sete-projetos-que-widget-nao-faz.md), [Română](https://v3.shoprocket.io/ro/blog/cazuri-de-utilizare-api-comert-sapte-proiecte-fara-widget.md), [ไทย](https://v3.shoprocket.io/th/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Türkçe](https://v3.shoprocket.io/tr/blog/commerce-api-kullanim-senaryolari-widget-ile-yapilamayan-yedi-proje.md), [中文](https://v3.shoprocket.io/zh/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md)