diff --git a/src/main/java/io/as/modules/device/service/impl/DeviceServiceImpl.java b/src/main/java/io/as/modules/device/service/impl/DeviceServiceImpl.java index f9e0356..da0e6cf 100644 --- a/src/main/java/io/as/modules/device/service/impl/DeviceServiceImpl.java +++ b/src/main/java/io/as/modules/device/service/impl/DeviceServiceImpl.java @@ -27,6 +27,7 @@ public class DeviceServiceImpl extends ServiceImpl impl String status = (String) params.get("status"); String deviceName = (String) params.get("deviceName"); String mac = (String) params.get("mac"); + String source = (String) params.get("source"); IPage page = this.page( new Query().getPage(params, "created_at", false), @@ -35,6 +36,7 @@ public class DeviceServiceImpl extends ServiceImpl impl .eq(StringUtils.isNotBlank(status), "status", status) .like(StringUtils.isNotBlank(deviceName), "device_name", deviceName) .like(StringUtils.isNotBlank(mac), "mac", mac) + .eq(StringUtils.isNotBlank(source), "source", source) .eq("delete_flag", "UNDEL") ); diff --git a/橘视厅酒店版openapi文档.html b/橘视厅酒店版openapi文档.html new file mode 100644 index 0000000..4dd0f58 --- /dev/null +++ b/橘视厅酒店版openapi文档.html @@ -0,0 +1,705 @@ + + + + + + + +

天卡开放平台 第三方对接文档

+

版本: V2.0
+更新日期: 2026-07-23

+
+

1. 概述

+

本文档面向第三方合作伙伴后端开发人员，描述天卡开放平台的接口规范。

+

1.1 业务流程

+
第三方EPG                      开放平台                        APK
+    |                             |                             |
+    |  1. 用户在EPG界面完成支付      |                             |
+    |                             |                             |
+    |  2. 调用消耗接口(发卡)        |                             |
+    |---POST /card/consume------->|                             |
+    |<---deviceId, expireAt-------|                             |
+    |    status=ACTIVATING        |                             |
+    |                             |  3. 异步激活(橘视厅SDK)     |
+    |                             |                             |
+    |  4. EPG传参启动APK           |                             |
+    |---设备标识(mac/sn等)-------> |                             |
+    |                             |  5. APK调init获取sign       |
+    |                             |<---POST /api/jst/init-------|
+    |                             |----sign------------------->|
+    |                             |  6. APK轮询checkBenefits    |
+    |                             |<---POST /checkBenefits------|
+    |                             |----thirdCardNo------------>|
+    |                             |    (status=ACTIVE时返回)    |
+    |                             |  7. APK用thirdCardNo播放    |
+
+

1.2 服务器地址

+ + + + + + + + + + + + + +
环境地址
生产环境http://58.220.83.58:8084
+
+

2. 鉴权方式

+

2.1 凭证

+

平台分配的 appKey 和 appSecret，由管理后台创建合作伙伴时自动生成。

+

2.2 签名算法

+
sign = MD5(appKey + timestamp + nonce + appSecret).toUpperCase()
+
+
    +
  • 拼接顺序固定：appKey + timestamp + nonce + appSecret，无分隔符
    • +
  • MD5 结果转大写
    • +
+

2.3 请求头

+

每个请求必须携带以下 HTTP 请求头：

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
请求头类型说明
appKeyString平台分配的应用 Key
timestampString毫秒级时间戳，有效期 5 分钟
nonceString随机字符串，5 分钟内不可重复
signString签名（大写 MD5）
+

2.4 鉴权失败响应

+

HTTP 401：

+
{"code": 401, "msg": "签名校验失败"}
+
+

2.5 统一响应格式

+
{"code": 0, "msg": "success", "data": {}}
+
+
    +
  • code = 0 表示成功，非 0 表示失败
    • +
  • 业务数据在 data 字段内
    • +
+
+

3. 天卡代销接口

+

3.1 消耗天卡

+

用户在 EPG 完成支付后调用，从合作伙伴天卡池分配 1 张天卡绑定到设备，并异步激活。

