49热聊 49Hot49热聊49Hot
浏览文档目录

联享券

联享券 API

独立应用 Token 的接口、权限与调用约束。

鉴权

运行时接口使用 sop_ Token。不要把账号 JWT 或 Bot Token 传给这些接口。

API=https://api.example.com
Authorization: Bearer sop_xxxxxxxxxxxxxxxxx
Content-Type: application/json
sop_ Token 绑定单个开放应用。接口不会接受 application_id、bot_id 等字段切换资源归属；Token 被吊销、过期或所属应用停用后立即不可用。应用策略还会校验 Origin：* 不限制，精确域名不含子域，*.example.com 只允许其子域；限制后缺少 Origin 的请求返回 403。

生产服务端可使用安全传输，把逻辑路径、sop_ Token、幂等键、请求体和响应体整体加密。查看请求加解密教程。

权限

vouchers:read读取模板和核销结果
vouchers:templates:write创建并提交模板
vouchers:issue发放联享券
vouchers:verify验证券状态
vouchers:redeem核销联享券
vouchers:reverse冲正核销

统一响应

HTTP 状态码表示传输和业务结果；响应体同时包含 success、code、message、data，meta.requestId 可用于排查。错误响应的 success 为 false，详情位于 error。

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {},
  "meta": {
    "requestId": "REQUEST_ID",
    "timestamp": "2026-09-08T10:30:00.000Z",
    "duration": "12ms"
  }
}

运行时接口

GET/api/v1/open-platform/me

读取 Token 所属应用，用于启动自检。

权限
vouchers:read
默认限流
60 次/分钟
幂等键
否
GET/api/v1/open-platform/vouchers/templates

查询当前应用的全部模板。

权限
vouchers:read
默认限流
60 次/分钟
幂等键
否
POST/api/v1/open-platform/vouchers/templates

创建 draft 模板。

权限
vouchers:templates:write
默认限流
20 次/分钟
幂等键
否
POST/api/v1/open-platform/vouchers/templates/:templateId/submit

提交 draft 或 rejected 模板审核。

权限
vouchers:templates:write
默认限流
10 次/分钟
幂等键
否
POST/api/v1/open-platform/vouchers/issue

向指定用户发放 active 模板的券。

权限
vouchers:issue
默认限流
30 次/分钟
幂等键
是
POST/api/v1/open-platform/vouchers/verify

按二维码或六位券码读取当前状态。

权限
vouchers:verify
默认限流
30 次/分钟
幂等键
否
POST/api/v1/open-platform/vouchers/redeem

原子核销一张当前可用的券。

权限
vouchers:redeem
默认限流
20 次/分钟
幂等键
是
GET/api/v1/open-platform/vouchers/redemptions/:redemptionId

查询当前应用内的核销或冲正记录。

权限
vouchers:read
默认限流
60 次/分钟
幂等键
否
POST/api/v1/open-platform/vouchers/redemptions/:redemptionId/reverse

冲正一次成功核销。

权限
vouchers:reverse
默认限流
10 次/分钟
幂等键
是

模板接口

模板编号在同一应用内唯一。创建后只能提交 draft 或 rejected 模板；审核通过的 active 模板才能发券。

字段必填说明
external_template_id是你的模板编号；同一应用内唯一。
name是面向用户展示的券名称。
type是discount | cash_discount | gift | service
issuer_name是发行方名称。
fulfiller_name是实际履约方名称。
fulfillment_category是physical_goods | offline_service | ecommerce_discount | app_credit
acquisition_source是free | merchant_campaign | platform_campaign
validity是fixed 使用 from/to；relative 使用 days_after_claim（1–3650）。
issue_limit是模板总发行上限；设为 0 时不限制累计发放量。
per_user_limit否单用户限领 1–100，默认 1。
description / cover_file_id否展示说明和当前应用所有者已上传到平台的图片文件 ID；可先在控制台上传并裁剪，不接受外部图片地址。
usage_rules / fulfillment / terms否结构化使用规则、履约信息和条款快照；fulfillment 可包含 HTTPS redemption_url 和 in_app / external 打开方式。

模板状态

draft草稿，可提交审核reviewing审核中active可发放rejected已驳回，可修改后重提paused / ended / archived不可继续发放

