到综团购预约品解决方案
收藏变更记录
变更时间 | 变更内容 | 版本号 |
6.30 | 注意本文档内字段内容为初版，可能会有些许变更 | v0.9 |
7.30 | 正式版本 | v1.0 |
业务介绍
场景简介
面向需用户提前预约的场景，为休闲娱乐、丽人、健身等本地生活商家/服务商提供通用的预约解决方案，包括：商品发布、预约管理、核销与对账的完整交易闭环能力。
接入流程
开发者入驻和接入
根据以下指南完成开放平台的入驻和自助化接入
二、整体说明（必读）
时序图
1.1.1 商品管理
1.1.2 库存推送
1.1.3 库存定时周期拉取
1.1.4 库存触发拉取
1.1.5 交易流程
请求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 | 必填 | |
» 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中的业务字段，其他信息可参考以上说明
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
三、接口-商品直连
权限申请说明
开放平台管理后台找到【综合团购预约解决方案】，点击查看详情，根据接口所在的能力来勾选开通，能力名称参考下方接口列表的能力名称
接口列表
业务场景/能力名称 | 是否必接 | 接口 | 说明 |
商品预约类价量态操作 | | | |
| | ||
| | ||
综合预约 订单确认接拒单 | | | |
综合预约订单查询 | | | |
商品预约类价量态操作 | | | |
综合预约订单创建 | 必接 | 抖音侧调用第三方进行预约单创单 | |
综合预约三方订单查询 | | 抖音侧调用第三方进行订单查询（用于平台和三方状态不一致时兜底处理，如三方未返回平台接单状态，那么平台会在超时拒单前进行一次订单查询，保障状态一致） | |
综合预约订单支付通知 | | 抖音侧调用第三方进行支付结果通知(如果是支付后创单则不需要接入本接口) | |
三方码发布 | | 抖音侧先申请服务商发码，如果能同步返回结果则不需要本接口，如果异步返回结果则调用本接口通知抖音。 | |
| 审核结果为拒绝时必须要告知抖音拒绝原因，若没有原因将会返回报错，拦截本次审核结果 2、「退款」接口中抖音的请求中 certificate_id 对应 code 为空，且最终服务商侧的审核结果为拒绝，必须在回调抖音时将 code 补上，否则将返回报错，拦截本次审核结果(具体参数见下方请求参数) 3、返回结果中 error_code 为 0 代表通知成功；其他值可当作通知失败，需做重试 4、若服务商未能在收到「退款」请求后 24 小时内成功告知抖音审核结果，那么本次请求将会被自动审核通过，完成后续的退款流程 | ||
| 抖音侧向商家/服务商发起券码申请，务必做到接口幂等，因为会存在网络等原因或出现超时，抖音会重试发券。 | ||
| 抖音侧向服务商发起退款的申请。 | ||
| 用于抖音侧向商家侧同步退款状态信息变更。 | ||
团购核销 | | 抖音团购券码的核销, 需要先调用本接口, 查询订单的券列表，选择要验的券，再调用验券接口，核销券码。 | |
| 用于核销券码，同时适用于抖音团购券码与三方券码，抖音券码的核销需要先调用准备接口，再调用本接口，三方券码的核销直接调用本接口即可。 | ||
| 针对“抖音团购券码、三方券码”两种券码误核销之后的撤销操作，订单状态由“已使用”回改为“待使用”，用于验券错误需要撤回验券等场景， 有时间限制，验券超过一个小时就不可再撤销。 extra.error_code、data.error_code 均为 0 代表撤销成功。 | ||
| 在核销的异常场景情况下，对抖音码团购、次卡券进行状态查询。 | ||
| 用于批量查询抖音券码和三方券码的状态 |
