@behio/ storefront-sdk (英语)

用于建设自定义店面的无头电子商务 SDK.

Behio给你一个完整的电子商务后端(产品,库存,订单,客户,折扣,多货币,多语言),让你任意设计店面. 商人在世界各地经营,当地税收规则、承运人和支付网关都以本地方式处理。 没有主题, 没有模板, 没有供应商锁定 .

显示目录设置( 2. 9. 0 )

ShopInfo.defaultProductSort 带有正常商家默认值。 用这个 当 URL 不指定一个排序时,用于选定排序控件。 选择 sort 从目录请求中应用此默认值到服务器 .

价格界限和面额范围使用访客显示的报价,包括 客户定价和可变起价。 使用同一认证客户端 两个电话。 当客价被隐藏时,范围是无效的,价格是界限的 被忽略,以防止通过结果计数进行披露.

ProductLabel 财务报告和审定财务报表 FacetLabel 曝光无效 iconName 与 商人的颜色和本地化名称. 产品清单、细节、标签和方面 保存此值。 将一个可信任的本地图标带回安全倒计时; 永远不要 将该字符串作为 SVG, HTML 或 URL 处理. 标签和自动规则得到解决 由API编辑. 保持文字可见度,并对所选颜色使用可读对比.

为什么是碧雄?

• 你拥有前端. 下.js,React,Vue,Nuxt,Astro,或平地JS,后端并不在意.
• 几分钟后开始生产. 目录 推车 离职 客户账户 订单 CMS 折扣码 礼品卡 忠诚程序等等.
• 为开发者所建. 完整TypeScript类型,自动完成,现代回放钩与TanStack查询.
• 规模准备. Redis craching, 速率限制,webhooks, 原子检出(不双向,不超销).

安装

2.0.1中的回放手推车突变取消旧手推车在写前和写前的读取 接受服务器响应。 这包括增加、清理、适用或 取消折扣,合并篮子。 延迟读取无法还原旧的 在其中一项行动取得成功之后,我们做了一个篮子.

从2.0.3起,一个老客户的反应和重复,推车会话,货币, 国家或地方被拒绝,具有SDK状态 409. 明确重试于 当前背景。 在同一客户会话中保留一个普通的令牌刷新 . useAuth() 取消旧查询并删除客户数据和价格 身份变化,包括原始的安全部门改革数据。 延迟登录或刷新失败 无法清除新登录。 此浏览器保护不替换按请求 SSR客户端或服务器授权.

npm install @behio/storefront-sdk

快速启动

import { BehioStorefront } from '@behio/storefront-sdk';

const storefront = new BehioStorefront({
  apiKey: 'pk_live_your_key',
});

// Fetch products and check the typed result.
const products = await storefront.catalog.getProducts({limit: 12});
if (products.error || !products.data.items.length) throw new Error('No products available');
await storefront.cart.addItem({productId: products.data.items[0].id, quantity: 1});

// After the customer enters addresses and selects shipping/payment:
const previewResult = await storefront.checkout.preview(checkoutInput);
if (previewResult.error) throw new Error(previewResult.error.message);
// Render previewResult.data.grandTotal. Wait for the customer to submit.
const orderResult = await storefront.checkout.createOrder({
  ...checkoutInput,
  previewToken: previewResult.data.previewToken,
});
if (orderResult.error) throw new Error(orderResult.error.message);
// Redirect to paymentRedirectUrl, or display the receipt for orderResult.data.

没有商店的网站(2.17.1)

每个Behio店面都属于一个网站. 网站开始为网站:商店 信息,SEO,网页,博客,FAQ,表格,收藏和分析 工作与它的密钥, 和类别及特色产品返回空列表。 另一个店 端点(产品、推车、结账、客户账户、订单) 代码 be.storefront.siteKeyNotAllowed 直到商人增加一个商店 网站,在 Behio 管理员或使用 MCP 工具 site-commerce-enable。 。 。 . 从那时起,同一个钥匙和同一个地点的ID 也服务于商店和商店 共享网站的名称,语言,标志,外观和SEO.

