历史版本文档（不推荐）

我的收藏

一、变更记录

变更时间	变更内容	版本号
2024.07.24	1.发放凭证接口废弃支付手续费与达人分佣手续费	v1.0.2
2023.08.11	1.核销接口废弃~~poi_id~~参数，新增核销模式参数，调整券码接口格式 2.退款接口新增退款ID和退款类型参数 3.退款通知接口新增退款ID和退款类型参数	v1.0.1
2023.07.24	创建文档	v1.0.0

二、名词解释

名词	说明
SPI	抖音侧制定接口规范，外部服务商/开发者按照规范实现http接口，抖音侧发起接口调用，将数据传送给开发者并接收开发者同步反馈。
Openapi	抖音侧提供http接口，外部服务商/开发者发起调用，将数据传给抖音或者从抖音侧主动查询需要的数据。

三、交互流程

四、接入前期准备

商家需先完成“抖音来客”入驻，参考：✈【抖音来客】机票系统操作手册

入驻开放平台

入驻开放平台流程：✈【抖音来客】机票系统操作手册

创建应用

如复用已有应用，请注意【发放凭证】SPI是复用接口，与预售券、三方码团购一样

创建应用及绑定开发者身份流程：✈【抖音来客】机票系统操作手册

生成 access_token

通过请求参数ClientKey&ClientSecret调用/oauth/client_token/生成的token，此token不需要用户授权

示例: clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ

参考 client_token 接口：https://developer.open-douyin.com/docs/resource/zh-CN/dop/develop/openapi/account-permission/client-token，body 返回 access_token

备注：需每2小时更新（开发阶段给到的测试账号不同，按对应文档说明使用，参考步骤2）

商家回调地址配置

系统已支持线上配置SPI，可线上配置

参考SPI 签名机制：https://developer.open-douyin.com/docs/resource/zh-CN/local-life/develop/preparation/signruleintroduce

使用SPI接口涉及：创建订单、通知支付结果、三方码发放凭证、申请退款、退款通知

目前已支持线上配置webhook，在开发设置中配置：

参考webhook 消息推送：https://developer.open-douyin.com/docs/resource/zh-CN/local-life/develop/preparation/massages.push

签名规则

SPI签名规则说明（new）

签名规则，抖音开发平台文档里提到有两套签名算法，两种签名的计算方式有些微差别，任选其中一种即可，推荐校验 header 中的签名，安全性会更高一些。

url 中的参数

参数名称	参数类型	参数描述	必需
client_key	string	服务商的client_key	是
timestamp	string	时间戳, 单位毫秒	是
sign	string	生成签名时无视该字段	否

header 中的 sign 参数

调用路径为抖音调用服务商的接口，会传递以下内容在header中

参数名称	参数类型	参数描述	必需
x-life-clientkey	string	服务商的client_key	是无用处仅作应用标识用
x-life-sign	string	新签名	是验签用

该 sign 的生成方式:

以三方服务商的 client_secret 开头; 然后将除 sign 之外的 URL 参数以 key=value 的形式按 key 的字典升序排列; 若为 POST 请求, 还需要加上 HTTP 的 BODY, key 固定为 http_body(http_body 的内容不参与排序，加到最后)。最后所有的这些项以字符'&'串联起来即为待签名内容 str1. 发码接口的示例如下(假设 client_secret 为 yyyyyy):

str1 的内容是 yyyyyy&client_key=xxxxxx&timestamp=1624293280123&http_body=zzzzzz 【注意：client_key是URL参数中动态获取，请不要直接固定写死，以免造成验签失败】

然后将待签名内容 str1计算 sha256 的值, 得到的结果即为 sign。

抖音将用于签名生成的 httpBody 以[]byte 类型请求服务商，服务商请不要将[]byte 反序列化成 object 再序列化 string 用于签名校验。这样会导致 json 中的字段顺序与抖音不符，同时若抖音侧将 httpBody 进行改动，也会导致签名校验不通过。

五、接口详情

接口名称	是否必接	接口说明	接口类型
发码	必接	抖音侧服务商接单成功后向服务商发起发放凭证申请。	SPI
履约核销	必接	1.核销凭证，必传字段order_id，现状默认整单核销 2.如果接口失败请重试，控制重试策略不要太频繁，核销调用失败会有兜底核销逻辑 3.不支持提前核销 4.需在商品实际使用后，商品为不可退状态时，再向抖音推送核销	openapi
退款申请	必接	抖音侧请求第三方申请退款，允许同步返回审核结果。当退款审核结果为接受，若传入手续费小于等于平台计算手续费，以平台计算罚金为准，否则视为拒绝。	SPI
发券回调	同步发码非必接异步发码必接	服务商回调抖音接口，回传三方码	openapi
退款通知	必接	抖音侧完成退款后，通知第三方实际退款结果。	SPI

开发者文档

航司saas对接解决方案