+
POST /openapi/partner/card/consume
+Content-Type: application/json
+
+

请求体：

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
参数类型必填说明
macString否*设备 MAC 地址
wifiMacString否*WiFi MAC 地址
deviceUidString是*设备唯一标识
deviceSnString否*设备序列号
channelOrgIdLong否渠道组织 ID
+

* mac / wifiMac / deviceUid / deviceSn +deviceUid必须传，mac / wifimac /deviceSn +至少传一个，需与 APK 启动时传入的设备标识一致。

+

请求示例：

+
{
+  "mac": "AA:BB:CC:DD:EE:01",
+  "deviceSn": "SN-001",
+  "deviceUid": "UID-001"
+}
+
+

响应：

+ + + + + + + + + + + + + + + + + + + + + + + + + +
字段类型说明
deviceIdLong设备 ID
expireAtString天卡过期时间（yyyy-MM-dd HH:mm:ss），初始为 24 小时，异步激活成功后更新为真实过期时间
statusString天卡状态：ACTIVATING（激活中）
+

响应示例：

+
{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "deviceId": 123,
+    "expireAt": "2026-07-24 14:00:00",
+    "status": "ACTIVATING"
+  }
+}
+
+

幂等说明：同一设备重复调用时不会消耗新天卡，直接返回已有天卡信息。若天卡已激活成功，status 返回 ACTIVE。

+

错误响应：

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
codemsg说明
400mac/wifiMac/deviceUid/deviceSn 至少传一个缺少设备标识
400天卡池库存不足可用天卡已耗尽
400操作太频繁，请稍后再试同一设备短时间内重复请求
500天卡分配失败，请重试系统繁忙，请重试
+

3.2 查询天卡库存

+
GET /openapi/partner/card/stock
+
+

响应示例：

+
{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "available": 50
+  }
+}
+
+
+

4. 媒资接口

+

4.1 查看授权范围

+
GET /openapi/partner/media/package
+
+

响应：

+ + + + + + + + + + + + + + + + + + + + + +
字段说明
scope授权级别：CONTENT（指定内容）/ CATALOG（指定栏目）/ FULL（全量）
catalogIds授权栏目 ID（逗号分隔，CATALOG 级别有值）
contentCount授权内容数量
+

4.2 栏目树

+
GET /openapi/partner/media/catalog-tree
+
+

按授权范围过滤返回： +- CONTENT 级别返回空树 +- CATALOG 级别只返回授权栏目 +- FULL 级别返回完整栏目树

+

4.3 内容列表

+
GET /openapi/partner/media/list?catalogid=472&pageindex=1&pagesize=20
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
参数类型必填说明
catalogidStringFULL/CATALOG 级别必填栏目 ID
pageindexint否（默认 1）页码
pagesizeint否（默认 20）每页条数
+
    +
  • CONTENT 级别：返回授权内容列表，不需传 catalogid
    • +
  • CATALOG 级别：必须传授权范围内的 catalogid
    • +
  • FULL 级别：必须传 catalogid
    • +
+

4.4 搜索

+
GET /openapi/partner/media/search?keyword=镖人&pageindex=1&pagesize=20
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
参数类型必填说明
keywordString是搜索关键词
pageindexint否（默认 1）页码
pagesizeint否（默认 20）每页条数
+

4.5 内容字段说明

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
字段说明
contentcode内容唯一编码
name内容名称
posterimg海报图片 URL
categoryname分类名称
score评分
isFree1 = 免费，0 = 付费
episodecount集数
duration时长（秒）
releaseyear上映年份
originalcountry地区
+
+

5. APK 侧流程说明

+

以下接口由 APK 调用，第三方无需直接调用，但需了解流程以便 EPG 传参启动 APK。

+

5.1 设备初始化

+

APK 使用消耗接口传入的相同设备标识调用初始化：

+
POST /api/jst/init
+Content-Type: application/json
+
+

请求体（不传 activationCode，代销模式）：

+
{
+  "mac": "AA:BB:CC:DD:EE:01",
+  "wifiMac": "...",
+  "deviceSn": "SN-001",
+  "deviceUid": "UID-001"
+}
+
+

