自研商家接入指南
收藏生活服务开放能力简介
抖音生活服务是什么
生活服务是抖音推出适用于所有线下门店的本地生活行业商家的业务。商家可以通过团购优惠套餐或代金券的配置，并且通过短视频、直播、POI 等渠道展现给用户，引导用户线上购买、线下核销、为线下门店引流。
为什么要做生活服务开放能力
现有团购需要商家使用手机登录来客操作经营，不做打通没办法满足连锁规模商家（通常有自己的收银和 Saas 后台管理系统）核销、发券、退款、对账等场景需求。故利用抖音生活服务开放能力 OpenAPI 并承接商家和日常需求对接。
抖音生活服务开放能力概览
名词解释
名词 | 说明 |
自研商家 | 拥有自研能力，自研打通 SaaS 能力，实现如商家可通过店内收银系统核销抖音券，查询账单等。 |
技术服务商 | 针对没有自研能力或自研能力不足的商家，技术服务商帮助商家打通 SaaS 能力，实现如商家可通过店内收银系统核销抖音券，查询账单等，但不做运营。 |
抖音券 | 抖音平台提供的券码，核销时需向平台请求，回调是否可以核销。 |
三方券 | 商家或三方服务商提供券码，下单时商家/服务商回传券码，由抖音发给用户。 |
生活服务应用 | 应用是开发功能的载体，生活服务应用专门用于的和抖音来客系统打通的应用载体，接口的权限、调用和授权都基于应用维度作用。 |
行业解决方案 | 解决方案是开通接口权限的入口，如餐饮行业解决方案包含核销、查询门店等能力。 |
接口权限 | 服务商只有申请某一接口的权限，才可以调接口。 |
商家授权 | 服务商访问某个商家的数据需要商家做授权。 |
整体接入流程
整体对接流程如下；
① 入驻抖音来客
- •移动端操作：在各大应用商店下载「抖音来客」APP，根据抖音来客使用手册完成入驻。
② 绑定开发者身份
没有抖音开放平台账号
- 1.商家登录抖音来客。
- 2.在左侧导航栏选择店铺管理 > 服务应用授权，在服务应用授权页面点击商家自研服务，在商家自研服务页签点击入驻开放平台。
- 3.在入驻开放平台面板填写相关信息，点击保存并提交，等待审核成功 。
- 4.返回服务应用授权页面，在操作列点击前往开发者平台，跳转至开发者平台。
已拥有抖音开放平台账号
- 1.商家登录抖音来客。
- 2.在左侧导航栏选择店铺管理 > 服务应用授权，在服务应用授权页面点击商家自研服务，在商家自研服务页签点击绑定开发者。
- 3.在绑定开发者对话框中通过手机号/邮箱绑定开发者。
- ◦通过手机号绑定
- ◦通过邮箱绑定
- 4.绑定成功后，返回服务应用授权页面，在操作列点击前往开发者平台，跳转至开发者平台。
③ 创建应用
创建生活服务商家应用
第一步：创建生活服务应用
第二步：等待审核完成
审核时效 1 个工作日。
第三步：查看应用详情
创建成功后即可进入应用详情页，查看对接所需的应用信息
- •APPID = ClientKey
- •AppSecret = ClientSecret
创建小程序应用
第一步：创建小程序
第二步：等待审核完成
审核时效 1 个工作日。
第三步：配置服务类目
进入小程序控制台-设置-基础设置，配置服务类目。
（例如餐饮、酒店旅游、生活服务等都属于生活服务的类目）
第四步：绑定小程序行业角色
进入小程序控制台-设置-基础设置，绑定已认证的生活服务商家角色
④ 申请解决方案及接口权限
申请所需的行业解决方案及能力。
路径：「开发者平台」>「控制台」>「应用详情页」>「解决方案」。
⑤ 功能开发
若您在开发中遇到任何技术问题，请通过页面右下角“开发者助手”，提交技术工单；或联系您的BD获取更多技术支持。
接口文档
解决方案 | 适用行业 | 能力介绍文档 | OnepAPI 文档 |
餐饮行业，如快餐、奶茶、火锅、西餐、中餐等。 | |||
休闲娱乐、丽人、运动健身、足疗按摩等。 | |||
酒店、民宿等。 | |||
景点、游乐园、滑雪场等。 | |||
接口调用注意事项
域名路径：
1、接口访问域名统一为
https://open.douyin.com，务必使用 HTTPS 请求。2、接口路径详见各接口，注意路径均以
/ 结尾，/ 不可省略。公共请求头：
每个接口都需要，不再每个接口中再单独提及
参数 | 描述 | 必须 |
content-type | application/json | 是 |
调用路径为服务商 调用 抖音的接口，会传递该请求头
参数 | 描述 | 必须 |
access-token | 是 | |
log_id | 抖音侧的问题排查标示 | 是 |
调用所有接口请求头中均需传
access-token。access-token 的值需调用 /oauth/client_token/ 生成，取响应体 data.access_token，详情请参见生成 Client_token。调用 POST 接口，请求头需传
content-type: application/json。服务商侧签名规则
url 中的参数
参数名称 | 参数类型 | 参数描述 | 必需 |
client_key | string | 服务商的 client_key | 是 |
timestamp | string | 时间戳, 单位毫秒 | 是 |
sign | string | 生成签名时无视该字段 | 否 |
header 中的 sign 参数
调用路径为抖音 调用 服务商的接口，会传递以下内容在header中
参数名称 | 参数类型 | 参数描述 | 必需 |
x-life-clientkey | string | 服务商的 client_key | 是（无用处，仅作应用标识用） |
x-life-sign | string | 新签名 | 是 验签用 |
该 sign 的生成方式：
- 1.以三方服务商的 client_secret 开头；
- 2.将除 sign 之外的 URL 参数以 key=value 的形式按 key 的字典升序排列；
若为 POST 请求，还需要加上 HTTP 的 BODY，key 固定为
http_body（http_body 的内容不参与排序，加到最后）。- 3.所有的这些项以字符
&串联起来即为待签名内容 str1。发码接口的示例如下（假设
client_secret 为 yyyyyy）：str1 的内容是 yyyyyy&client_key=xxxxxx&timetamp=1624293280123&http_body=zzzzzz。然后将待签名内容
str1 计算 sha256 的值，得到的结果即为 sign。注意
抖音将用于签名生成的 httpBody 以"[]byte "类型请求服务商，服务商请不要将" []byte "反序列化成 object 再序列化 string 用于签名校验。这样会导致 json 中的字段顺序与抖音不符，同时若抖音侧将 httpBody 进行改动，也会导致签名校验不通过。
验收与上线
请重点关注以下几项：
- 1.验券接口针对返回验券结果 result 字段，必须要做业务匹配。
说明：result 结果非 0，不表示技术侧异常，而是业务提示，当 result 返回非 0 时，需做必要的业务处理。
- 2.抖音侧接口返回失败，三方系统需有重试机制。
针对服务抖动造成的接口异常，一般重试即可解决。
- 3.建议三方系统做核销结果判断时，需预校验抖音返回结果，避免双方订单信息状态不一致。
- 4.信息同步接口必接，避免抖音客服强制退款，商家无感知。
FAQ
开放平台入驻常见问题
开放平台创建应用选择哪种类型？
答：生活服务应用。
开放平台创建应用选择行业？
答：根据客户的实际经营场景进行选择。
开放平台的申请，提交后一直是审核中怎么办？
答：开放平台的审核在 1 个工作日处理完成。如果一直没有审核，可以反馈到对应的 BD 同学。
资质准备有什么注意事项
答：
- 1.入驻营业执照图片清晰，营业执照主体与入驻机构名称保持一致。
- 2.入驻函需签字并盖章，盖章主体与入驻机构名称保持一致。
- 3.服务描述需涵盖具体业务及服务场景。
小程序应用如何绑定来客账户？
答：
- 1.开发者完成入驻拥有超管身份后，可从开放平台或抖音来客发起绑定：② 绑定开发者身份
- 2.创建小程序，进入小程序控制台-设置-基础设置，配置服务类目、绑定行业角色：生活服务行业角色认证说明（第三步、第四步）
Client token 怎么获取，是否需要过期刷新？
对接常见问题
如何生成 client_token？
答：grant_type 对应参数值就是"client_credential"字符串。
核销抖音券码时，获取到的短链接如何转换成长链接短链接？
答：GET 请求获取转发的长链接地址。
biz_msg 返回无权限执行该操作？
答：需要提供企业号 uid 即 client_key，报给对接销售反馈进行接口授权。
响应参数 biz_code 除了成功 0，其他错误码是否有枚举定义，还是说服务商自己定义？
答：
- 3.其他非零的没有特殊定义, 服务商自定义就行。
- 4.需要注意的一点是, 接口请求成功的情况下 biz_code 应该返回 0，不允许下单/发码失败/拒绝退款等业务上的返回都应该通过 data.result 来标识。
- 5.biz_code 非零表示接口请求失败, 会忽略 data 中的业务字段。
确认下接口安全是否只有签名，报文不需要加密？
答：不用。
服务商侧的接口地址 URL，我们必须要按照文档中的定义是吗？
答：不用，文档中的路径只是示例, 服务商可以自定义, 但请求与响应必须按照文档来。
抖音来客常见问题
绑定自研开发者时报错“开发者账号已完成绑定，请勿重复绑定”？
答：来客账户与开发者账户只能一对一绑定，绑定后开发者账户下的所有应用均可获得来客商家账户权限。
历史已经在企业号对接的技术服务商迁移到抖音来客后是否需要重新对接？
答：历史对接的服务商不影响，但随着生活服务对外新能力的完善，建议历史服务商可重新接一套接口，方便后续的迁移。
商家是否可以继续留在企业号？
答：商家需要迁移到抖音来客，如果需要使用新接口能力，建议商家迁移，如果需要迁移，可联系对口的 BD，提前做迁移。
