抖音开放平台Logo
开发者文档
生活服务商家应用
控制台
  • 接入前准备
  • 通用能力
  • 门店相关接口
  • 团购核销
  • 团购对账
  • 会员接入
  • 订单查询
  • 三方码
  • 预下单
  • 发券
  • 发券回调
  • 退款
  • 审核回调
  • 信息同步
  • 商品发布
  • 代运营
  • 团购退款
  • 商品查询
  • 招商入驻
  • KA核销对账
  • 餐饮
  • 大交通
  • 酒旅
  • 综合
  • 历史版本文档（不推荐）

    • 发券
    收藏
    我的收藏

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

    使用限制

    无

    接口 SLA

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

    接口说明

    1、发码中，必须十分钟内通过发码回调接口回调抖音侧告知发码结果，否则第10分钟抖音侧会自动发码失败，发起退款，会走服务商退款审核，此时服务商可以通过退款拒绝做补码操作。
    2、发码成功，则必须在响应中直接返回正确的码 (后面不需要要求回调)。
    3、发码失败，则抖音侧会发起退款申请，不走服务商退款审核，即服务商明确返回发码失败，不过退款审核，无法做补码，直接退款给用户
    （1）接口请求成功时务必确保 error_code=0, 发放券码的结果通过 data.result 字段返回。
    （2）若 error_code 不为 0，不处理 data 中的数据，抖音会十分钟内多次重试发券请求。
    4、金额说明：
    （1）商家实收（抽佣前）=原始金额-商家营销金额；
    （2）商家实收（抽佣后）此接口不提供；
    （3）平台营销金额：平台补贴的金额；
    （4）支付优惠金额：使用平台支付优惠的平台补贴金额。
    5、SPI 响应超时时间为 8s，超过 8s 则为无效响应。
    6、抖音侧重试间隔10s、30s 、60s 、120s、120s 、240s，最多重试6次

    基本信息

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

    服务商/商家侧 SPI 接口配置

    配置路径：开放平台-服务商平台/开发者平台-控制台-应用详情页-开发设置-SPI 回调
    需配置接口：
    接口
    介绍(服务商配置url时可见)
    需提供信息
    是否必填
    预下单
    抖音请求三方系统预下单
    回调地址：预下单URL
    必填
    发券
    抖音请求三方系统发码
    回调地址：发券URL
    必填
    退款
    抖音请求三方系统退款审核
    回调地址：退款URL
    必填
    信息同步
    抖音向三方系统同步退款信息
    回调地址：信息同步URL
    必填

    签名规则

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

    请求参数

    Body 请求

    参数名称
    参数类型
    参数描述
    必需
    order_id
    string
    抖音侧的订单号
    是
    third_order_id
    string
    第三方侧的订单号，如果预下单成功且回传，则会在接口中给出
    否
    count
    int
    发码数量
    是
    start_time
    int
    有效期开始时间，时间戳，秒
    是
    expire_time
    int
    有效期截止时间，时间戳，
    是
    sku
    object
    商品信息
    是
    .sku_name
    string
    抖音商品名
    是
    .sku_id
    string
    抖音的商品ID
    是
    .third_sku_id
    string
    三方服务商侧的商品ID
    是
    .groupon_type
    int32
    商品类型（1=团餐券; 2=代金券;3=次卡）
    是
    .time_card
    object
    次卡信息
    否
    ..times_count
    int32
    次卡总次数
    否
    open_id
    string
    下单人在抖音本地生活的openid
    是
    amount
    struct
    金额信息
    否
    .list_price
    int
    划线价格，单位分
    否
    .original_amount
    int
    原始金额,单位分
    否
    .pay_amount
    int
    用户实付金额,单位分
    否
    .ticket_amount
    int
    平台营销金额,单位分
    否
    .merchant_ticket_amount
    int
    商家营销金额,单位分
    否
    .fee_amount
    int
    支付手续费，单位分（已下线）
    否
    .commission_amount
    int
    达人分佣金额，单位分（已下线）
    否
    .payment_discount_amount
    int
    支付优惠金额，单位分
    否
    .coupon_pay_amount
    int
    券实付金额（=用户实付金额+支付优惠金额），单位分
    否
    ticket_rule
    object
    票务规则
    否
    .code_sending_info
    list(int)
    凭证发放方式，多选1=身份 2=券号 3=券码 6=链接URL
    是
    .code_type
    int
    券码类型；2=三方码
    是
    .url_type
    int
    外部链接内容，code_sending_info包含6；1=静态二维码 2=其他
    ​
    tourists
    list(object)
    出行人信息
    否
    .name
    string
    姓名
    2024年2月29日起，若用户下单商品不属于下列一级商品类目（住宿(8000000), 游玩(18000000), 度假旅游服务(32000000), 交通出行(31000000)），该字段脱敏
    否
    .phone
    string
    联系电话
    2024年2月29日起，若用户下单商品不属于下列一级商品类目（住宿(8000000), 游玩(18000000), 度假旅游服务(32000000), 交通出行(31000000)），该字段脱敏
    否
    .id_card
    string
    身份证号码
    2024年2月29日起，若用户下单商品不属于下列一级商品类目（住宿(8000000), 游玩(18000000), 度假旅游服务(32000000), 交通出行(31000000)），该字段脱敏
    否
    .credential_type
    int32
    身份证件类型（1=身份证; 2=港澳通行证; 3=台湾通行证; 4=回乡证; 5=台胞证; 6=护照）
    否

    请求示例

    URL 参数示例: https://api.example.com/namek/fulfilment/create/?client_key={你的 clientKey}×tamp=1630393201049&sign={计算出来的签名}
    {
    "order_id": "12345678",
    "third_order_id": "8767383",
    "count": 2,
    "sku": {
        "sku_id": "23456",
        "sku_name": "手机xxx",
        "third_sku_id": "345678",
        "groupon_type": 1
    },
    "amount": {
        "original_amount": 10000,
        "pay_amount": 8000,
        "ticket_amount": 1000,
        "merchant_ticket_amount": 1000,
        "payment_discount_amount": 1000,
        "coupon_pay_amount": 1000
    },
    "contact": {
        "name": "张三",
        "phone": "13800000000"
    },
    "tourists": [
        {
            "name": "张三",
            "phone": "13800000000",
            "id_card": "310115199807013370",
            "credential_type": 1
        },
        {
            "name": "李四",
            "phone": "13900000000",
            "id_card": "310115199912130020",
            "credential_type": 1
        }
    ],
    "start_time": 1664553600,
    "expire_time": 1665158399
}

    响应参数

    团购三方码响应参数

    字段名称
    字段类型
    字段描述
    必须
    data
    object
    ​
    是
    .error_code
    int64
    接口错误码
    是
    .description
    string
    接口错误描述
    是
    .result
    int
    发码结果. 0:发码中,1:成功,2:失败
    是
    .codes
    list
    三方码列表
    否，result返回1必填
    次卡场景下，不允许多item使用同一个券码Code
    响应示例
    {
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 1,
    "codes": ["abcd1234"]
  }
}

    景区预售券响应参数

    字段名称
    字段类型
    字段描述
    必需
    data
    object
    ​
    ​
    .error_code
    int64
    接口错误码
    是
    .description
    string
    接口错误描述
    是
    .result
    int
    发码结果. 0:发码中 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。
    否
    ...credentials
    list<object>
    身份凭证列表，最多限100个
    否
    ....credential_no
    string
    证件号
    否
    ....credential_type
    int32
    证件类型（1=身份证; 2=港澳通行证; 3=台湾通行证; 4=回乡证; 5=台胞证; 6=护照）
    否
    ...urls
    list<string>
    url电子凭证，最多限100个。每个URL长度不能超过512。
    否
    ...certificate_nos
    list<string>
    券号凭证，最多限100个
    否
    ..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=护照）
    否
      1.发码结果
      •发码中，则必须十分钟内通过凭证回调接口回调抖音侧告知结果，否则会自动取消预约
      •发码成功，则必须在响应中直接返回正确的凭证 (后面不需要回调)
      •发码失败，则抖音侧会预约失败，用户可用再次发起预约
      •接口请求成功时务必确保 error_code=0, 发放券码的结果通过 data.result 字段返回。
      •若 error_code 不为 0，不处理 data 中的数据，抖音会十分钟内多次重试发券请求。
      2.凭证
      •entrance和projects不能同时都为空
      •id_cards、qrcodes、certificate_nos不能同时都为空
      •id_cards、qrcodes、certificate_nos返回的各自集合长度不能超过请求的count
      •如果请求带了tourists，则返回的id_cards集合身份证信息必须包含在tourists中
    响应示例
    发码中
    {
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 0
  }
}
    发码成功
    {
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 1,
    "voucher": {
      "entrance": {
        "project_id": "1",
        "id_cards": ["310115199807013370", "310115199912130020"],
        "qrcords": ["qr_code1_096700560962", "qr_code1_806011925184"],
        "certificate_nos": ["a_096700560962", "a_806011925184"]
      },
      "projects": [
        {
          "name": "xx景区A项目",
          "project_id": "2",
          "id_cards": ["310115199807013370", "310115199912130020"],
          "qrcodes": ["qr_code2_806011925184", "qr_code2_534318095199"],
          "certificate_nos": ["b_806011925184", "b_534318095199"]
        }
      ]
    }
  }
}
    ​