---
title: 开始对接
description: 获取凭证、完成签名，接入观众登录与观看数据。
---

# 开始对接

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

## 第一次调用

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

## 接口目录

| 接口 | 使用场景 | 完整 Path |
|---|---|---|
| [创建或更新外部观众](./api/upsert-viewer.md) | 外部用户 → 观众 UID | `POST /api/v1/open/viewers/upsert` |
| [签发一次性登录票据](./api/login-ticket.md) | 观众 UID → 登录观看链接 | `POST /api/v1/open/viewers/login-tickets` |
| [查询观看数据概览](./api/watch-overview.md) | 活动整体观看统计 | `POST /api/v1/open/watch-data/overview` |
| [查询观众观看明细](./api/watch-viewers.md) | 指定观众的时长及会话统计 | `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 文档索引](/llms.txt) 是机器可读的文档目录，[完整文本](/llms-full.txt) 是合并后的全部内容，主要供 AI 和无需执行 JavaScript 的工具读取。

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