联享券

联享券使用指南

跟着步骤创建券、配到指定用户背包，再由对方发送给别人使用。

配置人

在开放平台填写券内容、提交审核，再选择派券人和数量。

派券人

在“待发送”背包中查看剩余数量，选择聊天对象发送。不能自己使用。

使用人

在聊天中领取券，然后在“可使用”中查看券码或使用链接。不能再次转送。

完整业务流程

创建券：打开一个开放应用，进入联享券，点击“创建联享券”，按提示填写券内容、数量和有效期。
等待审核：确认内容后提交审核。券详情会提示当前进度，审核通过后出现配券入口。
配到背包：搜索派券人的用户名，选择用户，填写张数，确认放入对方的“待发送”背包。
发送给别人：派券人在客户端打开“我的权益 → 待发送”，选择聊天对象后发送；也可以在聊天工具栏发券。
领取并使用：接收人在聊天卡片中领取，券进入“可使用”。按券上的规则出示券码或打开使用链接。

例如：给 A 配 5 张券，A 的背包显示“待发送 5 张”，A 不能自用。A 发给 B 后，B 领取并使用，不能再次转送。

5 张券发给 6 人会整批拦截，提示还差 1 张；同一个请求重试不会重复扣券。未领取的券超时后退回派券人的待发送库存。

打开控制台，开始创建

开发者 API 接入与核销（按需展开）

下面的旧版 /issue 接口直接给最终接收人生成可使用券；它不是“配券到待发送背包”。日常配券请使用控制台的分步入口，已有 API 集成继续保持原行为。

接入准备

登录开放平台控制台，创建一个开放应用。
在“应用策略”中配置域名白名单。* 表示不限制；example.com 只匹配该域名；*.example.com 匹配其所有子域名但不匹配根域名。限制后服务端请求必须发送匹配的 Origin。
在应用内创建券模板并提交审核。只有审核通过的模板可正式发放。
生成 sop_ Token，并按服务职责选择最小权限。完整 Token 只展示一次。

先选对凭证

凭证	用途	资源边界
`JWT`	控制台管理应用、Token 和机器人关联	当前登录账号拥有的应用
`sop_`	模板、发券、验券、核销和冲正	Token 所属的单个开放应用
`sbot_`	可选的机器人会话发券	机器人关联的开放应用和可访问会话

创建并提交券模板

模板定义权益、履约方、有效期和发行上限。创建后得到 draft 模板，提交审核并变为 active 后才能发放。

curl -X POST "$API/api/v1/open-platform/vouchers/templates" \
  -H "Authorization: Bearer $OPEN_PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_template_id": "app_points_100_2026",
    "name": "100 积分券",
    "type": "gift",
    "description": "核销后向外部应用账号增加 100 积分",
    "issuer_name": "联享券测试系统",
    "fulfiller_name": "联享券测试系统",
    "fulfillment_category": "app_credit",
    "acquisition_source": "merchant_campaign",
    "validity": { "mode": "relative", "days_after_claim": 30 },
    "issue_limit": 0,
    "per_user_limit": 1,
    "usage_rules": { "instructions": "登录联享券测试系统后确认兑换" },
    "fulfillment": {
      "points": 100,
      "unit": "points",
      "redemption_url": "https://www.example.com/linkedcoupons/login",
      "open_mode": "in_app"
    }
  }'

curl -X POST "$API/api/v1/open-platform/vouchers/templates/$TEMPLATE_ID/submit" \
  -H "Authorization: Bearer $OPEN_PLATFORM_TOKEN"

type 支持 discount、cash_discount、gift、service。
券背景只接受平台文件 ID，不接受外部图片地址。控制台可上传并按 16:9 裁剪；背景会随发券记录保存为快照。
fulfillment_category 当前支持 physical_goods、offline_service、ecommerce_discount、app_credit；应用积分使用 app_credit，并在 fulfillment 中保存积分数值与单位。
fulfillment.redemption_url 可配置 HTTPS 核销入口；URL 含 {code} 时客户端原位替换，否则把一次性券码写入 URL Fragment 的 voucher_code 参数。open_mode 使用 in_app 或 external 选择应用内页面或系统浏览器。
acquisition_source 支持 free、merchant_campaign、platform_campaign。
有效期可使用 fixed 的起止时间，或 relative 的领取后 1 至 3650 天。
issue_limit 为非负整数，设为 0 时不限制累计发放量；per_user_limit 为 1 至 100。external_template_id 在同一应用内唯一。

关联两个系统的用户

联享券不会合并两套账号体系。你的服务只保存“外部应用用户 ID ↔ 已授权 IM 用户 ID”的映射，积分余额仍由你的应用维护。

