UVS (Universal Voucher System) 开放 API (1.0.0)

Download OpenAPI specification:

UVS 开放平台接入规范与 API 手册。

这份规格覆盖什么

只有核销（以及它的前置卡券查询）。制券、批次管理、对账文件下载都在 UVS Portal 上完成，不经开放 API。

鉴权

HMAC-SHA256 签名。每个请求须带 x-uvs-access-key、x-uvs-timestamp、x-uvs-nonce、x-uvs-signature 四个头；签名覆盖 method + path + timestamp + nonce + body 的 SHA-256。时间戳窗口 ±5 分钟。

凭据标识一个 Tenant。没有角色——能操作什么完全由资源归属决定：属于你的就能操作，不属于的一律按不存在处理（返回 404 而不是 403，避免返回码本身成为存在性探针）。

幂等

所有写操作 (POST) 的 body **必填 request_id**。同一个 request_id 重试会安全重放首次响应，不会重复扣减、不会重复记账。换了 body 再用同一个 request_id 会被拒 (IDEMPOTENCY_KEY_REUSED)，这是调用方的 bug，不是可以忽略的告警。

错误

统一信封：4xx 是调用方问题，5xx 是服务方问题。每个响应都带 x-uvs-request-id，与错误信封里的一致——报障时给这个值即可定位。

锁定卡券核销额度 (lock)

锁定待核销的券，校验离线签名与授权链，计算并返回权威抵扣金额

Authorizations:

HMAC_SHA256

header Parameters

idempotency-key

string

Example: req_lock_20260726_001

【可选】HTTP 标准写操作幂等 Key。推荐与 Body 中的 request_id 保持一致。超时重试时，带相同 Key 将直接重放首次调用的响应

Request Body schema: application/json

request_id required	string 【必填】业务操作幂等请求 ID（如 req_20260726_001）。重复发送相同 request_id 会安全重放首次调用响应，不会重复扣款或发动作放
coupon required	string 核销码 (code)
merchant required	string 商户外部 ID (mch_…)，须属于调用方且在券的适用范围内
store	string 门店标识，调用方自定义的自由字符串。UVS 不做任何校验：不查找、不校验归属、不检查引用完整性，传错不会报错。值只做归一化后原样记录（`,` 与空白字符 → `_`，去首尾，截断 64 字符），用作对账文件里的一列与聚合键。归一化有损：`A,B` 与 `A B` 会归一成同一个值，故门店维度统计的准确性由调用方负责——请传不含逗号与空格的稳定编码
terminal	string POS 终端标识，调用方自定义的自由字符串。UVS 不做任何校验：不查找、不校验归属、不检查引用完整性，传错不会报错。值只做归一化后原样记录（`,` 与空白字符 → `_`，去首尾，截断 64 字符），用作对账文件里的一列与聚合键。归一化有损：`A,B` 与 `A B` 会归一成同一个值，故门店维度统计的准确性由调用方负责——请传不含逗号与空格的稳定编码
order_amount	number 订单总金额（分或元，百分比规则强制要求）
currency	string 货币代码 (ISO 4217)
order_id	string 外部 POS 订单号
	object 交易上下文（含 SKU 明细）

Responses

Request samples

Payload

Content type

application/json

{"request_id": "req_lock_001",
"coupon": "164TGDA8HAQ6XS1K",
"merchant": "mch_abc123",
"store": "STORE_01",
"terminal": "POS_07",
"order_amount": 100,
"currency": "CNY",
"order_id": "ORD_20260726_999",
"redemption_context": {"items": [{"sku": "SKU-A",
"quantity": 1,
"amount": 100
}
]
}
}

Response samples

Content type

application/json

{"ok": true,
"redemption": "red_lock_998877",
"discount_amount": 15.5
}

一阶段直接核销 (redeem)

锁定+确认一次成型，适用于无需预扣校验的即时核销场景

Authorizations:

HMAC_SHA256

header Parameters

idempotency-key

string

Example: req_lock_20260726_001

