Storefront API

Storefront API 是「在自己的网站上卖票」的浏览器侧一半。前端使用一把可写入页面代码的公开密钥直连 orriven，读取已发布的目录；买家选好之后，创建一个结账会话并把买家送到它的 url。之后由 orriven 的托管页面接手：补齐站点未收集的信息、占位、在 Stripe 收款、展示订单结果，再把买家送回站点。容量、结算、履约与票务邮件都是平台的工作。接入方只负责销售页。

不需要做登录，也没有登录可借用。 平台不托管任何参会者账号：购票成功后买家会收到一封邮件，内含入场凭证链接；之后打开任何托管页面，都会先要求输入这个邮箱。要在自定义网站里做「我的票」页面，请在服务端用开放 API实现——接入方负责认证此人，orriven 返回其报名与凭证链接。

两种密钥，两种形态

	Secret 密钥（`osk_…`）	Publishable 公开密钥（`opk_…`）
放在哪	仅服务端	前端——公开（设计如此）
作用域	整个业务单元，可读写	业务单元的公开 storefront：已发布活动与结账
调用面	`/v1`	`/storefront/v1`
能看到数字库存、草稿、参会名单	能	永远不能
泄露后果	立即轮换	等价于知道站点网址

两者在线路上互斥：公开密钥请求 /v1 得到与无效密钥完全相同的 401，Secret 密钥请求 /storefront/v1 同样如此。一把泄露的公开密钥能做的只有：读已发布的目录、受限流地下单——仅此而已。它读不到任何人的报名、看不到数字库存、不能访问开放 API。吊销它与吊销任何密钥一样：立即生效。

接入步骤

创建公开密钥

在「API 密钥」页选择Publishable 公开密钥，填写站点运行的 Origin —— https://tickets.example.com，每行一条（开发环境可以用 http://localhost:…）。密钥服务的是本业务单元的 storefront，无需再作其他选择。密钥全文随时在列表中可见、可复制。没有一次性 Secret，因为密钥是公开的。

发布活动

storefront 只返回已发布的活动。活动状态就是唯一的上线开关。同时请在活动的公开页面设置页面地址：推广链接会跳转到那里，托管页面也默认把买家送回那里。

从浏览器调用

const BASE = "https://openapi.orriven.com/storefront/v1";
const KEY = "opk_…";   // 可随页面分发

const res = await fetch(`${BASE}/events`, {
  headers: { Authorization: `Bearer ${KEY}` },
});

CORS 恰好向密钥上登记的 Origin 开放。其他 Origin 的请求会被拒绝。这道校验用于阻止把密钥嵌进其他站点。

GET /events 列出业务单元的已发布活动（每个都带 siteUrl，即控制台中设置的页面地址）。GET /events/{publicId} 返回销售页需要的一切——票种（soldOut 是布尔值，永远不是数字）、加购、捆绑、开放议程、讲者、赞助商、已发布的报名表单。隐藏票种不在目录中。GET /events/{publicId}/redemption-codes/lookup?code= 是通往它们的唯一路径。任何无效的码都返回同一个 404。活动提供其他语言时，加 ?lang= 即可取得主办方翻译后的内容。 售卖窗口是公开信息：在售票种带 opensAt/closesAt；upcomingTicketTypes 单列「已公布、未开售」的票种——名称、价格、权益，以及倒计时要数到的那个 opensAt 时刻。公布仅仅是公布：窗口开启之前，对未开售票种下单仍会被拒绝。

结账会话——托管结账

买家选定后，用其选择与已知的买家信息创建一个会话，再把买家送到 url：

const { url } = await post(`${BASE}/events/${publicId}/checkout-sessions`, {
  items: [{ itemType: "registration_type", itemId: ticketTypeId, quantity: 1 }],
  email: "ada@example.com",           // 可选——缺失时托管页会询问
  name: "Ada",                        // 可选
  redemptionCode: "VIP2026",          // 可选
  promotionCode: params.get("pl"),    // 可选——只做归因，不做门禁
  returnUrl: location.origin + "/thanks",
});
location.assign(url);