import { errorCode } from '@behio/storefront-sdk';

const {data, error} = await storefront.catalog.getProducts({limit: 12});
if (errorCode(error) === 'be.storefront.siteKeyNotAllowed') {
  // Website without a shop: hide the shop navigation instead of an error page.
}

errorMessage(error, locale) 返回此代码的已翻译句子 (cs, sk and en.) (中文(简体) ).

支付订单可短暂退回 contentDeliveryPending: true 购买时 正在分配文件和课程访问。 在初始状态中渲染此状态 接收 HTML 并刷新已认证的订单细节, 直至清空 。 告诉 (b) 客户收到付款后,无须放置 二级命令。 在等待其他内容时,现有的下载仍然可用. Behio将这项工作与付款交易一起储存,并中断了复试或 重新启动后发送失败 。 重复交付保持访问期限, 下载计数器和课程进度.

产品资源和变种页

渲染器 resolveVariantContent(product, selectedVariant).assetGroups 输入 初标 HTML. 有公共资源的变体取代了父母的团体 空或缺数组继承它们 。 各组人并尊重物品顺序, 本地化标题和消毒描述。 文件是正常的公共链接, 图像全尺寸打开,上传视频使用本地控件,外部 YouTube/Vimeo 播放器在明确点击后加载. 保护Vimeo未列入名单 隐私散列。 这些组从未包含已购买的下载 URL .

requiresShipping 财务报告和审定财务报表 isDigital 属于选定的变体。 用来 该车对整个订单仍然具有权威性. catalogSiblings 包含单独的产品页面: 实现真正的本地化链接 标记 isCurrent,保留了变体采取器中剩余的轴. 禁用没有可购买变量的值; 使用 isPurchasable 如此零库存 备份选项仍然可以选择。 清除不兼容轴选择 .

产品审查也必须出现在第一个HTML中. 获取第一页 服务器并传到 initialData 改为 useProductReviews; 页面和限制标识 缓存条目。 使用所选变体的ID和自己的评分,渲染相片和 商家的答复,并区分失败与空列表. 经核实的采购 需要经过认证的订单所有权。 帮助投票 success: false 实值 重复; 错误必须倒计时 .

反应钩

目录定价支持特定请求 country 并行 currency 财务报告和审定财务报表 客户认证. new BehioStorefront({apiKey, country: 'SK', currency: 'EUR'}) 解决每个目录表面的国家规则. setCountry() 变动 默认值; 明确的按国家计值胜出。 它不会改变车: 使用情况 cart.setDestination() 对于这个。 Next.js 适配器读取 behio_country 用于初始服务器渲染。 保持经认证的答复保密,并包括 货币和国家的来宾缓存键. 启动新车时, cart.setCurrency() 财务报告和审定财务报表 cart.setDestination() 保存下次变异前的返回会话。 模板应初始化 在添加第一个产品或捆绑之前的上下文,包括在 上一车过期.

import { BehioProvider, useProducts, useCart } from '@behio/storefront-sdk/react';

function App() {
  return (
    <BehioProvider apiKey="pk_live_your_key">
      <ProductList />
    </BehioProvider>
  );
}

function ProductList() {
  const { items, isLoading, error } = useProducts({ limit: 12 });
  const { addItem, isAdding } = useCart();

  if (isLoading) return <div>Loading...</div>;

  if (error) return <p role="alert">Products could not be loaded.</p>;

  return items.map(p => (
    <div key={p.id}>
      <h3>{p.name}, {p.price ? `${p.price.amount} ${p.price.currency}` : "Sign in to view price"}</h3>
      <button disabled={isAdding || !p.isPurchasable} onClick={() => addItem(p.id, 1).catch(() => window.alert("The item could not be added."))}>
        Add to Cart
      </button>
    </div>
  ));
}