【可选】HTTP 标准写操作幂等 Key。推荐与 Body 中的 request_id 保持一致。超时重试时，带相同 Key 将直接重放首次调用的响应

Request Body schema: application/json

request_id required	string 【必填】业务操作幂等请求 ID（如 req_20260726_001）。重复发送相同 request_id 会安全重放首次调用响应，不会重复扣款或发动作放
coupon required	string 核销码 (code)
merchant required	string 商户外部 ID (mch_…)，须属于调用方且在券的适用范围内
store	string 门店标识，调用方自定义的自由字符串。UVS 不做任何校验：不查找、不校验归属、不检查引用完整性，传错不会报错。值只做归一化后原样记录（`,` 与空白字符 → `_`，去首尾，截断 64 字符），用作对账文件里的一列与聚合键。归一化有损：`A,B` 与 `A B` 会归一成同一个值，故门店维度统计的准确性由调用方负责——请传不含逗号与空格的稳定编码
terminal	string POS 终端标识，调用方自定义的自由字符串。UVS 不做任何校验：不查找、不校验归属、不检查引用完整性，传错不会报错。值只做归一化后原样记录（`,` 与空白字符 → `_`，去首尾，截断 64 字符），用作对账文件里的一列与聚合键。归一化有损：`A,B` 与 `A B` 会归一成同一个值，故门店维度统计的准确性由调用方负责——请传不含逗号与空格的稳定编码
order_amount	number 订单总金额（分或元，百分比规则强制要求）
currency	string 货币代码 (ISO 4217)
order_id	string 外部 POS 订单号
	object 交易上下文（含 SKU 明细）

Responses

Request samples

Payload

Content type

application/json

{"request_id": "req_lock_001",
"coupon": "164TGDA8HAQ6XS1K",
"merchant": "mch_abc123",
"store": "STORE_01",
"terminal": "POS_07",
"order_amount": 100,
"currency": "CNY",
"order_id": "ORD_20260726_999",
"redemption_context": {"items": [{"sku": "SKU-A",
"quantity": 1,
"amount": 100
}
]
}
}

Response samples

Content type

application/json

{"ok": true,
"redemption": "red_lock_998877",
"discount_amount": 15.5
}

确认锁定核销 (confirm)

持锁方根据 lock_request_id 最终确认核销扣减

Authorizations:

HMAC_SHA256

header Parameters

idempotency-key

string

Example: req_lock_20260726_001

【可选】HTTP 标准写操作幂等 Key。推荐与 Body 中的 request_id 保持一致。超时重试时，带相同 Key 将直接重放首次调用的响应

Request Body schema: application/json

request_id required	string 【必填】业务操作幂等请求 ID。重复发送相同 request_id 会安全重放首次调用响应，不会重复扣款或发动作放
lock_request_id required	string 上一阶段锁定时的 lock_request_id（防越权抢占）
coupon required	string 核销码 (code)
merchant required	string 商户外部 ID (mch_…)，须属于调用方且在券的适用范围内

Responses

Request samples

Payload

Content type

application/json

{"request_id": "req_confirm_001",
"lock_request_id": "req_lock_001",
"coupon": "164TGDA8HAQ6XS1K",
"merchant": "mch_abc123"
}

Response samples

200
400
401
404
409

Content type

application/json

{"ok": true,
"redemption": "red_lock_998877",
"status": "REDEEMED"
}

释放已锁定卡券 (cancel)

按 (coupon, lock_request_id) 释放预扣锁定

Authorizations:

HMAC_SHA256

header Parameters

idempotency-key

string

Example: req_lock_20260726_001

【可选】HTTP 标准写操作幂等 Key。推荐与 Body 中的 request_id 保持一致。超时重试时，带相同 Key 将直接重放首次调用的响应

Request Body schema: application/json

request_id required	string 【必填】业务操作幂等请求 ID。重复发送相同 request_id 会安全重放首次调用响应，不会重复扣款或发动作放
lock_request_id required	string 需要释放的锁定 lock_request_id
coupon required	string 核销码 (code)

Responses

