用户申请退款SPI

我的收藏

调用路径

抖音 -> SaaS服务商

使用限制

接口说明

当用户发起退款申请，且需要商家审核时，需要通过此接口发消息给第三方系统。

第三方系统收到用户申请退款消息后，可立即返回处理结果：同意、拒绝、处理中；也可先返回“处理中”，然后再异步处理。建议先返回“处理中”，待商家处理后再异步通过「商家同意/拒绝退款接口」同步处理结果。

基本信息

HTTP URL	服务商侧配置的独立SPI地址
HTTP Method	POST
Scope	life.capacity.order.notice

请求头

•

content-type：application/json

•

x-bytedance-logid: 请求logid，用于问题排查。

•

x-life-clientkey: 服务商应用的client_key

•

x-life-sign: 本次请求的sha256签名,用于新版签名验签

签名规则

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

请求参数

Url参数

参数名称	参数类型	参数描述	必需
client_key	string	服务商client_key,不推荐使用	是
sign	string	老签名，不推荐使用。计算签名时不要带该参数(详见签名规则)	是
timestamp	int	请求发出时的秒时间戳，不要用作签名以外的逻辑，如有使用需求请联系抖音	是

Body 参数

参数名称	参数类型	参数描述	必需
order_id	string	订单id	是
after_sale_id	string	售后单id	是
simple_after_sale_type	int	退款类型 1、第一单撤销核销 2、第一单协同退	否
refund_reason	object	退款原因	是
.reason_code	list<int>	退款原因code	是
.desc	string	用户填写的备注信息	否
.show_reason	list<object>	退款原因文案	是
..reason_code	int	退款原因code	是
..msg	string	错误码对应的文案	是
refund_type	int64	退款类型：1-用户退款 2-客服、运营退款 3-研发退款 4-商家退款 99-系统退款
delivery_fee	int64	配送费用，单位分	否
packing_price	int64	退款打包费，单位分	否
refund_fee	int64	退货费用，单位分	是
refund_count	int64	被退款商品总件数	是
~~product_detail~~	~~object~~	~~商品信息~~	是	购物车上线后废弃
~~.product_id~~	~~string~~	~~商品id~~	是	购物车上线后废弃
~~.sku_id~~	~~string~~	~~skuid~~	是	购物车上线后废弃
~~.name~~	~~string~~	~~商品名称~~	是	购物车上线后废弃
~~.actual_amount~~	~~int64~~	~~商品实际价格~~	是	购物车上线后废弃
poi_id	string	接单poi id	否
products	list<struct>	退款商品信息	否
.product_id	string	商品id	否
.product_name	string	商品名称	否
.sku_id	string	skuid	否
.num	int	商品数量	否
.out_id	string	外部商品id	否
.commodities	list<object>	菜品搭配	否
..group_name	string	菜品类型	否
..total_count	int	此类型菜品总数	否
..option_count	int	此类型可选菜品总数	否
..items	list<object>	详细菜品列表	否
...name	string	详细菜品名称	否
...count	int	数量	否
...unit	string	单位	否
...price	int	价格，单位分	否
...product_id	string	抖音单品ID	否
...out_id	string	外部单品ID	否
...sku_id	string	抖音份量ID	否	无规格单品为-1
...out_sku_id	string	外部份量ID	否	无规格单品为-1
...sku_attr_list	list<object>	规格属性	否
....attr_name	string	规格属性名	否
....attr_key	string	规格属性ID	否
....group_key	string	规格属性组ID	否
....num	int	规格属性数量	否
....product_id	string	抖音加料ID	否
....out_id	string	外部加料ID	否

请求示例

POST 接口需附上请求体，GET 接口需将请求参数拼接至请求链接后

{
  "order_id": "1234567",
  "after_sale_id": "1234567",
  "refund_reason": {
    "reason_code": [
      123,
      234
    ],
    "desc": "不想要了",
    "show_reason": [
      {
        "reason_code": 123,
        "msg": "货品不足"
      },
      {
        "reason_code": 234,
        "msg": "已经打烊"
      }
    ]
  },
  "refund_type": 1,
  "delivery_fee": 40,
  "refund_fee": 100,
  "refund_count": 1,
  "product_detail": {
    "product_id": "123",
    "sku_id": "123",
    "name": "小蛋糕",
    "actual_amount": 100
  },
  "poi_id": "1234567",
  "user_apply_time":1689907930,
   "merchant_info": {
        "account_id":"1",
        "account_name":"名称"
    },
}

响应参数

参数名称	参数类型	参数描述
data
.result	int64	-1 处理中 2 审核通过 3 审核拒绝	是
.reject_reason	object	商家拒绝退款原因	否
..reason_code	list<int>	退款原因code	是
..desc	string	商家可填写的备注信息	否
..show_reason	list<object>	错误码对应的文案	是
...reason_code	int	退款原因code	是
...msg	int	退款原因文案	是
.error_code	int	错误码	否
.description	string	错误描述	否
.out_after_sale_id	string	外部售后单id	否

响应示例

可在后续验收时进行补充，验收文档示例（复制后使用）

正常示例

{
  "data": {
    "result": 3,
    "reject_reason": {
      "reason_code": [
        123,
        234
      ],
      "desc": "不想要了",
      "show_reason": [
        {
          "reason_code": "123",
          "msg": "货品不足"
        },
        {
          "reason_code": "234",
          "msg": "已经打烊"
        }
      ]
    },
    "error_code": 0,
    "description": ""
  },
  "extra": {
    "error_code": 0,
    "description": "",
    "sub_error_code": 0,
    "sub_description": "",
    "logid": "20220701162636010225145152030360A6"
  }
}

异常示例

待补充

错误码及错误描述

请填写服务商需特殊处理的错误码

error_code=0为处理成功，(0，999999]为未能成功处理请求时的错误码，不要传-1等小于0的值。