以上示例显示了浏览器钩的使用. 制作模板 服务器上的初始目录/目录并将其数据水化。 仅限 HTTP 会话 留在服务器动作或会话约束的 API 后面. useCart() 返回时 cart, (中文(简体) ), isEmpty, (中文(简体) ), itemCount 及其变异方法。 更新/删除保留最后一个 在等待并接受整个成功响应时完成服务器快照, 即使查询获取被禁用。 写入失败不翻转新缓存 数值. isEmpty 包括捆绑线; itemCount 使用服务器捆绑数量. 提供者在恢复浏览器会话存储后通知钩子.

包含什么

SDK 模块

反应钩(30+)

useProducts • 妇女 useProduct • 妇女 useCategories • 妇女 useFeatured • 妇女 useLabels • 妇女 useSearch • 妇女 useFilters • 妇女 useBundles • 妇女 useBundle • 妇女 useCrossSell • 妇女 useProductPromotions • 妇女 useGiftCardBalance • 妇女 useCart • 妇女 useCheckout • 妇女 useOrders • 妇女 useOrder • 妇女 useCustomer • 妇女 useAddresses • 妇女 useAddressAutocomplete • 妇女 useWishlist • 妇女 useProductReviews • 妇女 useSubmitReview • 妇女 useShopInfo • 妇女 useShopSeo • 妇女 useCartCount • 妇女 useBlogs • 妇女 useBlogPosts • 妇女 useBlogPost • 妇女 useSiteForm • 妇女 useSiteFormSubmit

FAQ 内容 (2.21.0)

在 Behio 管理员中读取为该网站配置的 FAQ 组 。 组合可以是 以弹片或身份证标注。 隐藏的问题不在此列; 缺少翻译 倒回网站的默认语言. 一个未知的组返回一个 404 错误 .

const groups = await storefront.faq.list({locale: 'cs'});
if (groups.error) throw new Error(groups.error.message);

const delivery = await storefront.faq.get('delivery', {locale: 'cs'});
if (delivery.error) throw new Error(delivery.error.message);
// delivery.data.items contains questions and sanitized HTML answers in admin order.

反应客户端可以使用 useFaqGroups({locale}) 财务报告和审定财务报表 useFaqGroup(slugOrId, {locale}) 从 @behio/storefront-sdk/react 在内部 BehioProvider。对于道德操守办公室,包括: 在服务器发送的 HTML 中提问并发出一个包含 FAQPage JSON-LD 对象 只有那页上实际可见的问题.

退出合同(2.25.0)

欧盟法律(第11a条,第2011/83/EU号指令,自2026年6月19日起)要求在线 消费者购买的提取功能。 何时 shopInfo.withdrawal.enabled, (中文(简体) ), 从页脚和客户账户将其链接,并带有明确的标签,例如: "从合同这里抽走" 流量有两步: 形式( 名称、 顺序) 数字,电子邮件),然后是带有"确认退出"按钮的概要. 只有 确认呼吁 withdraw; 显示返回的确认, 相同 内容与日期和时间通过电子邮件.

const {data: order} = await storefront.returns.lookupOrder('B-2026-0042', '[email protected]');
// order.customerName prefills the name, order.withdrawal tells the period and flags
const {data: ack, error} = await storefront.returns.withdraw({
  orderNumber: 'B-2026-0042',
  email: '[email protected]',
  name: 'Jana Nováková',
  confirmed: true, // the consumer pressed "Confirm withdrawal"
});
// ack.submittedAt, ack.items, ack.confirmationSent

预订(2.24.0)

Behio Bookings模块的在线预约。 日数是 YYYY-MM-DD 输入 分支时区(config.timezone); 花时间回答 409 be.bookings.slotTaken重新装入免费时间 让顾客再次选择.

const {data: config} = await storefront.bookings.getConfig();
const {data: free} = await storefront.bookings.getSlots({serviceIds: [config.services[0].id], from: '2026-10-21', to: '2026-11-03'});
const {data, error} = await storefront.bookings.create({serviceIds: [config.services[0].id], startMs: free.slots[0].startMs, name: 'Jana', email: '[email protected]', website: ''});
// data.booking.code, data.booking.status ('CONFIRMED' or 'PENDING'), data.manageToken