Request samples

Payload

Content type

application/json

{"request_id": "req_cancel_001",
"lock_request_id": "req_lock_001",
"coupon": "164TGDA8HAQ6XS1K"
}

Response samples

200
400
401
404
409

Content type

application/json

{"ok": true,
"redemption": "red_lock_998877",
"status": "REDEEMED"
}

冲正已核销交易 (reverse)

对已完成的核销记录进行全额冲正并写流水账本

Authorizations:

HMAC_SHA256

header Parameters

idempotency-key

string

Example: req_lock_20260726_001

【可选】HTTP 标准写操作幂等 Key。推荐与 Body 中的 request_id 保持一致。超时重试时，带相同 Key 将直接重放首次调用的响应

Request Body schema: application/json

request_id required	string 【必填】业务操作幂等请求 ID。重复发送相同 request_id 会安全重放首次调用响应，不会重复扣款或发动作放
redemption required	string 待冲正的核销记录外部 ID (red_…)
reason	string 冲正/退款原因说明

Responses

Request samples

Payload

Content type

application/json

{"request_id": "req_reverse_001",
"redemption": "red_lock_998877",
"reason": "顾客退货撤销交易"
}

Response samples

200
400
401
404
409

Content type

application/json

{"ok": true,
"redemption": "red_lock_998877",
"reversal": "rvs_00112233",
"status": "REVERSED"
}

紧急作废卡券 (void)

作废尚未使用的券（仅 ISSUED；已锁定 / 已核销 / 已冲正 / 已过期 / 已作废一律拒绝）

Authorizations:

HMAC_SHA256

header Parameters

idempotency-key

string

Example: req_lock_20260726_001

【可选】HTTP 标准写操作幂等 Key。推荐与 Body 中的 request_id 保持一致。超时重试时，带相同 Key 将直接重放首次调用的响应

Request Body schema: application/json

request_id required	string 【必填】业务操作幂等请求 ID。重复发送相同 request_id 会安全重放首次调用响应，不会重复扣款或发动作放
coupon required	string 待作废的核销码 (code)
merchant required	string 商户外部 ID (mch_…)，须属于调用方且在券的适用范围内
reason	string 作废原因说明

Responses

Request samples

Payload

Content type

application/json

{"request_id": "req_void_001",
"coupon": "164TGDA8HAQ6XS1K",
"merchant": "mch_abc123",
"reason": "活动作废退款"
}

Response samples

200
400
401
404
409

Content type

application/json

{"ok": true,
"coupon_id": "cpn_998877665544",
"status": "VOIDED"
}

卡券信息与状态查询

根据卡券核销码 (code) 查询卡券状态 (ISSUED / LOCKED / REDEEMED / EXPIRED / VOIDED) 及模板信息。需通过与核销相同的授权链：券与 merchant 都须属于调用方，且该 merchant 在券的适用范围内。响应隐去 code，返回卡券外部标识 cpn_…

Authorizations:

HMAC_SHA256

Request Body schema: application/json

coupon required	string 16 位 Crockford Base32 卡券核销码 (code)
merchant required	string 发起查询的商户外部 ID (mch_…)，须属于调用方且在券的适用范围内

Responses

Request samples

Payload

Content type

application/json

{"coupon": "164TGDA8HAQ6XS1K",
"merchant": "mch_7QJ4X2VN8KDA1M5PZR3T"
}

Response samples

200
400
401
404

Content type

application/json

{"ok": true,
"coupon": {"coupon_id": "cpn_998877665544",
"status": "ISSUED",
"batch_id": "bat_xyz789",
"created_at": "2026-07-26T10:00:00.000Z",
"valid_from": "2026-07-26T10:00:00.000Z",
"valid_to": "2026-08-26T10:00:00.000Z",
"redemption": {"merchant_id": "mch_7QJ4X2VN8KDA1M5PZR3T",
"status": "REDEEMED",
"started_at": "2026-07-26T10:00:00.000Z",
"discount_amount": 1200,
"currency": "SGD"
}
}
}