抖音开放平台Logo
控制台

券状态查询

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

接口说明

在核销的异常场景情况下，对抖音码团购、次卡券进行状态查询。

使用限制

1、仅支持查询抖音团购券码的状态

2、该场景常用于核销开放过程中，如存在断网情况下，商家系统没办法及时收到核销状态，增加券状态查询接口，方便商家系统查询券码状态

3、通过验券准备接口返回的加密 code 查询抖音团购券码状态

4、该接口不支持批量查询

基本信息

名称描述
HTTP URL
https://open.douyin.com/goodlife/v1/fulfilment/certificate/get/
HTTP Method
GET
Scope
life.capacity.fulfilment
权限要求

团购核销

1.需要申请权限 路径：抖音开放平台-开发者平台/服务商平台>控制台>应用详情>解决方案

2.需要商家授权，路径：抖音来客>店铺管理>第三方应用授权

请求头

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

请求参数

Query

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

验券准备接口返回的加密券码

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

请求示例

curl --location --request GET '/goodlife/v1/fulfilment/certificate/get/?encrypted_code=3wbcqy3UIR' \
--header 'access-token: 0801121846735352506a356a6' \
--header 'content-type: application/json' \
--data ''

响应参数

Body

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

响应示例

正常响应示例

{
  "data": {
    "certificate": {
      "code": "l04y3aI334",
      "encrypted_code": "ijrq42C2YZ",
      "start_time": 3451409998017959000,
      "certificate_id": 6594947298403630000,
      "not_available_time_info": {
        "fulfil_enable": false,
        "can_no_use_week_day": [
          8334624547801304000
        ],
        "can_no_use_date": [
          {
            "end_time": 6216432909289307000,
            "start_time": 7604748094287202000
          }
        ]
      },
      "used_status_type": 1,
      "verify_records": [
        {
          "verify_type": 1,
          "verifier_unique_id": "OfeGwFgUWL",
          "poi_id": 207821252390421150,
          "times_card_serial_num": 1785627511812604000,
          "verify_id": "7qGdpPaQJY",
          "certificate_id": "l5PdxewZbC",
          "verify_time": 7563567756801700000,
          "can_cancel": false
        }
      ],
      "sku": {
        "sku_id": "nfYjOWhvrf",
        "title": "GAarzqzzwo",
        "groupon_type": 1,
        "market_price": 1995506533835392000,
        "sold_start_time": 5574594901290286000,
        "third_sku_id": "2PtTbIQ5nA",
        "account_id": "Km8QEYAupP"
      },
      "verify": {
        "can_cancel": false,
        "verify_type": 1,
        "verifier_unique_id": "fa8RYMn4b1",
        "poi_id": 8597594927780037000,
        "times_card_serial_num": 8382832612253757000,
        "verify_id": "mrkU2Xfeev",
        "certificate_id": "MjbhSuRBLj",
        "verify_time": 6697630751792713000
      },
      "time_card": {
        "serial_amount_list": [
          {
            "serial_numb": 1909885161725615000,
            "amount": {
              "original_amount": 7209665082074703000,
              "pay_amount": 837731376571866200,
              "merchant_ticket_amount": 7125324145913672000,
              "payment_discount_amount": 1202769628049179000,
              "coupon_pay_amount": 4793690383822236000,
              "list_market_amount": 8466960651601694000,
              "platform_discount_amount": 6596774182645987000
            }
          }
        ],
        "times_count": 8295958836095649000,
        "times_used": 7810759063584207000
      },
      "status": 1,
      "expire_time": 9157739619557615000,
      "amount": {
        "payment_discount_amount": 1244167186508970800,
        "coupon_pay_amount": 6911056851093502000,
        "list_market_amount": 1384341115275304200,
        "platform_discount_amount": 2056710047674977000,
        "original_amount": 9087977021581028000,
        "pay_amount": 8300371704817755000,
        "merchant_ticket_amount": 1240845961757775600
      }
    },
    "error_code": 0,
    "description": ""
  },
  "extra": {
    "sub_description": "SamI0LF3Dz",
    "logid": "202008121419360101980821035705926A",
    "now": 5160924589350531000,
    "error_code": 2729486079485261000,
    "description": "SlWwETlmsB",
    "sub_error_code": 7095173481615762000
  }
}

异常响应示例

{
  "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
根据实际业务错误返回
联系抖音处理