统一券核销入口

同步执行抖音验券流程，并返回本次核销的主结果。

当前支持三种入参模式：

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: ********************

Body 参数application/json必填

示例

按扫码得到的短链核销按手输明文券码核销使用 prepare 后参数直接验券

{
    "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

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢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网关错误