Webinars / Open API

开始对接 ​

通过 Webinars Open API，把你系统中的用户接入直播观看页，并查询他们的有效观看时长。当前提供 4 个接口，所有请求均使用 POST + JSON + HMAC-SHA256。

第一次调用 ​

  1. 在商家控制台选择当前商户，进入 开发者 → 开放 API，取得 API Key 和 Secret。
  2. 取得部署方提供的 API 基础地址。文档站域名与 API 域名是两个入口；不能把当前文档域名直接当成 API 地址。
  3. 按 签名算法 构造请求，调用「创建或更新外部观众」，保存返回的 uid。
  4. 用 uid 和活动 ticketCode 签发登录票据，将 loginUrl 交给该用户打开。
  5. 需要观看统计时，查询概览或观众明细。数据成熟度及明细查询时机见各接口说明。

接口目录 ​

接口使用场景完整 Path
创建或更新外部观众外部用户 → 观众 UIDPOST /api/v1/open/viewers/upsert
签发一次性登录票据观众 UID → 登录观看链接POST /api/v1/open/viewers/login-tickets
查询观看数据概览活动整体观看统计POST /api/v1/open/watch-data/overview
查询观众观看明细指定观众的时长及会话统计POST /api/v1/open/watch-data/viewers/query

三个标识不要混淆 ​

标识来源用途
externalUserId你系统中的稳定用户标识在当前商户下绑定观众，区分大小写
uid创建或更新观众接口返回当前商户内的数字观众编号，JSON 数字
ticketCode商家控制台的活动观看链接，如 /w/abc123 中的 abc123定位活动；不是控制台内部的活动 ID

API Key 决定商户身份，请求不需要 X-Tenant-ID、商家 Cookie 或 JWT。不同商户之间不能共用观众映射；跨商户活动查询按不存在处理。

文档怎么读 ​

先看公共说明，接口页只保留其特有参数和行为。每页支持标题锚点、代码复制和 Markdown 阅读。AI/LLM 文档索引 是机器可读的文档目录，完整文本 是合并后的全部内容，主要供 AI 和无需执行 JavaScript 的工具读取。

在线调试 只向当前部署环境发送真实请求。环境与 API 地址未配置时仍能阅读文档和复制示例；实际可用性需由部署方核验。

读取本页 Markdown（纯文本）·AI/LLM 文档索引（纯文本）