发放参数

字段必填说明
Idempotency-Key是请求头；标识一次发券动作。
template_id是当前应用下 active 模板的 ID。
external_issue_id是你的唯一业务发放编号。
recipient_user_id是已授权或已有业务关系的用户 ID。

成功响应返回 issuanceId 和 voucher。应用级接口不会返回券码或二维码明文；凭据由持券用户侧安全展示。

券凭据

{
  "credential": {
    "type": "qr_token",
    "value": "SCANNED_VALUE"
  }
}

type 支持 qr_token 与 redeem_code。六位券码忽略大小写、空格和连字符。验券会在发现已过期的 available 券时更新其状态，但不会核销。

核销参数

字段必填说明
Idempotency-Key是请求头；标识一次核销动作。
credential是qr_token 或 redeem_code 凭据对象。
external_order_id是你的订单或交易编号。
store_id否发生核销的门店编号。
operator_id否操作员编号。
occurred_at否ISO 8601 业务发生时间；默认服务器当前时间。
核销以 available、已生效且未过期为条件执行原子更新。并发请求只有一个能成功；其余返回 409。验券结果不能替代核销结果。

冲正

冲正必须引用一次成功且尚未冲正的核销记录，并使用新的 Idempotency-Key。成功后券在仍未过期时恢复为 available，否则变为 expired。

{
  "reason": "订单退款",
  "operator_id": "manager_02"
}

幂等与重试

  • 发券、核销、冲正分别使用不同的 Idempotency-Key。
  • 同一业务动作重试时必须复用原键和完全相同的请求体。
  • 客户端超时不代表服务端失败；先重试原请求或查询核销记录，不要换键重复执行。
  • 409 可能表示额度用完、达到单用户限领、券已核销、当前不可核销或幂等冲突，应读取 message/error 后分类处理。

控制台管理接口

这些接口使用登录账号 JWT，只允许访问当前账号拥有的开放应用。

GET    /api/v1/open-platform/applications
POST   /api/v1/open-platform/applications
GET    /api/v1/open-platform/applications/:id
PATCH  /api/v1/open-platform/applications/:id
GET    /api/v1/open-platform/applications/:id/tokens
POST   /api/v1/open-platform/applications/:id/tokens
DELETE /api/v1/open-platform/applications/:id/tokens/:tokenId
PUT    /api/v1/open-platform/applications/:id/bots/:botId
DELETE /api/v1/open-platform/applications/:id/bots/:botId

配到待发送背包

应用所有者使用登录账号 JWT 搜索派券人并分配库存。此操作不生成可使用的券或核销凭据；派券人发送、接收人领取后才生成用户券。原有运行时 /issue 接口仍直接发给使用人，不等同于配券。

GET  /api/v1/open-platform/applications/:id/vouchers/recipients?keyword=sender
GET  /api/v1/open-platform/applications/:id/vouchers/allocations?templateId=TEMPLATE_ID&page=1&limit=20
POST /api/v1/open-platform/applications/:id/vouchers/allocations
{
  "templateId": "TEMPLATE_ID",
  "recipientUserId": "SENDER_USER_ID",
  "quantity": 5,
  "idempotencyKey": "UNIQUE_ALLOCATION_REQUEST_ID"
}

搜索支持至少两字符的用户名或完整用户 ID，最多返回 20 人。配券数量为 1–10000 的整数，不可超过剩余库存；网络异常重试须沿用同一幂等编号和请求参数。返回的配券记录包含 id、quantity、remaining、sendingCount、claimedCount 与 status。

常见状态码

  • 400 请求字段缺失、格式错误或参数超出允许范围。
  • 401 Token 无效、已过期或已吊销。
  • 403 应用停用、功能关闭或 Token 缺少权限。
  • 404 模板、券或核销记录不属于当前应用。
  • 409 状态冲突、额度不足或幂等键被不同请求复用。
  • 429 请求超过接口限流。
  • 5xx 平台暂时异常。保留 requestId，并仅使用原幂等键和原请求体重试。

常见业务错误

VOUCHER_ALREADY_REDEEMED券已经核销，不得再次消费。
VOUCHER_NOT_REDEEMABLE券尚未生效、已过期、已撤销或状态不允许核销。