直播通道设备同步
接口说明
- 接口概述:用于服务商将其维护的门店直播设备通道信息同步到抖音平台,供后续门店直播通道绑定、通道查询及直播状态相关链路使用。
- 前提条件:
1. 调用方已完成该接口对应解决方案与能力的申请并获得调用权限;
2. 服务商与目标商家已建立有效商服授权关系;
3. vendor_code 已在平台侧完成准入配置。
- 使用场景:
1. 服务商首次接入门店直播设备时,批量同步设备通道数据;
2. 设备通道新增、变更、删除后,增量同步最新通道信息;
3. 服务商侧进行失败补偿或重复投递时,基于 sequence_number 发起幂等重试。
- 涉及业务逻辑:
1. 接口按 vendor_code + sequence_number 做幂等控制,重复请求不会重复写入;
2. 门店标识使用 poi_id 或 social_credit_number,二者必须二选一;
3. 单次请求支持批量同步多条通道数据,op 支持 UPSERT 和 DELETE;
4. 请求整体合法时,接口按 best-effort 模式处理单条数据,单条失败通过 failed_items 返回,不影响其他合法通道入库;
5. 当配置读取、幂等控制或写库等系统异常发生时,接口整单失败,调用方可使用原 sequence_number 重试。
使用限制
调用前提:
1. 应用已获得该接口对应能力权限;
2. 服务商与商家已建立有效商服授权关系;
3. vendor_code 已完成平台侧准入配置。
基本信息
| 名称 | 描述 |
|---|---|
| HTTP URL | https://open.douyin.com/goodlife/v1/store_live/channels/sync/ |
| HTTP Method | POST |
| Scope | life.capacity.store_live.channels.sync |
| 权限要求 | - 接口使用限制: 1. poi_id 与 social_credit_number 必须二选一,不能同时为空,也不能同时传入; 2. channels 不能为空,单次请求最多支持 50 条通道数据; 3. channels[].op 仅支持 UPSERT 和 DELETE; 4. channels[].device_serial 与 channels[].channel_no 为必填项; 5. 同一请求中若 device_serial + channel_no 重复,以最后一条数据为准。 - 失败重试策略: 1. 当接口返回整单系统错误或“请求正在处理中”时,可保留原 sequence_number 发起幂等重试; 2. 当接口返回 failed_items 时,表示整单已完成处理,不建议原样整单重试,应修正失败条目后重新发起同步。 |
请求参数
来客商户根账户ID
单次最多 50 条;同一请求中若 device_serial + channel_no 重复,以最后一条为准
请求流水号;服务端按 vendor_code + sequence_number 做幂等控制;重复重试请复用同一个值
服务商编码;必须为平台已准入并开通的服务商编码
门店 POI 标识;与 social_credit_number 二选一,且只能传一套
社会信用代码;与 poi_id 二选一,且只能传一套
curl --location --request POST 'https://open.douyin.com/goodlife/v1/store_live/channels/sync/' \ --header 'content-type: application/json' \ --header 'access-token: xxxxx' \ --data '{ "sequence_number": "sync_20250506_000001", "vendor_code": "xx", "social_credit_number": "91330100MA27XG019Q" "channels": [ { "op": "UPSERT", "device_serial": "DEVICE_10001", "channel_no": "CH_01", "channel_name": "1号直播通道", "extra": "{\"camera_position\":\"gate\",\"resolution\":\"1080p\"}" } ] }'
响应参数
{ "extra": { "error_code": 0, "description": "", "sub_error_code": 0, "sub_description": "", "logid": "202605072109137078938666D740DEDBC9", "now": 1778159353 }, "data": { "failed_items": [ { "device_serial": "blmBCwF68c", "channel_no": "nHCThYdPel", "error_code": "yF0gUKZbqC", "error_msg": "Gy5C39wdJK" } ], "sequence_number": "Ak07yEAMYf", "replayed": false, "processed_at": "1234567", "success_count": 1, "failed_count": 1, "error_code": 0, "description": "" } }
错误码
| HTTP 状态码 | 错误码 | 错误码描述 | 排查建议 |
|---|---|---|---|
| 200 | 2100001 | 未知错误 | 重试接口,重试3次仍报错联系抖音生活服务技术支持 |
| 200 | 2100004 | 系统繁忙,此时请开发者稍候再试 | 重试接口,重试3次仍报错联系抖音生活服务技术支持 |
| 200 | 2100005 | 参数不合法 | 请根据接口错误返回信息调整参数 |
| 200 | 2119001 | 参数不合法 | 请根据接口错误返回信息调整参数 |
| 200 | 2119002 | 系统繁忙,请稍候再试 | 重试 |
| 200 | 2119003 | 请求太过频繁,请稍后再试 | 重试 |
| 200 | 2119005 | 应用未获商家授权 | 联系合作商家在商家后台发起授权,并在服务商后台同意授权 |
| 200 | 2119010 | 接口已下线 | 接口已下线 |
| 200 | 2190002 | access_token无效 | 调用接口重新生成access_token |
| 200 | 2190004 | 应用未获得该能力, 请去https://open.douyin.com/申请 | 应用申请接口权限 |
| 200 | 2190008 | access_token过期,请刷新或重新授权 | 规范token刷新机制,检查是否有测试环境在同步刷新token |
| 200 | 3000001 | 根据实际业务错误返 回 | 对照接口文档规范参数并重试 |
| 200 | 5000001 | 根据实际业务错误返回 | 联系抖音处理 |
| 200 | 5000001 | 服务器异常 | 请稍后重试,重试时保留原 sequence_number。如多次重试仍失败,请记录 logid 联系平台排查。 |
| 200 | 3000291 | 请求参数无效 | 检查 body 结构、字段类型、字段层级是否符合接口定义 |
| 200 | 3000015 | 非法请求 | 检查请求体是否为空,或请求结构是否不符合接口定义 |
| 200 | 5000009 | 服务器异常 | 请稍后重试 ,重试时保留原 sequence_number。如多次重试仍失败,请记录 logid 联系平台排查。 |
| 200 | 4000001 | 请求流水号不能为空 | 检查 sequence_number 是否传递且非空 |
| 200 | 4000004 | 服务商编码不能为空 | 检查 vendor_code 是否传递且非空 |
| 200 | 4000002 | 门店标识参数非法 | 检查 poi_id 与 social_credit_number 是否严格二选一 |
| 200 | 4000003 | 通道列表不能为空 | 检查 channels 是否传递且至少包含一条通道 |
| 200 | 3000190 | 单次同步的通道数量不能超过50个 | 检查 channels 数量是否超过 50 条 |
| 200 | 3000007 | 当前服务商暂未开放 | 检查 vendor_code 是否已在平台白名单开通 |
| 200 | 4000008 | 当前应用暂未开通该服务商权限 | 检查当前应用 client_key 是否已加入该服务商白名单 |
| 200 | 3000001 | 请求正在处理中,请稍后重试 | 使用相同 vendor_code + sequence_number 稍后重试,不要立即并发重放 |
