发券回调
收藏
我的收藏抖音侧先申请服务商发码,如果能同步返回结果则不需要本接口,如果异步返回结果则调用本接口通知抖音。
使用限制
无
接口说明
1、(非必需) 抖音侧先申请服务商发码,如果能同步返回结果则不需要本接口,如果异步返回结果则调用本接口通知抖音。
2、error_code 为 0 代表通知成功,如未成功请重试。
3、异步发码,发码失败的场景,也需要在本接口中返回 result=2 的结果。
4、10 分钟后未调用本接口,抖音会发起退款申请。如需要补发码,通过退款接口拒绝退款时补发券码。
基本信息
HTTP URL | ||||
HTTP Method | POST | |||
Scope | life.capacity.tripartite.code | |||
权限要求 |
|
请求头
参数 | 描述 | 必须 |
Content-Type | application/json | 是 |
access-token | 是 |
请求参数
Body 请求
参数名称 | 参数类型 | 参数描述 | 必需 |
order_id | string | 抖音侧的订单号(发码申请时给出) | 是 |
third_order_id | string | 如发券成功,将第三方订单号回传抖音 | 否 |
codes | list | 三方码列表(如果成功则必填) | 否 |
result | int64 | 发券接口,1=成功,2=失败 | 是 |
fail_reason | string | 失败原因(建议按照下文“失败原因”枚举回传) | 否 |
voucher | struct | 景区预售券凭证 (景区预售券必需字段,非接入景区预售券能力无需传入) | 否 |
.entrance | struct | 景区的入园项目 (若入园凭证是单独的凭证,则使用此字段用来传入园凭证。若不是单独的凭证,可使用自定义项目的字段传入) | 否 |
..project_id | string | 入园项目的唯一标识,与projects中不能重复(核销时需要) | 是 |
..id_cards | list<string> | 身份证号码,最多限100个 | 否 |
..qrcodes | list<string> | 二维码凭证,可以是一串数字,也可以是一个URL,最多限100个。每个URL长度不能超过512。 | 否 |
..certificate_nos | list<string> | 券号凭证,最多限100个 | 否 |
..urls | list<string> | url电子凭证,最多限100个。每个URL长度不能超过512。 | 否 |
..credentials | list<object> | 身份凭证列表,最多限100个 | 否 |
...credential_no | string | 证件号 | 否 |
...credential_type | int32 | 证件类型(1=身份证; 2=港澳通行证; 3=台湾通行证; 4=回乡证; 5=台胞证; 6=护照) | 否 |
..projects | list<object> | 可自定义的项目(例:景区项目索道A、索道B等) | 否 |
...project_id | string | 项目唯一标识,不能重复(核销时需要) | 是 |
...name | string | 自定义的项目名称(例:景区XXXX索道) | 是 |
...id_cards | list<string> | 身份证号码,最多限100个 | 否 |
...qrcodes | list<string> | 二维码凭证,可以是一串数字,也可以是一个URL,最多限100个 | 否 |
...certificate_nos | list<string> | 券号凭证,在C端展示为数字串,最多限100个 | 否 |
...urls | list<string> | url电子凭证,最多限100个。每个URL长度不能超过512。 | 否 |
...credentials | list<object> | 身份凭证列表,最多限100个 | 否 |
....credential_no | string | 证件号 | 否 |
....credential_type | int32 | 证件类型(1=身份证; 2=港澳通行证; 3=台湾通行证; 4=回乡证; 5=台胞证; 6=护照) | 否 |
请求示例
{ "order_id": "8000003756266535682", "codes": ["3609561912"], "third_order_id": "12313123", "result": 1, "fail_reason": "发码成功" }
响应参数
字段名称 | 字段类型 | 字段描述 |
data | object | |
.certificate_info_list | struct | 券关系列表(只有请求中回传了第三方订单号 时,会返回) |
.certificate_id | string | 券ID(抖音侧的券唯一标识) |
.code | string | 三方码 |
.error_code | int64 | 接口错误码 0代表成功 |
.description | string | 接口错误描述 |
extra | object | |
.error_code | int64 | 接口错误码 0代表成功 |
.description | string | 接口错误描述 |
logid | string | 抖音侧排查问题的标示 |
响应示例
正常示例
{ "data":{ "certificate_info_list":[ { "certificate_id":"923123123123", "code":"xx123" } ], "error_code":0, "description":"success" }, "extra":{ "error_code":0, "description":"success", "sub_error_code":0, "sub_description":"", "logid":"xxxxx", "now":1701944514 } }
异常示例
{ "extra": { "error_code": 3000001, "description": "不允许操作状态", "sub_error_code": 0, "sub_description": "", "logid": "20240525123700046E9277D156F073D112B", "now": 1716611820 }, "data": { "error_code": 3000001, "description": "不允许操作状态" } }
错误码
HTTP 状态码 | 错误码 | 描述 | 排查建议 |
200 | 2190002 | access_token无效 | 调用接口重新生成access_token |
200 | 2190004 | 应用申请接口权限 | |
200 | 2190008 | access_token过期,请刷新或重新授权 | 规范token刷新机制,检查是否有测试环境在同步刷新token |
200 | 2119001 | 参数不合法 | 更换 参数 |
200 | 2119002 | 系统繁忙,请稍候再试 | 重试 |
200 | 2119003 | 请求太过频繁,请稍后再试 | 重试 |
200 | 2119005 | 应用未获商家授权 | 联系合作商家在商家后台发起授权,并在服务商后台同意授权 |
200 | 3000005 | 订单状态不正确 | 服务商侧同步作废订单 |
200 | 3000001 | 根据实际业务错误返回 | 对照接口文档规范参数并重试 |
200 | 4000001 | 补充参数 | |
200 | 4000002 | 对照接口文档规范参数并重试 | |
200 | 5000001 | 联系抖音处理 | |
200 | 3000002 | 核销门店错误 | 检查核销门店重试 |
200 | 3000009 | 超时未回调自动发码失败 | 超10分钟未回调自动发码失败发起退款了,不要再回调了,可以通过退款补码 |
发券失败原因
fail_reason | 失败原因 | 是否透传用户 |
1 | 商品不存在 | 是 |
2 | 商品已下线 | 是 |
3 | 未到商品开始售卖时间 | 是 |
4 | 已过商品结束售卖时间 | 是 |
5 | 商品库存售罄 | 是 |
6 | 已达到购买上限 | 是 |
7 | 价格校验失败 | 否 |
20 | 其他异常(服务商自定义) | 否 |