从确认邮件中更改并取消 : getByToken, (中文(简体) ), getManageSlots, (中文(简体) ), reschedule, (中文(简体) ), cancel。反应 : useBookingConfig, (中文(简体) ), useBookingSlots, (中文(简体) ), useCreateBooking, (中文(简体) ), useManagedBooking, (中文(简体) ), useCancelBooking, (中文(简体) ), useRescheduleBooking。如果没有自己的用户界面,则嵌入主机部件 (见"文献"的"书目"一页).

框架支助

• 下一个.js: 服务器组件 + 客户端钩, SSR 准备
• 反应 + Vite: 标准SPA设置
• 数值 3: 与安全部门改革相混合
• Vue + 维特: 提供/输入模式
• 香草联署材料:在任何运行时间工作(Node.js、Deno、Bun、Cloudflare工人)

内建地物

• 401自动刷新 JWT 令牌
• 可配置复试与后退( 5xx, 429)
• 费率限制跟踪和警告
• 请求/答复拦截器
• 事件系统(自动、推车、订单生命周期)
• 刻录会话持续

文档

全面的API参考、框架指南和实例:

sdk.behio.com (中文(简体) )

许可证

麻省理工学院

离职价格审查和商贸政策

打电话 checkout.preview(input) 完成交货和支付选择后. 打开它 grandTotal,然后发送其 previewToken 最后决定 createOrder 输入. 信使会持续5分钟,与目前的推车,价格和选择相接. A 类 已更改或已过期的审查返回 be.storefront.checkoutChanged: 刷新显示 {\fn华文仿宋\fs16\1chd1d1d1}等待飞船再次屈服. useCheckoutPreview 可用于反应; 服务器动作在 HttpOnly 饼干中存储来宾收件符时首选 .

discountTotal 包括忠诚和礼品卡扣除。 添加接收快照 paymentFee, (中文(简体) ), roundingAdjustment, (中文(简体) ), loyaltyDiscount,以及 giftCardDeducted; 无效表示 旧的订单。 从不重复分解 使用 cart.checkoutLimits 分钟/最大值 以马车货币计值。 取出旗帜、账户/密码政策、外观、维护、, SIO和货币显示来自打字店合同. 查看退出文档 对独立的法律同意和准确的预览生命周期.

实际交付用途 product.requiresShipping 财务报告和审定财务报表 cart.requiresShipping独立 可下载奖金。 仅在线订单需要开具账单地址并省略货运. CourseListItem.isRevoked 财务报告和审定财务报表 DigitalDownload.isRevoked 区分已撤回的访问 从过期。 课程采购有独立的准入期;复习不延长 访问,而退还一项购买保留另一项有效的购买.

交付进度用途 Cart.shippingSubtotal,在产品推广之后,在订单券/忠诚/礼品卡之前. shippingPromotionApplied 标志着积极促进免费分娩。 方法阈值已经包括将全店阈值转换为所要求货币. 在线推车requiresShipping: false)没有执行进展.

客座课程的购买只有在一个账户的电子邮件地址是 已校验, 即使电子邮件校验是注册的选项 。 采购 属于该账户。 不同的离职收据 电子邮件不能要求另一个账户的课程。 未核实账户无法延伸 使用发送到同一地址的客人购买方式进入。 进行核查 (c) 向课程区内未经核实的客户发出通知,但不披露客人购买情况.

只为自有显示客户取消 PENDING 财务报告和审定财务报表 UNPAID 秩序。 秩序. 后端在持有订单锁时检查两个状态; 付款可以更改 页面加载后,请保留可见错误并刷新拒绝后的顺序. 取消一次,恢复实际剩余存量扣除. 仓库 分配标识符是内部的,决不能用模板提供.

Canonical 发现 URL

