> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orriven.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 开放 API 概览
> 把 Orriven 接进你自己的系统:通过一套限定在单个业务单元内的 REST API,管理活动、票种、报名、兑换码与签到。
Orriven 开放 API 让你自己的软件做到控制台能做的事:创建活动、配置票种与价格、实时查看剩余票量、录入参会者、审批报名、生成兑换码、记录签到。它与控制台读写**同一份数据、遵守同一套规则** ——容量、生命周期、审批,无论从哪扇门进来,行为完全一致。
API 的作用域是**单个业务单元**。密钥在某个业务单元内生成,只能读写该单元的活动——碰不到其他单元,更碰不到其他组织。见 [API 密钥](/zh/developers/api-keys)。
## 能做什么
| 领域 | 权限 |
| ----- | ------------------------------------------------------------------------------------------------------------ |
| 活动 | 创建、读取、修改、归档(无删除) |
| 票种 | 完整配置:价格、容量、候补、可见性、审批模式、售卖窗口、生命周期 |
| 剩余票 | 实时数字:容量、已确认、候补中、订单占位、剩余 |
| 报名 | 列表、创建、查看、审批通过、驳回、取消 |
| 兑换码 | 列表、生成(单个或批量)、禁用 |
| 加购与捆绑 | 完整配置,含捆绑内容 |
| 购买流 | 从你的后端下单/确认/取消:票、加购、捆绑、兑换码装进一张订单;免费当场结清,付费返回 Stripe 托管支付页并回跳你自己的地址——见 [Headless 购买流](/zh/developers/checkout) |
| 订单 | 列表与详情——结算由平台 webhook 完成;退款仍是控制台决定 |
| 权益 | 按报名读取生效权益(票种 ∪ 兑换码 ∪ 个人授予) |
| 场地 | 只读列表(含权益门),用于展示地点 |
| 议程与讲者 | 只读:按时间排序的日程(含每场权益门)与讲者阵容 |
| 签到 | 记录与查询,按报名 ID 或胸卡码 |
| 参会者 | 按活动的只读列表 |
自动化对 API 操作一视同仁:通过 API 录入的报名会触发你配置的「新增参会人」自动化,审批通过触发确认流程,到场签到触发欢迎流程——与控制台操作完全同源。
## 基础地址与交互式文档
本文所有端点都挂在你的 Orriven API 主机的 `/v1` 下。示例中主机写作 `$BASE`:
```bash theme={null}
export BASE="https://openapi.orriven.com" # 本地开发:http://localhost:3002
```
API 会自我描述:`GET $BASE/openapi.json` 返回完整的 OpenAPI 3.1 规范(可用它生成你所用语言的客户端);`$BASE/docs` 是交互式文档页,可以直接带着密钥试调每个端点。
## 请求与响应约定
* 请求与响应均为 JSON;写操作请带 `Content-Type: application/json`。
* 时间戳一律是带时区偏移的 ISO 8601(`2026-09-01T09:00:00+08:00`)。
* 金额是活动币种**最小货币单位的整数**(¥120.00 → `12000`),含税——与控制台同一约定。
* 每个请求都携带密钥:`Authorization: Bearer `。
* API 采用[日期版本](/zh/developers/versioning):密钥在创建时钉住版本,每个响应以 `Orriven-Version` 头回显生效版本。
## 下一步
在控制台生成密钥——Secret 只显示一次。
活动 → 票种 → 报名 → 签到,七条 curl 走完。
每个资源、方法与状态码。
API 所映射的控制台概念。