托管结账页展示明细与价格，收集缺失的信息——邮箱、姓名、票种的报名表单、加购——然后下单（占位 15 分钟）、确认；付费单再把买家交给 Stripe。页面使用活动的语言，显示活动名称与业务单元的名称和标识。
付款完成（免费单则立即）后，买家落在托管订单页。页面上的**「返回主办方」**按钮会跳到 returnUrl，并附加 ?order=<orderNumber>&status=<status> —— paid 即成功。未提供 returnUrl 时，按钮使用活动的页面地址。
会话有效 24 小时，且不占位。只有买家从会话里下单后才开始占位。已在该活动报名的买家会在托管页得到确认，绝不会被卖第二个座位。
预填的 email 会被原样使用：页面以打码形式展示且不允许修改，因此即使会话链接被猜中，也不会泄露邮箱地址。

直接结账

若由前端自行渲染结账流程，三步——下单、确认、轮询——仍可从页面发起：

// 下单：占位 15 分钟。`email` 必填。
const { order } = await post(`${BASE}/events/${publicId}/orders`,
  { email, ticketTypeId, returnUrl: location.origin + "/thanks" });

// 确认：免费单当场结清……
const done = await post(
  `${BASE}/events/${publicId}/orders/${order.orderNumber}/confirm`, {});

// ……付费单返回 { status: "awaiting_payment", paymentUrl } ——
// 把买家送过去，然后轮询 GET /events/{publicId}/orders/{orderNumber} 直到 "paid"。

confirm 的 successUrl/cancelUrl 为可选。不传时 Stripe 把买家送回托管订单页（再由它送回 returnUrl）；传入则直接回到站点自己的页面（绝对 https 地址；localhost 允许 http）。每个订单载荷都带 orderUrl（其托管页面），订单仍开放时还带 checkoutUrl。已报名的买家得到 alreadyRegistered: true 的确认，绝不会被卖第二个座位。

在站点里做「我的票」

storefront 没有用户中心。买家自己的页面就是托管页面：平台邮件里的入场凭证链接展示其二维码、钱包通行证、证书与问卷，在新设备上打开时都会要求输入邮箱。要在自定义网站里提供同样的内容，请在服务端用开放 API实现：认证此人，调用 GET /v1/events/{eventId}/registrations?email=，把每条报名的 passUrl 链接出去。链接泄露时，重新生成只需一次调用。

交互式参考

此调用面返回 OpenAPI 规范：$BASE/storefront/openapi.json 是 OpenAPI 3.1 文档，$BASE/storefront/docs 是可试调的参考页。每个端点在本站侧边栏的「Storefront 接口」组里也各有一页。日期版本与开放 API 完全一致：密钥绑定创建时的版本，Orriven-Version 头可按请求覆盖。

注意事项

永远没有数字。 这个面对容量只返回 soldOut: true/false。实时数字属于开放 API 的 availability，在 Secret 密钥之后。
404，不是 403。 草稿活动、其他业务单元的活动、不存在的 id，从这一侧看完全无法区分。
限流按密钥与访客双重计算。 创建结账会话与按订单号读取，在密钥自身额度之外还有按（密钥，IP）的限制。收到 429 请退避。
Storefront 流量进请求日志，不进审计日志。 调用会出现在控制台的开发者日志里供调试。结账是买家的动作，不写入组织审计日志。履约时自动化与票务邮件照常触发。

API 密钥

创建公开密钥、管理 Origin。

购买流（Secret 密钥）

服务端形态，含结账会话，以及「我的票」页面。

开始使用

参考

接口

Storefront 接口

两种密钥，两种形态

接入步骤

目录

结账会话——托管结账

直接结账

在站点里做「我的票」

交互式参考

注意事项

相关页面

API 密钥

购买流（Secret 密钥）

​两种密钥，两种形态

​接入步骤

​目录

​结账会话——托管结账

​直接结账

​在站点里做「我的票」

​交互式参考

​注意事项

​相关页面

API 密钥

购买流（Secret 密钥）

两种密钥，两种形态

接入步骤

目录

结账会话——托管结账

直接结账

在站点里做「我的票」

交互式参考

注意事项

相关页面