# 商务 API 的用例：七种小部件做不到的搭建 > 当店面小部件不是合适的形态时：SaaS 内嵌电商、多终端商品目录、白标店铺、自定义体验、AI 智能体、自定义 BI。附 Shoprocket JS SDK 的代码示例。 Ryan Badger - 2025年8月4日 - 阅读约 5 分钟 ## 用于嵌入的电商 API 是做什么的 大多数电商平台给你的是一个小部件。粘贴一段脚本，就得到一个店面。对 95% 的店铺来说，这完全够用。 当你想做小部件做不到的事时，就该用商务 API：在你自己的界面里渲染商品，在 SaaS 后台里嵌入结账，把商品目录分发到多个终端（网页 + 移动端 + 语音），或者搭建没有任何平台开箱提供的自定义买家流程。 Shoprocket 两种都有。[小部件](https://v3.shoprocket.io/zh/blog/headless-commerce-the-three-tiers-the-real-options-and-which-one-you-probably-actually-want.md)是默认选项。当你超出了小部件的能力范围，或者压根不需要小部件时，就用 [`@shoprocket/core` SDK](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' }) // 用户点击“Add credits”按钮 await sr.cart.addItem(addon.id, 1) ``` ### 2. 多终端商品目录（网页 + 原生应用 + 语音 + 聊天） 同一份商品目录，在每个地方以不同方式呈现。网页店面展示完整的商品详情，原生 iOS 应用展示精简列表，语音助手朗读商品信息，聊天集成则回复一个可购买的链接。 四个终端调用的是同一个 API。当你在 Shoprocket 后台修改某个商品的价格，每个终端在下一次请求时都会反映出来。不需要逐个终端同步内容。 ### 3. 白标 / 合作伙伴店面 你是一个让别人销售自己商品的平台：社区市场、合作伙伴名录、拥有各个经销商站点的连锁加盟网络。每个合作伙伴都有属于自己、而不是你的品牌形象。 每个合作伙伴的站点运行你的框架，但用他们自己的 `publicKey` 调用商务 API。他们的商品、他们的订单、他们的结算，全部按账户隔离。没有任何小部件会妨碍他们的品牌表达。 ### 4. 完全自定义的买家体验 交互式商品配置器（定制电脑配置、个性化珠宝、定制家具）。3D 商品查看器。“买下整个房间”的照片画廊，点击图片上的像素就能把商品加入购物车。邮件里的一键复购按钮。 这些小部件一个都做不到，API 可以。你渲染设计师构想的任何界面，背后的电商机制由 API 负责。 ### 5. AI 智能体与智能体电商 一个 AI 智能体（ChatGPT、Claude 或自定义智能体），可以浏览商品并代表用户完成购买。智能体需要以编程方式访问你的商品目录和购物车，而不是去解析一个 DOM 小部件。 Shoprocket 在标准 API 访问之外，还提供面向 AI 电商协议的数据源。当智能体被问到“有哪些 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) // Cart sr.cart.get() sr.cart.addItem(productId, quantity) sr.cart.updateItem(itemId, quantity) sr.cart.removeItem(itemId) // Session sr.session.create() sr.setSessionToken(token) ``` 此外，SDK 尚未封装的功能（订单、客户、折扣、商品写入）可以使用完整的 REST API。完整参考请见 [api.shoprocket.io/docs](https://api.shoprocket.io/docs)。 ## API 优先反而是错误的情形 有几种情况下，小部件才是正确的选择，API 则是小题大做： - **一个有 10-200 个商品的简单店面。** 小部件把它渲染得完美无缺；自己写一套商品目录界面，是在重复做已经解决的事。 - **你没有专门的前端工程力量。** API 优先意味着你要自己开发并维护加载状态、规格界面、错误处理、无障碍支持，以及 21 种语言的国际化（i18n）。小部件免费给了你这几周的工作量。 - **你最看重的是上线速度。** 小部件只要几分钟；API 优先至少要几周。 默认用小部件。碰到小部件做不到的事时，再去用 API。 ## 一个现实的第一个项目 最常见的“我需要 API”项目：一款 SaaS 产品想在自己的后台里销售额度、订阅或一次性的附加组件。 做法： 1. 在前端安装 `@shoprocket/core` 2. 在 Shoprocket 里创建一个名为“Add-ons”（附加组件）之类的分类 3. 添加商品，填入你想要的确切定价 / 描述 4. 用你自己的组件库在后台里渲染商品列表 5. 点击时加入购物车，并跳转到 Shoprocket 的托管结账页（如果你愿意多做些工作，也可以内嵌结账） 6. 配置一个 webhook 端点来接收 `order.paid` 事件，这样你就能开通这次购买所解锁的内容（额度、权限、发货） 就这样。几个文件，对习惯调用 API 的人来说一天的工作量。没有小部件，没有 iframe，也不必在产品界面上做任何妥协。 ## 我们不推荐什么 不要重新搭建一套和小部件已有功能高度相似的完整商品目录界面。如果你花了几周时间做“带筛选和搜索的商品网格”，那你写的就是小部件几分钟就能给你的东西。这种形态用小部件，真正不同的形态才用 API。 > **提示：**如果你想走 API 优先，只是因为小部件的默认样式和你的品牌不搭，先试试[小部件的样式钩子](https://github.com/shoprocket/shoprocket-js)。小部件支持的 CSS 自定义比看上去多得多。完全用 API 重建的工作量要大得多。 ## 一句话总结 - **小部件** = 默认选项，覆盖 95% 的店铺 - **API / SDK** = 小部件形态不合适时使用（SaaS 内嵌电商、多终端、白标、自定义体验、AI 智能体、自定义 BI） - **当前 SDK 的能力范围：** 商品、购物车、会话；订单 / 客户 / 折扣则用完整的 REST API - **第一个项目的模式：** SaaS 后台通过 SDK 销售额度或附加组件，并由 webhook 驱动开通 - **不要用 API 重建** 小部件已经做得很好的东西；选对你的形态 [开始免费试用](https://app-v3.shoprocket.io/signup)并获取一个公开密钥；SDK 在任何 Shoprocket 套餐上都可免费使用。14 天，无需绑定银行卡。 --- - HTML version: https://v3.shoprocket.io/zh/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget - Language: 中文 (zh) - 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/ru/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-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)