接入前准备

通用能力

餐饮

大交通

酒旅

综合

到综团购解决方案

综合到店提货解决方案

商品发布

提货券三方码交易能力

提货券抖音码交易能力

商品查询

线索管理解决方案

历史版本文档（不推荐）

发券

我的收藏

抖音侧向商家/服务商发起券码申请，务必做到接口幂等，因为会存在网络等原因或出现超时，抖音会重试发券。

提货券订单一单只需返回一个三方码。

使用限制

无

接口 SLA

请求服务商接口，每个服务商各不相同

接口说明

1、发码中，必须十分钟内通过发码回调接口回调抖音侧告知发码结果，否则第10分钟抖音侧会自动发码失败，发起退款，会走服务商退款审核，此时服务商可以通过退款拒绝做补码操作。

2、发码成功，则必须在响应中直接返回正确的码 (后面不需要要求回调)。

3、发码失败，则抖音侧会发起退款申请，不走服务商退款审核，即服务商明确返回发码失败，不过退款审核，无法做补码，直接退款给用户

（1）接口请求成功时务必确保 error_code=0, 发放券码的结果通过 data.result 字段返回。

（2）若 error_code 不为 0，不处理 data 中的数据，抖音会十分钟内多次重试发券请求。

4、SPI 响应超时时间为 8s，超过 8s 则为无效响应。

5、抖音侧重试间隔10s、30s 、60s 、120s、120s 、240s，最多重试6次

基本信息

HTTP URL	地址由服务商提供
HTTP Method	POST
申请权限	综合到店提货解决方案 > 提货券三方码交易能力
权限要求	•需要申请权限，路径：抖音开放平台-开发者平台/服务商平台>控制台>应用详情>解决方案 •需要url配置，路径：见下方“服务商/商家侧SPI接口配置” •需要商家授权，路径：抖音来客>店铺管理>服务应用授权

签名规则

签名规则参考查看这个地址的说明

请求参数

参数名称	参数类型	参数描述	必需
order_id	string	抖音订单ID	是
order_out_id	string	外部订单ID	否
poi_id	string	预约门店id	是
sku_list	object	商品信息	是
.sku_id	string	是	抖音侧规格 ID
.product_id	string	是	抖音侧商品 ID
.sku_out_id	string	否	第三方规格 ID
.product_out_id	string	否	第三方商品 ID
.count	int	发码数量，提货券一笔订单对应一个三方码	是
.start_time	int	有效期开始时间，时间戳，秒	是
.expire_time	int	有效期截止时间，时间戳，秒	是
.groupon_type	int32	商品类型 •1：团餐券 •2：代金券 •3：次卡 •4：储值卡 •5：周期卡 •6：预约品 •7：提货券	是
open_id	string	下单人在抖音本地生活的openid	是

请求示例

URL 参数示例: https://api.example.com/namek/fulfilment/create/?client_key={你的 clientKey}×tamp=1630393201049&sign={计算出来的签名}

{
  "order_id": "12345678",
  "order_out_id": "8767383",
  "poi_id": "4212324847",
  "open_id": "1221",
  "sku_list": [{
        "sku_id": "3211",
        "product_id": "132",
        "count": 1,
        "start_time": 1664553600,
        "expire_time": 1665158399,  
        "groupon_type": 7
    }]
}

响应参数

字段名称	字段类型	字段描述	必须
data	object		是
.error_code	int64	接口错误码	是
.description	string	接口错误描述	是
.result	int	发码结果. 0:发码中,1:成功,2:失败	是
.codes	list	三方码列表	否，result返回1必填
.fail_reason	string	失败原因（建议按照下文“失败原因”枚举回传）	否
.fail_reason_desc	strin	失败原因（描述文案）	否

发券失败原因

fail_reason	失败原因	是否透传用户
1	商品不存在	是
2	商品已下线	是
3	未到商品开始售卖时间	是
4	已过商品结束售卖时间	是
5	商品库存售罄	是
6	已达到购买上限	是
7	价格校验失败	否
20	其他异常（服务商自定义）	否

响应示例

{
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 1,
    "codes": ["abcd1234"]
  }
}

错误码

error_code	description	备注
0	success	成功
110		库存不足
130		商品已下架
200		限购
300	...	抖音侧需要重试，其他错误码抖音不重试
400～499		其他自定义错误

发券

​使用限制​

​接口 SLA​

​接口说明​

​基本信息​

​签名规则​

​请求参数​

​请求示例​

​响应参数​

​发券失败原因​

​响应示例​

​错误码​