由用户在你的应用中主动发起绑定，并跳转或引导到 IM 完成授权；回调成功后保存双方不可变用户 ID。
如果通过已关联机器人发券，可从机器人已获准访问的私聊会话确定接收人；机器人接口首期只支持私聊。
发券时把映射得到的 IM 用户 ID 放入 recipient_user_id；核销成功后再按 fulfillment.points 给外部应用账号增加积分。

不要用手机号、邮箱或昵称猜测 IM 身份，也不要通过接口枚举用户。用户解除绑定后停止新发券，并按你的隐私政策处理映射记录。

发放给指定用户

服务端使用 vouchers:issue 权限发券。recipient_user_id 必须来自用户授权或已有业务关系，不能通过接口枚举用户。

curl -X POST "$API/api/v1/open-platform/vouchers/issue" \
  -H "Authorization: Bearer $OPEN_PLATFORM_TOKEN" \
  -H "Idempotency-Key: order_20260903_001" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "YOUR_TEMPLATE_ID",
    "external_issue_id": "benefit_20260903_001",
    "recipient_user_id": "AUTHORIZED_SOCHAT_USER_ID"
  }'

external_issue_id 标识你的业务发放记录，Idempotency-Key 标识本次 API 动作。超时或断线重试时，两者和请求体都必须保持不变；同一个键配不同请求会返回 409。

发放结果

{
  "success": true,
  "data": {
    "issuanceId": "ISSUANCE_ID",
    "voucher": {
      "id": "VOUCHER_ID",
      "templateId": "TEMPLATE_ID",
      "status": "available",
      "validFrom": "2026-09-08T00:00:00.000Z",
      "expiresAt": "2026-10-08T00:00:00.000Z",
      "version": 1
    }
  }
}

验券、核销与冲正

验券只读取状态。核销和冲正会改变券状态，只能从可信服务端调用，并分别使用独立幂等键。

curl -X POST "$API/api/v1/open-platform/vouchers/verify" \
  -H "Authorization: Bearer $VERIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "credential": { "type": "redeem_code", "value": "ABC-123" } }'

curl -X POST "$API/api/v1/open-platform/vouchers/redeem" \
  -H "Authorization: Bearer $REDEEM_TOKEN" \
  -H "Idempotency-Key: redeem_order_9001" \
  -H "Content-Type: application/json" \
  -d '{
    "credential": { "type": "redeem_code", "value": "ABC-123" },
    "external_order_id": "order_9001",
    "store_id": "store_01",
    "operator_id": "cashier_07",
    "occurred_at": "2026-09-08T10:30:00.000Z"
  }'

curl "$API/api/v1/open-platform/vouchers/redemptions/$REDEMPTION_ID" \
  -H "Authorization: Bearer $READ_TOKEN"

curl -X POST "$API/api/v1/open-platform/vouchers/redemptions/$REDEMPTION_ID/reverse" \
  -H "Authorization: Bearer $REVERSE_TOKEN" \
  -H "Idempotency-Key: reverse_order_9001" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "订单退款", "operator_id": "manager_02" }'

先验券再核销可改善收银交互，但不能把验券结果当作锁。最终以核销响应为准；并发核销只有一个请求能成功。

券状态

pending尚未到生效时间

available当前可核销

locked业务处理中，暂不可重复操作

redeemed已经核销

expired已经过期

revoked已经撤销

可选：通过机器人发送

在开放应用中关联同账号下已审核的机器人后，机器人可在私聊会话中发送本应用的券。此时使用 Bot Token 调用机器人接口。

POST /api/v1/bots/vouchers/issue
Authorization: Bearer sbot_...

{
  "chat_id": "PRIVATE_CHAT_ID",
  "template_id": "APPLICATION_TEMPLATE_ID",
  "external_issue_id": "benefit_20260903_002"
}

解除关联只会关闭机器人的发送能力，不会删除开放应用、券模板、已发放券或 sop_ Token。

安全与业务边界

sop_ Token 与 Bot Token 都只能保存在可信服务端。
仅向已授权或存在业务关系的用户发券，并保留授权与发放依据。
券码和二维码都是兑换凭证，页面展示时避免被无关第三方获取。
开发者负责权益内容、兑换规则、履约和客服。平台不售券、不代收款。

需要加密路径、Token、请求体和响应体时，按“请求加解密教程”接入安全传输。

上线前检查

将应用策略从 * 改为生产和测试服务的明确来源，并验证无 Origin、错误域名和不匹配协议均返回 403。
Token 按服务拆分权限并设置到期时间，确认完整 Token 已保存且可轮换。
保存 external_issue_id、Idempotency-Key、issuanceId、voucher.id 和 redemptionId 的业务映射。
对 401、403、404、409、429 和 5xx 分类处理；只对可恢复错误使用原请求幂等重试。
保护券码和二维码，日志中脱敏，不把 sop_ 或 sbot_ Token 写入前端、URL 或错误上报。
用测试券走完发放、验券、重复核销拦截、查询和冲正闭环。

打开控制台，开始创建请求加解密查看 API