1. Open
dy-gateway
  • Health
    • 健康检查
      GET
  • Open
    • 统一券核销入口
      POST
    • 验券准备
      POST
    • 获取当前抖音 access_token
      GET
    • 查询门店信息
      GET
  • Internal
    • 查询核销流水
      GET
    • 查询核销汇总报表
      GET
    • 创建核销端应用
      POST
    • 查询核销端应用列表
      GET
    • 修改应用 token 读取权限
      PATCH
  • 数据模型
    • HealthResponse
    • ErrorResponse
    • MessageResponse
    • AppStatus
    • VerificationStatus
    • EnrichmentStatus
    • OrderStatus
    • PrepareCouponRequest
    • VerifyCouponRequest
    • VerificationView
    • VerificationResponse
    • AccessToken
    • AccessTokenResponse
    • VerifierApp
    • CreateAppResponseData
    • CreateAppRequest
    • CreateAppResponse
    • AppListResponse
    • UpdateTokenAccessRequest
    • VerificationListResponse
    • VerificationSummaryRow
    • VerificationSummaryResponse
  1. Open

统一券核销入口

POST
/v1/open/coupons/verify
同步执行抖音验券流程,并返回本次核销的主结果。
当前支持三种入参模式:
short_link 模式:服务端会先解析短链并执行 certificate.prepare,再继续验券
code 模式:服务端会用明文券码执行 certificate.prepare,再继续验券
encrypted_code 模式:调用方先调 prepare 拿到必要参数后,可直接跳过内部 prepare 发起验券
根据抖音官方说明,抖音团购券的 certificate.prepare 与 certificate.verify 调用次数应一一对应。
在本网关内,short_link / code 模式会由服务端先补一次 prepare,再继续 verify;
encrypted_code 模式则表示调用方已经在网关外先完成了对应的 prepare,本接口不会重复发起 prepare。
也就是说,一次实际核销对应的一次 prepare 可以发生在网关内,也可以发生在调用方上游,但不能跳过 prepare 直接把明文券码送去 verify。
若某次验券已经成功,当前二维码会失效,后续需要刷新二维码后再重新 prepare。
如果抖音返回了 order_id,系统会异步投递补全任务,用于后续查询订单详情和刷新验券后的券状态。
补全任务不会改变 verify_status,只会影响 enrichment_status 以及本地报表字段完整度。
响应中的 douyin_response 字段会附带本次验券的抖音官方原始响应对象,便于调用方兼容旧解析逻辑。

请求参数

Authorization
API Key
在 header 添加参数
X-Client-Key
示例:
X-Client-Key: ********************
API Key
在 header 添加参数
X-Timestamp
示例:
X-Timestamp: ********************
API Key
在 header 添加参数
X-Nonce
示例:
X-Nonce: ********************
API Key
在 header 添加参数
X-Signature
示例:
X-Signature: ********************
or
Body 参数application/json必填

示例
{
    "poi_id": "7182937465123456789",
    "short_link": "https://v.douyin.com/i5Qw3X7Y/",
    "verify_token": "verify-token-20260311-001",
    "extra": {
        "operator_id": "cashier-008",
        "device_id": "ipad-pos-01",
        "note": "前台扫码核销"
    }
}

请求示例代码

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
请求示例请求示例
Shell
JavaScript
Java
Swift
cURL
curl --location --request POST '/v1/open/coupons/verify' \
--header 'X-Client-Key: <api-key>' \
--header 'X-Timestamp: <api-key>' \
--header 'X-Nonce: <api-key>' \
--header 'X-Signature: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "poi_id": "7182937465123456789",
    "short_link": "https://v.douyin.com/i5Qw3X7Y/",
    "verify_token": "verify-token-20260311-001",
    "extra": {
        "operator_id": "cashier-008",
        "device_id": "ipad-pos-01",
        "note": "前台扫码核销"
    }
}'

返回响应

🟢200成功
application/json
核销请求已处理完成
Body

示例
{
    "data": {
        "id": 1024,
        "app_id": 3,
        "app_name": "华东校区核销小程序",
        "poi_id": "7182937465123456789",
        "verify_status": "success",
        "error_code": 0,
        "error_description": "",
        "certificate_id": "certificate-123",
        "encrypted_code": "ENCODED_COUPON_CODE",
        "origin_code": "ORIGIN_COUPON_CODE",
        "coupon_status": "USED",
        "product_id": "product-8899",
        "product_name": "少儿编程体验课",
        "sku_id": "sku-001",
        "sku_name": "周末班",
        "verify_records_count": 1,
        "verify_id": "verify-987654",
        "order_id": "order-556677",
        "source_order_id": "source-order-556677",
        "ext_order_id": "merchant-order-20260311001",
        "order_status": 201,
        "pay_amount": 19900,
        "receipt_amount": 15900,
        "discount_amount": 4000,
        "enrichment_status": "pending",
        "enrichment_retry_count": 0,
        "douyin_response": {
            "err_no": 0,
            "err_tips": "success",
            "data": {
                "verify_results": [
                    {
                        "verify_id": "verify-987654",
                        "order_id": "order-556677",
                        "certificate_id": "certificate-123",
                        "result": 0
                    }
                ]
            }
        },
        "verify_time": "2026-03-11T10:35:12Z",
        "create_order_time": "2026-03-11T10:20:00Z",
        "pay_time": "2026-03-11T10:21:05Z",
        "created_at": "2026-03-11T10:35:12Z",
        "updated_at": "2026-03-11T10:35:12Z"
    }
}
🟠400请求有误
🟠401未认证
🔴502网关错误
修改于 2026-03-16 02:28:54
上一页
健康检查
下一页
验券准备
Built with