航司saas对接解决方案
收藏一、变更记录
变更时间 | 变更内容 | 版本号 |
2024.07.24 |
| v1.0.2 |
2023.08.11 |
| v1.0.1 |
2023.07.24 | 创建文档 | v1.0.0 |
二、名词解释
名词 | 说明 |
SPI | 抖音侧制定接口规范，外部服务商/开发者按照规范实现http接口，抖音侧发起接口调用，将数据传送给开发者并接收开发者同步反馈。 |
Openapi | 抖音侧提供http接口，外部服务商/开发者发起调用，将数据传给抖音或者从抖音侧主动查询需要的数据。 |
三、交互流程
四、接入前期准备
入驻开放平台
- 1.入驻开放平台流程：✈【抖音来客】机票系统操作手册
创建应用
如复用已有应用，请注意【发放凭证】SPI是复用接口，与预售券、三方码团购一样
- 1.创建应用及绑定开发者身份流程：✈【抖音来客】机票系统操作手册
生成 access_token
- 1.通过请求参数ClientKey&ClientSecret调用/oauth/client_token/生成的token，此token不需要用户授权
示例: clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
- 2.参考 client_token 接口：https://developer.open-douyin.com/docs/resource/zh-CN/dop/develop/openapi/account-permission/client-token，body 返回 access_token
- 3.备注：需每2小时更新（开发阶段给到的测试账号不同，按对应文档说明使用，参考步骤2）
商家回调地址配置
- 1.系统已支持线上配置SPI，可线上配置
- b.使用SPI接口涉及：创建订单、通知支付结果、三方码发放凭证、申请退款、退款通知
- c.目前已支持线上配置webhook，在开发设置中配置：
签名规则
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 的生成方式:
- 1.以三方服务商的 client_secret 开头; 然后将除 sign 之外的 URL 参数以 key=value 的形式按 key 的字典升序排列; 若为 POST 请求, 还需要加上 HTTP 的 BODY, key 固定为 http_body(http_body 的内容不参与排序，加到最后)。最后所有的这些项以字符'&'串联起来即为待签名内容 str1. 发码接口的示例如下(假设 client_secret 为 yyyyyy):
- 2.str1 的内容是 yyyyyy&client_key=xxxxxx×tamp=1624293280123&http_body=zzzzzz 【注意：client_key是URL参数中动态获取，请不要直接固定写死，以免造成验签失败】
- 3.然后将待签名内容 str1计算 sha256 的值, 得到的结果即为 sign。
- 4.抖音将用于签名生成的 httpBody 以[]byte 类型请求服务商，服务商请不要将[]byte 反序列化成 object 再序列化 string 用于签名校验。这样会导致 json 中的字段顺序与抖音不符，同时若抖音侧将 httpBody 进行改动，也会导致签名校验不通过。
五、接口详情
接口名称 | 是否必接 | 接口说明 | 接口类型 |
必接 | 抖音侧服务商接单成功后向服务商发起发放凭证申请。 | SPI | |
必接 |
| openapi | |
必接 | 抖音侧请求第三方申请退款，允许同步返回审核结果。当退款审核结果为接受，若传入手续费小于等于平台计算手续费，以平台计算罚金为准，否则视为拒绝。 | SPI | |
同步发码非必接 异步发码必接 | 服务商回调抖音接口，回传三方码 | openapi | |
必接 | 抖音侧完成退款后，通知第三方实际退款结果。 | SPI |