返回 sign（设备鉴权凭证，24 小时有效）。

+

5.2 查询天卡权益

+

APK 轮询查询激活状态，仅当 status 为 ACTIVE 时获取播放凭证：

+
POST /api/jst/checkBenefits
+Header: sign: <init 返回的 sign>
+
+

响应：

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
status说明是否返回 thirdCardNo
ACTIVATING异步激活中，需继续轮询否
ACTIVE激活成功，可播放是
ACTIVATION_FAILED激活失败否
UNBOUND无天卡绑定否
+

轮询建议：间隔 2 秒，超时 5 分钟。

+

5.3 播放

+

APK 使用 thirdCardNo 作为播放凭证初始化橘视厅 SDK，获取播放地址后播放。

+
+

6. 签名示例

+

Java

+
String appKey = "平台分配的appKey";
+String appSecret = "平台分配的appSecret";
+String timestamp = String.valueOf(System.currentTimeMillis());
+String nonce = UUID.randomUUID().toString().replace("-", "");
+String sign = DigestUtils.md5Hex(appKey + timestamp + nonce + appSecret).toUpperCase();
+
+

Python

+
import hashlib, time, uuid
+
+timestamp = str(int(time.time() * 1000))
+nonce = uuid.uuid4().hex
+sign = hashlib.md5((app_key + timestamp + nonce + app_secret).encode()).hexdigest().upper()
+
+

Node.js

+
const crypto = require('crypto');
+const timestamp = Date.now().toString();
+const nonce = crypto.randomBytes(16).toString('hex');
+const sign = crypto.createHash('md5')
+    .update(appKey + timestamp + nonce + appSecret)
+    .digest('hex').toUpperCase();
+
+
+

7. 请求示例（curl）

+

以下示例中的 appKey、appSecret 需替换为平台分配的实际值。timestamp、nonce、sign 需按签名算法实时生成。

+

7.1 消耗天卡

+
curl -X POST "http://58.220.83.58:8084/openapi/partner/card/consume" \
+  -H "Content-Type: application/json" \
+  -H "appKey: 你的appKey" \
+  -H "timestamp: 1784809605695" \
+  -H "nonce: 1784809605695aaf094ef" \
+  -H "sign: A6EBB96858ED2FAD864CB39568E3EABB" \
+  -d '{"mac":"AA:BB:CC:DD:EE:01","deviceSn":"SN-001","deviceUid":"UID-001"}'
+
+

响应：

+
{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "deviceId": 123,
+    "expireAt": "2026-07-24 20:26:46",
+    "status": "ACTIVATING"
+  }
+}
+
+

7.2 查询天卡库存

+
curl -X GET "http://58.220.83.58:8084/openapi/partner/card/stock" \
+  -H "appKey: 你的appKey" \
+  -H "timestamp: 1784809605695" \
+  -H "nonce: 1784809605695aaf094ef" \
+  -H "sign: A6EBB96858ED2FAD864CB39568E3EABB"
+
+

7.3 查看授权范围

+
curl -X GET "http://58.220.83.58:8084/openapi/partner/media/package" \
+  -H "appKey: 你的appKey" \
+  -H "timestamp: 1784809605695" \
+  -H "nonce: 1784809605695aaf094ef" \
+  -H "sign: A6EBB96858ED2FAD864CB39568E3EABB"
+
+

7.4 栏目树

+
curl -X GET "http://58.220.83.58:8084/openapi/partner/media/catalog-tree" \
+  -H "appKey: 你的appKey" \
+  -H "timestamp: 1784809605695" \
+  -H "nonce: 1784809605695aaf094ef" \
+  -H "sign: A6EBB96858ED2FAD864CB39568E3EABB"
+
+

7.5 内容列表

+
curl -X GET "http://58.220.83.58:8084/openapi/partner/media/list?catalogid=472&pageindex=1&pagesize=20" \
+  -H "appKey: 你的appKey" \
+  -H "timestamp: 1784809605695" \
+  -H "nonce: 1784809605695aaf094ef" \
+  -H "sign: A6EBB96858ED2FAD864CB39568E3EABB"
+
+

