历史版本文档（不推荐）

度假行业解决方案

我的收藏

业务介绍

场景简介

预售券

预售券支持用户“先买券，后预约使用”，方便用户囤货和商家卖货的一种商品类型

可参考与以下商品类型差异：
•日历产品：选择日期固定价格、固定使用用户后下订（需求推进中）
•团购券：购买后直接去商家核销使用，无需预约（旅行社行业暂不支持）

日历套餐

日历套餐：选择日期固定价格、明确使用用户后下订；当前仅支持酒景套餐类商品

可参考与以下商品类型差异：
•预售券：支持用户“先买券，后预约使用”，方便用户囤货和商家卖货的一种商品类型
•团购券：购买后直接去商家核销使用，无需预约（旅行社行业暂不支持）

名词解释

client_key: 三方通过接口对接抖音开放平台前需要创建应用，应用的AppId等价于client_key，二者值相同，用于唯一区分一个应用

client_secret：等价于生活服务应用中的AppSecret, 搭配client_key可通过文档 - 抖音开放平台 - 服务商平台 (open-douyin.com)获取access_token

access_token: 接口调用的凭证，携带在请求header中用于身份识别

测试账号：为了方便三方与抖音侧进行联调测试，三方可向抖音侧BD申请测试账号（包含服务商测试账号和对应的测试商家账号），测试账号的应用和权限申请抖音侧已经提前准备好，可直接投入开发测试使用

接入前准备

测试账号申请

开发测试期间，使用抖音提供的沙箱账号进行测试，绑定商家手机号，即可用商家手机号以沙箱账号身份登录来客，测试完成后，再使用商家正式账号

沙箱账号申请流程：需要与所负责区域对齐api接入需求后，由BD建群邀请商家技术等相关人员进群后，与群内的TS同学对接申请。

沙箱账号已绑定自研商家，可登录抖音来客，自带clientKey应用，secret，固定token，接口调用权限，无需再走入驻开平和申请授权流程

开通认证开发者账号

•

技术服务商：技术服务商接入指南

•

自研：自研商家接入指南

创建生活服务应用

参考文档 https://partner.open-douyin.com/docs/resource/zh-CN/dop/ability/life-service-ability/life.capacity/guide/

创建第三方生活服务商家应用：

填写相关信息，创建应用。

应用创建成功后，可进入应用详情页查看ClientKey&ClientSecret

等待应用审核完成。审核时效 3 个工作日。

开通解决方案及能力

开通流程

1、登录服务商平台。

2、在右上角点击「控制台」，在「我的应用」页面选择「生活服务商家应用」，然后点击目标应用。

3、在应用左侧导航栏点击「解决方案」，在「解决方案」页面到店餐饮行业解决方案的「操作」列点击「查看详情」。

4、在【度假行业解决方案】面板中选择所需的能力，点击「申请开通」，等待平台审核。审核通过后，即可以使用相关能力。审核时效 3 个工作日。

特别说明：在申请度假解决方案时，不管是日历票还是预售券，都请一并申请右侧红框的能力。

否则商家在发布商品选择对接直连系统时会搜索不到授权的开放平台应用

商家授权技术服务商 or 绑定自研服务商

若是技术服务商，需商家在抖音来客授权给技术服务商：

若是自研商家，需商家在商家自研服务里绑定开发者：

服务商/自研需要在开发者平台/服务商平台处理授权申请

开发指南

•

生成client_token

•

生活服务商家应用SPI调用指南

•

生活服务商家应用webhook 调用指南

请求header内容

调用抖音侧API接口时，需要在header填充token信息用于鉴权；抖音侧提供的测试账号和三方自行申请的正式账号token填充方式有所不同，请注意区分！

若无特殊说明，以下header的内容适用下文所有API接口

测试账号

参数名称	参数类型	必须参数	备注
» access-token	string	必填	使用douyin.xxx或者ka.xxx前缀的token （申请测试账号时，由抖音侧提供）
» Content-Type	固定值	必填	application/json
» X-Sandbox-Token	固定值	必填	1

正式账号

参数名称	参数类型	必须参数	备注
» access-token	string	必填	根据这个地址获取的token
» Content-Type	固定值	必填	application/json

API接口说明

