抖音开放平台Logo
控制台

验券准备

更新时间 2024-07-24 02:58:49
收藏
我的收藏

接口说明

抖音团购券码的核销, 需要先调用本接口, 查询订单的券列表，选择要验的券，再调用验券接口，核销券码。

  1. 抖音团购券码的核销，每次都需要先调用本接口，优先查询订单的券列表，选择要验的券，再调用验券接口，核销券码，验券准备和验券接口的调用次数需要一一对应，如已经调用验券接口验券成功，则当前二维码会失效，无法继续使用验券准备接口，需要使用刷新的二维码再进行调用。
  1. 二维码扫出来是一个短链，示例：https://v.douyin.com/eHHc1ft/ ，扫码后并调用本接口可返回当前订单下可用的全部券码信息，如未返回券码信息，则说明该订单此刻无可用券码。
  2. 对短链做 HTTP 请求。得到对应的长链接是https://www.iesdouyin.com/share/commerce/coupon/I0ZwZEZpb2U1N0pjQVZxS2NJRTFSQW5WK1c4bmxvbnNWdUQ2Wk85Y1N0eHpRUFpMMmZwNTdFM2NKeWlFNDM2QT0/?schema_type=13&object_id=I0ZwZEZpb2U1N0pjQVZxS2NJRTFSQW5WK1c4bmxvbnNWdUQ2Wk85Y1N0eHpRUFpMMmZwNTdFM2NKeWlFNDM2QT0&utm_campaign=client_scan_share&app=aweme&utm_medium=ios&tt_from=scan_share&iid=&utm_source=scan_share。
  3. 链接中object_id参数的值即为本接口传入的 encrypted_data 参数 I0ZwZEZpb2U1N0pjQVZxS2NJRTFSQW5WK1c4bmxvbnNWdUQ2Wk85Y1N0eHpRUFpMMmZwNTdFM2NKeWlFNDM2QT0

请仅感知链接中的 object_id 参数。其他的参数、域名、路径等信息请不要感知。以后都有优化和调整的可能。

  1. 定期清理过期券，在清理前可以获取到已经过期的券，用此券核销会报错。
  2. 该接口只返回未使用状态的券信息。

基本信息

名称描述
HTTP URL
https://open.douyin.com/goodlife/v1/fulfilment/certificate/prepare/
HTTP Method
GET
Scope
life.capacity.fulfilment
权限要求
  • 需要申请权限 ，路径：抖音开放平台 > 开发者平台/服务商平台 > 控制台 > 应用详情 > 解决方案
  • 需要商家授权，路径：抖音来客 > 店铺管理 > 第三方应用授权

请求头

名称字段类型是否必填示例描述
access-tokenString是clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
调用https://open.douyin.com/oauth/client_token/生成的token
content-typeString是application/json
固定值"application/json"

请求参数

Query

名称字段类型是否必填示例描述
codeString否
券码明文
encrypted_dataString否

从二维码解析出来的标识

(传参前需要先进行URL编码，注意不要有空格)

poi_idString否

操作核销的抖音门店id

请求示例

https://open.douyin.com/goodlife/v1/fulfilment/certificate/prepare/?code=100000000000

响应参数

Body

名称字段类型是否必填示例描述

响应示例

正常响应示例

{
  "data": {
    "error_code": 0,
    "description": "",
    "verify_token": "bTzezmw1QN",
    "certificates": [
      {
        "verify": {
          "can_cancel": false,
          "verify_type": 1,
          "verifier_unique_id": "iyC4GN4rn9",
          "poi_id": 4130990035032469500,
          "times_card_serial_num": 1119096798949989000,
          "verify_id": "ZjW8GDgQWr",
          "certificate_id": "4QL7g9fAvK",
          "verify_time": 8372667043961122000
        },
        "used_status_type": 1,
        "certificate_id": 1547825311463442400,
        "time_card": {
          "times_count": 3085447330034450000,
          "times_used": 768365467306361500,
          "serial_amount_list": [
            {
              "serial_numb": 2134401145067428000,
              "amount": {
                "original_amount": 3472870525749536300,
                "pay_amount": 3433122571129206300,
                "merchant_ticket_amount": 3239920090813340000,
                "payment_discount_amount": 6421282484707015000,
                "coupon_pay_amount": 4608952047904284000,
                "list_market_amount": 4694672733357339000,
                "platform_discount_amount": 4680950096575991000
              }
            }
          ]
        },
        "encrypted_code": "2XGsY8kKE1",
        "amount": {
          "pay_amount": 4958711503816374000,
          "merchant_ticket_amount": 6235018165510614000,
          "payment_discount_amount": 2003142443214968,
          "coupon_pay_amount": 3762057733607267000,
          "list_market_amount": 907590751855790200,
          "platform_discount_amount": 1552570542369865000,
          "original_amount": 4895189045803098000
        },
        "not_available_time_info": {
          "can_no_use_date": [
            {
              "start_time": 4084975267353391000,
              "end_time": 2626900529420987400
            }
          ],
          "fulfil_enable": false,
          "can_no_use_week_day": [
            7577028759473086000
          ]
        },
        "code": "RAS1n0USMw",
        "start_time": 7986378922400461000,
        "expire_time": 2881768982850912000,
        "verify_records": [
          {
            "verify_id": "7Nc7QWwzEO",
            "certificate_id": "paOqVH0Ww1",
            "verify_time": 6019846477591310000,
            "can_cancel": false,
            "verify_type": 1,
            "verifier_unique_id": "XsyJFItZx6",
            "poi_id": 2877496934691995600,
            "times_card_serial_num": 7414136160209935000
          }
        ],
        "status": 1,
        "sku": {
          "account_id": "cedmYtURHK",
          "sku_id": "QETojxjbxv",
          "title": "ReujtCjHnD",
          "groupon_type": 1,
          "market_price": 1303641918177988600,
          "sold_start_time": 8430300544865816000,
          "third_sku_id": "4v3gtF1cnP"
        }
      }
    ],
    "order_id": "jh8O40k9M9"
  },
  "extra": {
    "description": "R6CQUBbmRw",
    "sub_error_code": 948527794874605200,
    "sub_description": "dofhrIF18Y",
    "logid": "202008121419360101980821035705926A",
    "now": 4863184500671430000,
    "error_code": 1162922644428233200
  }
}

异常响应示例

{
  "data": {
    "error_code": 2190008,
    "description": "access_token过期,请刷新或重新授权"
  },
  "extra": {
    "error_code": 2190008,
    "description": "access_token过期,请刷新或重新授权",
    "sub_error_code": 0,
    "sub_description": "access_token过期,请刷新或重新授权",
    "logid": "202406131959494F28C28C0002DD440D4B",
    "now": 1718279990081
  }
}

错误码

http状态码错误码错误码描述排查建议
2002190002
access_token无效
调用接口重新生成access_token
2002190004
应用未获得该能力, 请去https://open.douyin.com/申请
应用申请接口权限
2002190008
access_token过期,请刷新或重新授权
规范token刷新机制，检查是否有测试环境在同步刷新token
2002119001
参数不合法
更换参数
2002119002
系统繁忙，请稍候再试
重试
2002119003
请求太过频繁，请稍后再试
重试
2002119005
应用未获商家授权
联系合作商家在商家后台发起授权，并在服务商后台同意授权
2003000001
根据实际业务错误返回
对照接口文档规范参数并重试
2004000001
根据实际业务错误返回
补充参数
2004000002
根据实际业务错误返回
对照接口文档规范参数并重试
2005000001
根据实际业务错误返回
联系抖音处理
2003000002
核销门店错误
检查核销门店重试