7.6 搜索

+
curl -X GET "http://58.220.83.58:8084/openapi/partner/media/search?keyword=镖人&pageindex=1&pagesize=20" \
+  -H "appKey: 你的appKey" \
+  -H "timestamp: 1784809605695" \
+  -H "nonce: 1784809605695aaf094ef" \
+  -H "sign: A6EBB96858ED2FAD864CB39568E3EABB"
+
+

7.7 签名生成示例（bash）

+
APP_KEY="你的appKey"
+APP_SECRET="你的appSecret"
+TIMESTAMP=$(date +%s%3N)
+NONCE="${TIMESTAMP}$(head -c 8 /dev/urandom | xxd -p)"
+SIGN=$(echo -n "${APP_KEY}${TIMESTAMP}${NONCE}${APP_SECRET}" | md5sum | awk '{print toupper($0)}')
+
+echo "appKey: $APP_KEY"
+echo "timestamp: $TIMESTAMP"
+echo "nonce: $NONCE"
+echo "sign: $SIGN"
+
+# 直接用变量发请求
+curl -X POST "http://58.220.83.58:8084/openapi/partner/card/consume" \
+  -H "Content-Type: application/json" \
+  -H "appKey: $APP_KEY" \
+  -H "timestamp: $TIMESTAMP" \
+  -H "nonce: $NONCE" \
+  -H "sign: $SIGN" \
+  -d '{"mac":"AA:BB:CC:DD:EE:01","deviceSn":"SN-001"}'
+
+
+

8. 注意事项

+
    +
  1. nonce 唯一性：每个请求的 nonce 必须唯一，5 分钟内重复提交会被拒绝。
    2. +
  2. timestamp 有效期：与服务器时间差超过 5 分钟会过期。
    3. +
  3. 设备标识一致性：消耗接口传入的设备标识必须与 APK 启动时传入的一致，否则 APK 无法找到设备。
    4. +
  4. 异步激活：消耗接口返回后天卡异步激活（通常 2-5 秒），APK 需轮询 checkBenefits 确认激活完成。
    5. +
  5. 库存管理：消耗接口返回库存不足错误时，需联系平台采购天卡。
    6. +
+
+

附录：设备标识说明

+

deviceUid 生成规则

+

APK 的 deviceUid 按以下优先级生成：

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
优先级来源格式重装不变工厂重置不变
1Android ID（Settings.Secure.ANDROID_ID）64 位 hex（16 字符），如 f0f179fe199f7a52是否
2UUID（兜底，存 SharedPreferences）32 位无横线，如 a1b2c3d4e5f6...否否
+

Android ID 为空时使用 UUID 兜底。正常情况下 deviceUid 即 Android ID。

+

关键注意点

+
    +
  1. +

    consume 与 init 的 deviceUid 必须一致：第三方调用消耗接口时传入的 deviceUid 必须与 APK 调用 init 时传入的 deviceUid 相同，否则 APK 无法找到设备。

    +
    2. +
  2. +

    Android ID 按签名隔离：Android 8+ 系统中，不同签名的 App 在同一设备上获取的 Android ID 不同。因此 EPG 获取 deviceUid 的方式需与 APK 一致，建议由 APK 提供给 EPG，而非 EPG 自行获取。

    +
    3. +
  3. +

    推荐传参方式：EPG 启动 APK 时通过 Intent 传递设备标识，APK 使用相同标识调 init 接口。设备标识建议优先使用 mac，其次 deviceUid。

    +
    4. +
+

设备标识匹配优先级

+

消耗接口和 init 接口均按以下优先级匹配设备：

+
mac > wifiMac > deviceUid > deviceSn
+
+

只要有一个标识匹配即可找到设备。建议 consume 和 init 传递相同的标识组合。

+ + \ No newline at end of file diff --git a/橘视厅酒店版openapi文档.pdf b/橘视厅酒店版openapi文档.pdf new file mode 100644 index 0000000..3be788b Binary files /dev/null and b/橘视厅酒店版openapi文档.pdf differ