本文档所有api请求结果，若无特殊说明则都遵循以下规则
1.返回体中有data, extra, base_resp字段,其中base_resp三方可忽略，data用于传输数据，extra用于携带附属信息； data.error_code和extra.error_code值相同，可任取其一用于状态判断
2.error_code为0，表示请求成功； error_code为非0状态时，表示请求失败，可结合description查看失败原因，失败时抖音侧可能不会返回业务字段
3.部分接口业务字段中可能会有业务状态码，判断顺序：http请求状态码>error_code>业务状态码
4.错误码说明详见：旅行社直连相关枚举& 常见错误码_抖音开放平台
5.下文API接口返回示例出于精简考虑，仅给出了data中的业务字段，其他信息可参考以上说明
6.加密字段解密参见：解密方法
7.注意：SPI请求体中包含的可选字段在一些场景下可能不会返回需要商户兼容处理
8.注意：SPI请求体中包含的字段在不存在的情况下可能会返回NULL值，需要商户处理好兼容逻辑
•spi或openapi http均为post

•

成功示例

{
    "base_resp": { // 可忽略
        "status_code": 0,
        "status_message": "success"
    },
    "extra": {
        "error_code": 0,
        "description": "success",
        "sub_error_code": 0,
        "sub_description": "",
        "logid": "20230614120842393C34F06C7FBA04F355",
        "now": 1686715725
    },
    "data": {
        "业务字段1":"业务值1",
        "业务字段2":"业务值2",
        "error_code": 0,
        "description": "success"
    }
}

•

失败示例

{
    "base_resp": { //可忽略
        "status_message": "时间范围不合法,格式为`2006-01-02`,且最大时间不能超过距今365天,起始时间不能超过结束时间,起始时间不能早于今天",
        "status_code": 299000044
    },
    "extra": {
        "error_code": 3000001,
        "description": "时间范围不合法,格式为`2006-01-02`,且最大时间不能超过距今365天,起始时间不能超过结束时间,起始时间不能早于今天",
        "sub_error_code": 0,
        "sub_description": "",
        "logid": "202306141347349C568D61A00C5319C55A",
        "now": 1686721655
    },
    "data": {
        "description": "时间范围不合法,格式为`2006-01-02`,且最大时间不能超过距今365天,起始时间不能超过结束时间,起始时间不能早于今天",
        "error_code": 3000001,
    },
}

•

spi返回值结构

返回字段需在data结构体内，必须按照下图格式返回（返回值需全部在data的属性key内）可直接参考spi接口返回值样例

{
    "data": {
        "error_code": 0,
        "description": "success",
        "XXXX":"XXXXX"
    }
}

重试规则

•

重试次数：12次

•

重试间隔：5s

开发者自测、验收、上线流程

补充自测-验收-上线流程及验收文档
抖音码验收文档：暂不需要验收
如果有对接群，需在对接群内与抖音测TS同学沟通验收流程，验收通过后方可上线
有验收工具的话这里可以附验收工具操作 SOP ，手工验收的就附手工验收 SOP

业务对接流程

一些强弱依赖稳定性说明
1.抖音通知服务商创建订单，若三方系统没有创单成功，没有返回out_order_id,抖音侧这笔订单还可以进行预约，由于服务商系统中没有这笔订单，用户发起预约后到商家确认接单这时，服务商无法执行接单操作，这笔预约订单只有超时取消操作
  兜底解法
◦抖音系统会在创单失败后，连续重试大概15次（一直失败后无后续自动补偿机制）。服务商修复好后可告知抖音进行接口人工补偿
◦当服务商确实无法接单时，会根据商品上配置的接单时长计算最晚接单时间，到期后直接取消该预约单

创单和支付可选交易模式，需要对接时沟通支付后创单还是先创单再支付（预售默认支付后创单）如果是支付前创单需要以最终支付结果通知为准，创单时用户可能未支付完成。
支付后创单时，创单请求结构体内才会有支付信息，否则请监听支付通知
若需要支付前创单，请告知抖音测技术支持同学，需针对沙箱账号或正式clientKey维度更改配置。（需走线上发布流程）

预售券

时序图

正向交易

逆向交易

接口清单

能力	是否必接	接口文档	描述
旅行社poi查询	必须对接	查询订单商品快照的poi	三方系统查询抖音创建的订单所关联商品的poi信息，内部自行匹配后在消费凭证中返回对应的poiid
酒旅旅行社-预售券价量态操作	选接	预售券价量态-更新预售商品价库及属性	商家在来客后台创建商品成功后，通过接口调整预售券的价格库存信息
	选接	预售券价量态-更新预定商品日历库存	商家在来客后台创建商品成功后，通过接口调整预售券关联预约商品的价格库存信息
	选接	预售券价量态-获取预售券商品价量态	商家在来客后台创建商品成功后，可以通过接口查询到商品基础信息、商品状态以及预售商品及可预约商品的价格库存信息
