供应商接入

供应商（服务方）是为权益卡用户提供线下或线上服务的机构，包括健康站、体检中心、诊所、药店等。通过 B 端核销 API，服务方可主动发起权益核销，完成服务确认与履约记录。

供应商 API 即将开放（预计 2026 Q3）。接口设计已完成，正在进行服务方注册体系建设。如有提前接入需求，请通过下方合作申请入口联系我们。

角色说明

当前权益卡的履约流程由用户端驱动（用户预约 → 到店 → 服务方核销）。供应商 API 开放后，服务方可在用户到店时主动发起核销，无需依赖用户在 App 内操作，大幅提升线下服务的流畅度。

现有流程	开放后流程
用户在 App 内预约 → 到店出示码 → 服务方扫码 → 平台核销	用户到店出示卡号或二维码 → 服务方调用核销 API → 平台扣减次数、生成履约记录

供应商类型

类型	说明	核销范围
`HEALTH_STATION`	晓葆健康站，通过 `points_code` 识别	绑定该健康站的权益项
`SERVICE_PROVIDER`	体检中心、诊所、药店等非健康站服务方	绑定该服务方 ID 的权益项
`CHANNEL_PARTNER`	渠道商（保险、银行、企业 HR）	仅查询和批量发卡，不执行核销

核销权益接口

即将开放 — 以下为接口设计规范，正式上线前可提前联系对接。

POST/open/v1/benefit-cards/verify-use

鉴权：AppKey + MD5 签名（S2S），参见鉴权说明。

请求体（application/json）：

字段	类型	必填	说明
`card_number`	string	是	用户权益卡卡号（15 位）
`user_benefit_item_id`	integer	是（二选一）	用户权益项 ID（从用户扫码或展示中获取）
`quantity`	integer	否	核销数量，默认 1
`points_code`	string	否	健康站编码（服务方为健康站时传入）
`service_provider_id`	integer	否	非健康站服务方 ID
`remark`	string	否	核销备注，最长 200 字符

请求示例：

POST /open/v1/benefit-cards/verify-use
X-App-Id: 100023
X-Timestamp: 1743494400
X-Signature: d41d8cd98f00b204e9800998ecf8427e

{
  "card_number": "XB1234567890ABC",
  "user_benefit_item_id": 191,
  "quantity": 1,
  "points_code": "BJ001",
  "remark": "到店轻体检核销"
}

成功响应（200 OK）：

{
  "success": true,
  "data": {
    "fulfillment_record_id": 1001,
    "card_number_masked": "XB12 **** **** 0ABC",
    "benefit_item_name": "轻体检服务",
    "quantity_used": 1,
    "remaining_quantity": 11,
    "user_info": {
      "name_masked": "张*",
      "phone_masked": "138****1234"
    },
    "verified_at": "2026-04-01 14:30:00"
  }
}

核销成功后，平台会自动生成 benefit_fulfillment_records 记录，并扣减用户的remaining_quantity。核销不可撤销，请在执行前做好确认提示。

核销数据结构

核销后生成的履约记录包含以下关键字段：

字段	类型	说明
`fulfillment_record_id`	integer	履约记录唯一 ID
`card_number`	string	权益卡卡号（脱敏）
`benefit_item_name`	string	权益项名称
`current_usage_quantity`	integer	本次核销数量
`status`	string	`COMPLETED` / `CANCELLED` / `FAILED`
`points_code`	string	核销健康站编码（可空）
`initiated_at`	string	核销发起时间
`rating`	integer	用户评分（1-5，用户评价后填充）

错误码

code	HTTP 状态	说明	处理建议
`CARD_NOT_FOUND`	404	卡号不存在或不属于当前应用	确认卡号是否正确
`CARD_EXPIRED`	422	权益卡已过期	提示用户权益已到期
`BENEFIT_ITEM_INACTIVE`	422	权益项不可用（已暂停或未激活）	联系平台运营
`NO_REMAINING_QUOTA`	422	权益项剩余次数不足	提示用户本权益已用完
`SERVICE_PROVIDER_UNAUTHORIZED`	403	当前服务方无权核销此权益项	确认服务方权限配置
`DUPLICATE_FULFILLMENT`	422	同一用户同一权益在短时间内重复核销	检查是否误触发，等待冷却后重试
`HTTP_401`	401	签名校验失败	检查 AppKey/AppSecret 和签名算法

服务方注册流程

接入供应商 API 前，需完成以下注册步骤：

提交合作申请：通过首页合作申请表单提交服务方信息（机构名称、类型、联系方式）。
平台审核：晓葆平台审核服务方资质（通常 3 个工作日内）。
配置权限：审核通过后，平台运营在管理台配置该服务方可核销的权益项清单（allowed_benefit_item_ids）。
获取凭证：在控制台创建应用，获取 AppKey 和 AppSecret，用于 API 鉴权。
接口联调：在测试环境完成核销接口联调，验证核销逻辑与响应处理。

当前供应商 API 处于内测阶段。如需提前接入，请联系 open@xiaobaotop.com 或通过首页表单提交申请。

客户端接入