第三方店铺前端公共 API

当前入口包含 43 项第三方店铺前端相关公开操作，包括目录读取、hosted session 与官方浏览器流程、购物车/报价和订单读取/取消/售后。下列链接与通用 API Reference 使用同一批生成页；未列出路径的资源均尚未开放。

• API 来源提交: fea64ddee8d29d0f9296de5b046cb26ce0a96cdf
• OpenAPI SHA-256: 989e09de11d6a1accdf647db33b9b1dc24141458771dc4a69bc99ca8c083c2f0

托管跳转边界

目录读取留在第三方站。Artifact 已提供 hosted login/checkout session 与官方浏览器票据、投影、取消和回跳操作，以及购物车、地址令牌、优惠、统一报价和订单读取/取消/售后操作；它仍未声明订单最终创建或支付执行。浏览器只能顶层跳转到 Ayalink 官方托管页面，再返回平台审核的精确 return URL。第三方不得收集密码/MFA、转发 Ayalink Cookie、处理支付凭据或反代托管页面。

店铺身份与启动配置

• GET /api/v1/runtime-config — 读取公开运行配置
• GET /api/v1/bootstrap — 读取公开站点启动配置
• GET /api/v1/public/contact — 读取公开联系渠道
• GET /api/v1/catalog/merchants/{slug} — 读取公开店铺资料

配置与装修

• GET /api/v1/public/store-access/{store}/config — 读取店铺公开安全配置
• GET /api/v1/storefront-decorations/merchants/{slug} — 读取店铺已发布装修

分类

• GET /api/v1/catalog/categories — 读取公开分类
• GET /api/v1/catalog/merchants/{slug}/categories — 读取店铺公开分类

商品

• GET /api/v1/catalog/products — 读取公开商品目录
• GET /api/v1/catalog/products/{slug} — 按 slug 读取公开商品
• GET /api/v1/catalog/merchants/{slug}/products — 读取店铺公开商品
• GET /api/v1/catalog/merchants/{merchantSlug}/products/{productSlug} — 读取店铺公开商品详情

搜索

• GET /api/v1/search — 搜索可公开销售商品

公开法律内容

• GET /api/v1/legal/documents — 按语言读取当前已发布法律正文

Hosted login 官方浏览器流程

• POST /api/v1/open/hosted/login/initiate — 创建官方托管登录流程
• POST /api/v1/open/hosted/login/return — 以 PKCE 单次消费托管登录返回码
• POST /api/v1/hosted/login/{flowId}/ticket — 单次消费官方托管登录票据并读取请求方投影

Hosted checkout 官方浏览器流程

• POST /api/v1/open/hosted/checkout/sessions — 创建服务端重算的托管结账会话
• GET /api/v1/open/hosted/checkout/sessions/{sessionId} — 读取绑定安装的托管结账状态
• POST /api/v1/open/hosted/checkout/sessions/{sessionId}/cancel — 取消尚未进入不可逆支付阶段的托管结账
• POST /api/v1/hosted/checkout/{sessionId}/ticket — 单次消费官方托管结账票据并读取安全摘要
• POST /api/v1/hosted/checkout/{sessionId}/projection — 读取官方托管结账安全摘要
• POST /api/v1/hosted/checkout/{sessionId}/cancel — 安全取消尚未进入不可逆阶段的官方托管结账
• POST /api/v1/hosted/checkout/{sessionId}/return — 读取已批准的精确回跳地址与原始 state

购物车、地址令牌与统一报价

• PUT /api/v1/open/storefront/carts/{cartId}/address — 校验并保存购物车短期地址令牌
• GET /api/v1/open/storefront/carts/{cartId}/checkout-quote — 生成配送税费优惠统一结算报价
• POST /api/v1/open/storefront/carts/{cartId}/checkout — 由购物车创建官方托管结账会话
• POST /api/v1/open/storefront/carts/{cartId}/clear — 清空公开购物车
• DELETE /api/v1/open/storefront/carts/{cartId}/items/{skuId} — 移除公开购物车 SKU
• PATCH /api/v1/open/storefront/carts/{cartId}/items/{skuId} — 更新公开购物车 SKU 数量
• POST /api/v1/open/storefront/carts/{cartId}/items — 向公开购物车添加 SKU
• DELETE /api/v1/open/storefront/carts/{cartId}/promotion — 移除购物车优惠码
• PUT /api/v1/open/storefront/carts/{cartId}/promotion — 校验并应用购物车优惠码
• POST /api/v1/open/storefront/carts/{cartId}/quote — 按实时价格与库存生成短期报价
• POST /api/v1/open/storefront/carts/{cartId}/revoke — 撤销公开购物车访问票据
• GET /api/v1/open/storefront/carts/{cartId} — 读取安装绑定的公开购物车
• POST /api/v1/open/storefront/carts — 创建安装绑定的公开购物车

订单读取、取消与售后

• GET /api/v1/open/storefront/orders/{orderId}/after-sales-eligibility — 读取退款退货售后资格
• POST /api/v1/open/storefront/orders/{orderId}/after-sales — 提交退款或进入官方售后流程
• GET /api/v1/open/storefront/orders/{orderId}/cancellation-eligibility — 读取订单取消资格
• POST /api/v1/open/storefront/orders/{orderId}/cancellations — cancelStorefrontOrder
• GET /api/v1/open/storefront/orders/{orderId} — 读取 receipt 绑定的最小订单状态
• GET /api/v1/open/storefront/orders — 以 customer-bound receipt proof 读取最小订单列表

尚未开放的资源组

当前 artifact 没有以下资源的 operation，因此本站不生成 endpoint、参数、scope 或响应：

• 订单最终创建 — 尚未开放
• 支付执行与支付凭据处理 — 尚未开放
• 托管结账 complete/continue（需要官方 session 与 CSRF） — 尚未开放
• 退款专用操作 — 尚未开放
• 独立价格资源 — 尚未开放
• 独立媒体资源 — 尚未开放

商品 schema 中即使出现价格、媒体或库存相关字段，也不代表存在独立资源 API；只按对应 operation 页的实际 schema 使用。