旅行社确认接口	必须对接	预售券确认接单	抖音侧通知第三方支付成功后，第三方需要在商品上单中设置的接单时间内通知抖音侧接单结果，超时会拒单。采用异步确认
酒旅-旅行社支付结果通知	必须对接	预售券支付通知	抖音侧通知第三方支付成功。供应商交易模式为支付后创单的情况下抖音不会调用该spi
酒旅-旅行社创建订单	必须对接	预售券创建预约订单	抖音侧调用第三方创建旅行社预约订单
酒旅-旅行社订单取消通知	必须对接	预售券订单取消通知	用于预售订单/预约单取消时，抖音侧通知三方系统取消订单（SPI）。
酒旅-旅行社退款结果通知	必须对接	预售券退款通知	订单退款时，抖音侧通知三方系统退款结果。当订单退款时，如果订单中没有第三方订单号，则无需通知三方系统。（SPI）
酒旅-旅行社创建预售订单	必须对接	预售券创建预售订单	创建预售券订单 SPI。
酒旅预售券商品上架和下架信息推送	选接	商品上下架	商家在来客后台创建商品成功后，通过接口操作上下架状态变更。
酒旅预售券商品上架和下架信息推送	选接	商品审核结果通知	商家在来客后台提交商品审核，或通过直连操作修改价格库存信息审核通过后，推送至商家（SPI）
KA核销对账	选接	账单详细查询	商家通过接口查询自己账单详情。

度假日历套餐

时序图

正向交易

逆向交易

接口清单

能力	是否必接	接口文档	描述
旅行社poi查询	必须对接	查询订单商品快照的poi	三方系统查询抖音创建的订单所关联商品的poi信息，内部自行匹配后在消费凭证中返回对应的poiid
旅行社日历品操作	建议对接	旅行社日历品价量态信息同步	商家在来客后台创建商品成功后，通过接口调整日历套餐的价格库存信息最大日期范围不超过当天起360天（含）价库实时生效，无需审核
	建议对接	日历品商品价量态信息查询	商家在来客后台创建商品成功后，可以通过接口查询到商品基础信息、商品状态以及价格库存信息；最多360天内；仅返回可售日期+不可售日期且已设置价库的日期
	建议对接	日历套餐价库信息拉取更新（SPI）	商家在来客后台创建商品成功后，通过接口调整日历套餐的价格库存信息
旅行社日历品价量态操作	建议对接	日历商品操作上下架	•下架操作：商品为“上架”“审核中”状态时可进行下架操作，其他状态返回失败 •返回信息：商品当前状态未生效，无需重复操作 •需要校验商品归属于当前商家，如果不属于则拒绝请求 •返回信息：当前商品ID无效，请检查后重试 •仅可设置旅行社商品且为直连商品 •支持批量，单次最多10个商品
旅行社日历品价量态操作	建议对接	商品审核结果通知（webhook）	商家在来客后台提交商品审核，或通过直连操作修改价格库存信息审核通过后，推送至商家
旅行社日历品行业交易商家接单	必须对接	旅行社日历套餐接单	抖音侧通知第三方支付成功后，第三方需要在商品上单中设置的接单时间内通知抖音侧接单结果，超时会拒单。采用异步确认。
旅行社日历品行业交易可定检查	必须对接	可定检查（SPI）	可定检查。当且仅当明确告知可定检查失败时拒绝用户下单，其余情况默认放行
旅行社日历品行业交易创建订单	必须对接	旅行社日历品行业交易创建订单	用户下单后，抖音侧调用第三方创建旅行社日历套餐订单
旅行社日历品行业交易支付结果通知	非一步订单必须对接	旅行社日历品行业交易支付结果通知	抖音侧通知第三方支付成功。供应商交易模式为支付后创单的情况下抖音不会调用该spi
旅行社日历品行业交易退款成功通知	必须对接	日历品行业交易订单退款结果通知（SPI）	订单退款时，抖音侧通知三方系统退款结果。当订单退款时，如果订单中没有第三方订单号，则无需通知三方系统
旅行社日历品-订单取消通知	必须对接	旅行社日历品订单取消	用于预售订单/预约单取消时，抖音侧通知三方系统取消订单
KA核销对账		账单详细查询	商家通过接口查询自己账单详情。