catalog.getSitemap(locale?) 遵循条形变量索引和界域 产品选择。 其条目和 ProductDetail.seo 显示可选 localizedSlugs 在1.20中,映射使语言能够实际被卡通流涕. 用于hreflang和语言链接; 省略未知的翻译 发明它们。 Crawler 客户端必须无会话 。 在下一个元数据路径中, 调用 connection() 在动态 SDK 获取和验证生产结构之前.

备查目录和价格隐私

无效的价位查询返回 HTTP 503 与 be.storefront.pricingUnavailable;不受限制的来宾定价绝不是倒计时. 与 throwOnAvailabilityError: true中,捕获已知的 SDK 可用性例外,只当一个明确的服务器报出错误并重试替换失败的内容时。 A 类 {data, error} 检查无法单独处理此例外路径 。 绝不将停产视为零审查、零产品、免费报价或404.

完整类别过滤器

catalog.getCategoryProducts(slug, query) 共享全文 ProductsQuery 序列器为 getProducts. 价格界限保留为零,布尔滤波器保留为假,数组使用重复参数,公共参数/面选择使用JSON. 类别,主列表和有特色的提供遵循了后端中相同的已公布的可变和股票模式规则.

一种(2.5)

ProductListItem.isUnique 标记手工制作的原作: 一块,永远不要 重新炒作 从未卖出过股票. soldAt 一旦它卖出 和 可用标签为"已售出". 隐藏数量阶梯, 永远不提供 倒数看原作, 提供"我想要一个相似的".

来自 Behio Chat (2.4) 的相册链接

cart.claimLink(token) 添加已准备好的手推车链接(由 在Behio Chat的AI)中 代码。 在服务器上打电话 /cart/link/[token] 路由处理器,然后 重定向取出 。 添加项目, 永远不要替换推车; 打开第二个 不重复数量。 已过期的链接失败 be.storefront.cartLinkExpired答复 GET /cart/link/_probe 有页眉 x-behio-cart-link: 1 所以Behio Chat知道店面支持链接.

表单验证错误( 2. 6. 1)

formFieldErrors(error) 保留每个支持的字段代码,包括 dateNotFuture, (中文(简体) ), dateNotPast 财务报告和审定财务报表 tooManyFiles。在旁边显示每个错误 它的字段,并在拒绝提交时保存输入的值.

页面脚本的单元格摘要( 2. 6)

浏览器手推车响应发送 behio:cart 打开 window 与 {total, currency, itemCount} 并保留最后一个值 window.__behioCart (Behio Chat读它是为了车价值的问候) 领带 totalsAvailable: false,无法读取并更改客户/定价上下文 清除最后一个值并发送 detail: null数字表示未知,而 {total: 0, itemCount: 0, currency} 是一个确认的空推车。 听者必须 处理两个。 计数来自权威 cart.itemCount,包括: 捆绑单位。 旧的反应不能恢复较新的总结. 移动车的存储前置 服务器( 服务器动作, 快取路由) 调用 publishCartSummary({total, currency, itemCount}) 每个客户端之后 新车 打电话 clearCartSummary() 当快照失败时, 无可用 总计或需要登录。 在安保部门改革期间,这两个职能都无所作为。 碧瑶聊天 取消行车值问候, 并在行车值清空时删除已过时的行车文本 .

包厢供货和美术馆(2.0,未放行)

catalog.getBundles({locale, currency, country}) 财务报告和审定财务报表 getBundle(slug, options) 返回明确 priceHidden, (中文(简体) ), isPurchasable 财务报告和审定财务报表 unavailableReason 并行 无效的价格和储蓄。 永远不要让一个无效的价格变成零。 荣誉 quantityRules.minimum, (中文(简体) ), step 和无效 maximum 额外完成 设置在当前访客篮。 服务器用于组件步骤, 普通行,其他捆绑,共享股票和商家限额. 组合列表/细节 请求中包含拖车会话和客户,私下返回 no-store 数据,以及 不得输入共享缓存。 隐藏的股票不会显示数字上限。 反应捆绑 钩子接受相同的上下文加服务器 initialData 和单独的查询缓存 由此可见。 他们等待会话恢复; 手推车和认证钩刷新 其范围在篮子或身份改变后。 直接核心捆绑突变需求 手推车刷新加取消/验证两个捆绑查询前缀. API 错误需要重试状态; 它们不是一个空目录 .

