	开放平台地址	接入指南
KA自研商家	https://developer.open-douyin.com/	https://partner.open-douyin.com/docs/resource/zh-CN/dop/ability/life-service-ability/life.capacity/ka.guide
技术服务商	https://partner.open-douyin.com/	https://partner.open-douyin.com/docs/resource/zh-CN/dop/ability/life-service-ability/life.capacity/guide/

服务商创建应用

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

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

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

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

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

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

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

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

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

开通应用的解决方案

在应用详情中，点击解决方案，选择【到综团购预约解决方案】申请开通。审核时效 3 个工作日。

生成 access_token

通过请求参数ClientKey&ClientSecret调用/oauth/client_token/生成的token，此token不需要用户授权。示例: clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ

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

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

商家回调地址配置

•

spi回调地址

系统已支持线上配置SPI，技术服务商可线上配置：

参考SPI 签名机制：https://partner.open-douyin.com/docs/resource/zh-CN/local-life/develop/OpenAPI/preparation/signruleintroduce（包含加密字段解密方法）

•

webhook

订阅webhook事件：https://developer.open-douyin.com/docs/resource/zh-CN/dop/develop/webhooks/update-event-subscription-status

webhook事件名暂时未出现在订阅事件列表里，上述接口调用成功即可

webhook格式见第四章第六节（商品审核结果通知）。 webhook只需配置一个url，商家自行根据event事件名路由，以event对应的结构体反序列化相应内容。

如若商家配置失败，可联系抖音开发处理（需提供申请了加了权限后ck对应的token ）

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

参考webhook 消息推送：https://partner.open-douyin.com/docs/resource/zh-CN/dop/develop/openapi/life-service-open-ability/life.capacity/beforeinsert/massages.push

抖音SPI调用的验签case

参考文档： https://partner.open-douyin.com/docs/resource/zh-CN/local-life/develop/preparation/signruleintroduce

注：http_body值需要读取HTTP请求原始字符串，切勿序列化后再反序列化，否则字段顺序可能会乱

原始字符串： 111111&client_key=sandbox113&timestamp=1693991210709&http_body={"currency":"CNY","occupancies":[{"first_name":null,"last_name":null,"name":"2JhtVGPmblZr1LAI7NE/og==","phone":"","license_type":0,"license_id":""}],"hotel_id":"7216656839890208829","check_out_date":"2023-09-08","number_of_units":1,"number_of_guests":2,"daily_rates":[{"period_start_date":"2023-09-07","period_end_date":"2023-09-08","original_amount":10,"amount_before_tax":10,"currency":"CNY"}],"meals":[{"meal_type":1,"meal_num":1}],"biz_type":2021,"room_id":"7247049008404203560","rate_plan_id":"1776079051954195","check_in_date":"2023-09-07","total_amount":10}

sha256值:  f8337d76e78dd42cb4e22fe9ec24bee6a7798eac625bec46e50537228e16ae31

二、整体说明（必读）

时序图

1.1.1 商品管理

1.1.2 库存推送

1.1.3 库存定时周期拉取

1.1.4 库存触发拉取

1.1.4 交易流程

请求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.下文API接口返回示例出于精简考虑，仅给出了data中的业务字段，其他信息可参考以上说明
5.加密字段解密参见：https://partner.open-douyin.com/docs/resource/zh-CN/local-life/develop/preparation/decrypt
6.注意：SPI请求体中包含的可选字段在一些场景下可能不会返回需要商户兼容处理
7.注意：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

三、接口-商品直连

权限申请说明

开放平台管理后台找到【到综团购预约解决方案】，点击查看详情，根据接口所在的能力来勾选开通，能力名称参考下方接口列表的能力名称

接口列表

业务场景/能力名称	是否必接	接口	说明
商品预约类价量态操作		到综接待单元保存实时库存
		到综接待单元库存更新通知
		创建or更新到综接待单元库存sku
综合预约订单确认接拒单		综合预约品确认接拒单
综合预约订单查询		综合预约品订单查询
商品预约类价量态操作		库存拉取
综合预约订单创建	必接	创建预约单	抖音侧调用第三方进行预约单创单
综合预约三方订单查询		查询外部订单	抖音侧调用第三方进行订单查询（用于平台和三方状态不一致时兜底处理，如三方未返回平台接单状态，那么平台会在超时拒单前进行一次订单查询，保障状态一致）
综合预约订单支付通知		支付结果通知	抖音侧调用第三方进行支付结果通知(如果是支付后创单则不需要接入本接口)
三方码发布		发券回调	抖音侧先申请服务商发码，如果能同步返回结果则不需要本接口，如果异步返回结果则调用本接口通知抖音。
		审核回调	审核结果为拒绝时必须要告知抖音拒绝原因，若没有原因将会返回报错，拦截本次审核结果 2、「退款」接口中抖音的请求中 certificate_id 对应 code 为空，且最终服务商侧的审核结果为拒绝，必须在回调抖音时将 code 补上，否则将返回报错，拦截本次审核结果(具体参数见下方请求参数) 3、返回结果中 error_code 为 0 代表通知成功；其他值可当作通知失败，需做重试 4、若服务商未能在收到「退款」请求后 24 小时内成功告知抖音审核结果，那么本次请求将会被自动审核通过，完成后续的退款流程
		发券	抖音侧向商家/服务商发起券码申请，务必做到接口幂等，因为会存在网络等原因或出现超时，抖音会重试发券。
		退款	抖音侧向服务商发起退款的申请。
		信息同步	用于抖音侧向商家侧同步退款状态信息变更。
团购核销		验券准备	抖音团购券码的核销, 需要先调用本接口, 查询订单的券列表，选择要验的券，再调用验券接口，核销券码。
		验券	用于核销券码，同时适用于抖音团购券码与三方券码，抖音券码的核销需要先调用准备接口，再调用本接口，三方券码的核销直接调用本接口即可。
		撤销核销	针对“抖音团购券码、三方券码”两种券码误核销之后的撤销操作，订单状态由“已使用”回改为“待使用”，用于验券错误需要撤回验券等场景，有时间限制，验券超过一个小时就不可再撤销。 extra.error_code、data.error_code 均为 0 代表撤销成功。
		券状态查询	在核销的异常场景情况下，对抖音码团购、次卡券进行状态查询。
		券状态批量查询	用于批量查询抖音券码和三方券码的状态