> ## 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 快速上手

> 从一把新密钥到完成签到的参会者:创建活动、给票定价、盯着剩余票、录入报名、扫码入场。

这篇教程用 `curl` 走完整个流程。你需要一把密钥([去生成](/zh/developers/api-keys))和你的 API 主机:

```bash theme={null}
export BASE="https://openapi.orriven.com"   # 本地开发:http://localhost:3002
export KEY="osk_…"                              # 创建时复制的 Secret
```

<Steps>
  <Step title="1 —— 创建活动">
    ```bash theme={null}
    curl -s -X POST "$BASE/v1/events" \
      -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
      -d '{"name":"秋季峰会","timezone":"Asia/Shanghai","startsAt":"2026-09-01T09:00:00+08:00"}'
    ```

    活动以**草稿**状态出生——发布之前对公众不可见。记下返回的 `id`。
  </Step>

  <Step title="2 —— 创建票种">
    ```bash theme={null}
    curl -s -X POST "$BASE/v1/events/$EVENT/ticket-types" \
      -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
      -d '{"name":"普通票","capacity":100,"priceAmount":12000}'
    ```

    `priceAmount` 是活动币种的最小货币单位——CNY 活动里 `12000` 就是 ¥120.00。填 `0`(或不填)即免费票。记下返回的 `id`。
  </Step>

  <Step title="3 —— 开售">
    票种同样以**草稿**出生。开售就是改状态:

    ```bash theme={null}
    curl -s -X PATCH "$BASE/v1/events/$EVENT/ticket-types/$TYPE" \
      -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
      -d '{"status":"open"}'
    ```
  </Step>

  <Step title="4 —— 盯着剩余票">
    ```bash theme={null}
    curl -s -H "Authorization: Bearer $KEY" \
      "$BASE/v1/events/$EVENT/ticket-types/$TYPE/availability"
    ```

    ```json theme={null}
    { "capacity": 100, "confirmed": 0, "waitlisted": 0, "held": 0, "remaining": 100 }
    ```

    `held` 是公开结账中活跃订单占住的名额。这些数字是参考值——真正的把关发生在报名事务内部,读到旧值也不会导致超卖。
  </Step>

  <Step title="5 —— 录入报名">
    ```bash theme={null}
    curl -s -X POST "$BASE/v1/events/$EVENT/registrations" \
      -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
      -d "{\"email\":\"ada@example.com\",\"name\":\"Ada\",\"registrationTypeId\":\"$TYPE\"}"
    ```

    `201` 且 `"created": true` ——注意返回里的 `checkinCode`,那是胸卡凭证。同一邮箱再次报名会得到 `200` 和 `"created": false`,返回已有的那条报名:重复只被确认,绝不重复占位。
  </Step>

  <Step title="6 —— 审批(若票种开了审批模式)">
    在**审批模式**的票种上,API 录入的报名落在 `pending` ——API 只是记录申请,不代表准入决定。要明确地做出决定:

    ```bash theme={null}
    curl -s -X POST "$BASE/v1/events/$EVENT/registrations/$REG/approve" \
      -H "Authorization: Bearer $KEY"
    ```
  </Step>

  <Step title="7 —— 扫码签到">
    ```bash theme={null}
    curl -s -X POST "$BASE/v1/events/$EVENT/checkins" \
      -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
      -d '{"checkinCode":"CHK-…","subjectType":"event"}'
    ```

    `201` 记录到场;同一张胸卡再扫一次得到 `200` 和 `"alreadyCheckedIn": true` ——被确认,不是报错。
  </Step>
</Steps>

## 你刚刚验证了什么

* **草稿优先的生命周期** ——活动和票种在被打开之前不可见,与控制台一致。
* **容量闸门** ——`confirmed` 到达 `capacity` 后,下一次报名收到 `412`(票种开了候补则落 `waitlisted`)。
* **幂等的重复** ——重复报名与重复扫码都以确认代替报错,你的集成可以放心重试。
* **自动化** ——如果这个业务单元配置了「新增参会人」或签到自动化,你刚才的 API 调用已经触发了它。

## 相关页面

<CardGroup cols={2}>
  <Card title="端点参考" icon="book" href="/zh/developers/api-reference">
    剩下的一切:兑换码、加购、捆绑、订单、错误、限流。
  </Card>

  <Card title="票种" icon="tickets" href="/zh/ticketing/ticket-types">
    容量、候补、审批模式与可见性的完整解释。
  </Card>
</CardGroup>