合并产品上市 images 与共享 media 并安全拆卸 URLs (英语). 共享视频不得隐藏更多上市相片. 渲染图像 链接,然后加强缩略图选择和本地视频.

Bundle 退出预览解决当前明确的货币报价和组件 规则。 以确认的顺序提交预览符; 处理 checkoutChanged 显示新预览。 等待命令 持有捆绑配额,终端 取消/退款将解除,重新开放必须再次要求。 库存模式 总是 AVALLLL 和 MADE TO ORDER 覆盖全程被保存的履带库存限制 搬运、取出和订购过渡,同时保留准确的库存流动.

墨盒捆绑行返回 当前 在遗产名称中提供 bundlePriceSnapshot 字段。 库存的手推车和订单快照不变 读取。 显示 priceChanged 和使用情况 quantityControls.decreaseTo 编号 : increaseTo ; 取消该方向。 保留 列旁边的服务器验证错误。 老服务器可以省略这些控件. 土著 服务器捆绑的数量/再移动在水合之前形成工作。 Bundle 组件保存 他们自己的税率和分配的价格参与优惠券的定向; 马车读取在商家或马车变更后重新检查票证的资格.

第2版修改了捆绑目录价格和 CartBundleLine.bundlePriceSnapshot 改为无效值。 在升级前更新消费者:无效, 从来没有免费的报价。 无效的捆绑留在拖车中 isPurchasable: false 还有一个 unavailableReason; 保留其去除控制. QUANTITY_UNAVAILABLE 可能 可通过改变数量进行修复。 何时 cart.totalsAvailable === false, (中文(简体) ), 隐藏货币总额并禁用手推车和小型手推车的退票。 别 将所余数字摘要字段解释为应付引号。 服务器 重新检查组件出版物、销售窗口、数量、库存和域名选择 在一个捆绑的突变之前。 SDK 保留匿名时返回的会话 访客先添加一个捆绑,然后读取同一个车的地址.

保留产品行(2.0,未放出)

SDK 2 发送 X-Behio-Cart-Contract: 2 每一个推车请求。 此选择加入 无效的时价。 在同一 v1 路由中, 没有此标题的客户端 当当前报价时保留数字、同货币存储价格快照 不见了。 兼容性投影不是购买授权 : 预览和退出总是验证当前报价。 还是老客户 需要更新以显示新的可用性和修理控制。 抓图 绝不绕过隐藏价格认证或重新给外币贴上标签.

产品行也报告 isPurchasable 财务报告和审定财务报表 unavailableReason它的单位, 细目和税额,加 product.currentPrice,当有 没有现行货币价格。 不恢复旧的快照或显示为零 . 保持行可移动; cart.totalsAvailable 适用于产品和捆绑.

偏爱 item.quantityControls.decreaseTo 财务报告和审定财务报表 increaseTo 为推车后台. 无效的目标会禁用这个方向. 这些指标包括: 同一产品在捆绑, 其他上市 分享它的股票,商迷你, 步骤多相和最大相。 他们可以直接跳到有效的修理后 商人编辑. 现有分数单位在无商时保留分数 步骤已配置。 服务器在写入前验证所产生的篮子; 显示本地窗体旁边的返回错误并重新读取权威推车.

以货币、目的地、代码、合并、, 和清除反应。 分析必须省略未知的金额,不得排放 当 totalsAvailable 是虚假的.

客户奖励(2.9)

认证, SSR 安全 customer.getGamification({badgesPage?, challengesPage?, limit?}) 返回 得到的徽章和挑战 . customer.joinChallenge(challengeId) 保持入学资格; customer.refreshGamification() 协调活动仍在继续。 使用 POST 表单 这些突变和重读的奖励 加上忠诚的平衡. 错误必须保持可见。 不接受客户提供的点数或进度.