开放平台 · SSO 对接

密探开发者文档

复用密探的用户身份体系与积分体系，快速接入你的平台。验证身份、查询余额、扣款退款、卡密充值，一套接口全部搞定。

注册对接方注册 · 获取密钥

接入密探资金接口（扣款/退款/查余额等）前，请先在此注册你的对接方身份，系统会为你自动生成一把唯一密钥（secret_key）。

用途说明：这把密钥用于标识「你是谁」。后续调用所有 /api/sso/* 接口时，必须在请求头携带 X-SSO-KEY: 你的密钥。密钥即身份，密探据此识别调用方，并保证退款只能由原扣款方发起，防止他人伪造退款。

注意：注册后密钥默认停用，需联系密探运营在后台「启用」后才会生效。密钥仅本次展示，请立即复制保存。

概述对接概述

密探开放了一套标准 SSO 接口，供第三方平台复用密探的用户身份体系和积分体系（积分与人民币 1:1 等价）。

第三方平台只需拿到用户在密探 App 登录后产生的 token，即可调用以下接口完成：验证用户身份、查询余额、扣款 / 退款、卡密充值。

鉴权鉴权方式

所有接口采用双重鉴权：

鉴权项	传递方式	说明
用户 token	query 参数 / body 字段 token	密探登录 token，标识「操作用户本人」
服务间密钥	请求头 X-SSO-KEY	对接方注册获得的唯一密钥，标识「调用方身份」

安全说明：token 为加密字符串，无法伪造，一个 token 仅能操作其对应的那一个用户本人；X-SSO-KEY 标识对接方身份，密钥不匹配或未启用将返回 401，且退款只能由原扣款方发起。

接口 1验证身份

校验 token 有效性，返回对应用户的身份信息。

POST/api/sso/verify?token={token}

参数	类型	必填	说明
token	string	是	密探登录 token

{
  "user_id": 123,
  "nickname": "张三",
  "avatar": "https://qwert888.asia/static/avatars/xxx.jpg"
}

接口 2查询余额

查询用户当前余额。返回 balance（元，可带两位小数）与 balance_fen（分，整数，用于精确结算）。

GET/api/sso/balance?token={token}

参数	类型	必填	说明
token	string	是	密探登录 token

{
  "user_id": 123,
  "balance": 1000.50,
  "balance_fen": 100050
}

接口 3扣款 / 退款

对用户余额进行扣款（pay）或退款（refund）。注意：调用本接口必须在请求头携带 X-SSO-KEY（你的对接方密钥），否则 401。

POST/api/sso/charge

参数	类型	必填	说明
token	string	是	密探登录 token
amount	number	是	金额（元，可带小数，内部按分精确结算、向上取整）；退款时忽略此值（按扣款单本金退）
order_no	string	是	订单号（唯一，用于幂等防重复扣款）
type	string	是	`pay` = 扣款，`refund` = 退款

{
  "token": "xxx",
  "amount": 100,
  "order_no": "ORDER_20260927_001",
  "type": "pay"
}

说明：order_no 为幂等键，同一个 order_no 重复请求不会重复扣款/退款，直接返回当前余额。扣款会按平台抽成比例（fee）加收抽成，退款只退本金、不退抽成。

接口 4卡密充值

验证用户输入的卡密，验证通过后给用户增加余额，卡密标记为已使用（一次性）。

POST/api/sso/recharge

参数	类型	必填	说明
token	string	是	密探登录 token
card_code	string	是	用户输入的卡密号
order_no	string	是	充值订单号（唯一，幂等）

{
  "token": "xxx",
  "card_code": "ABC123456789",
  "order_no": "RECHARGE_20260927_001"
}

说明：卡密由密探后台生成/管理，第三方平台只负责将用户输入的 card_code 原样透传。

错误码错误码说明

HTTP 状态码	含义	处理建议
200	成功	—
400	参数错误 / 余额不足 / 卡密无效或已使用	提示用户检查卡密或余额
401	token 无效 / 已过期 / 登录已失效；或 X-SSO-KEY 缺失、无效、未启用	引导用户重新登录密探获取新 token；检查密钥是否已注册并启用

常见错误 detail：

detail	场景
缺少 token	未传 token
token 无效或已过期	token 格式错误或已过期
登录已失效，请重新登录	用户已退出登录或改密，token 失效
无效的服务间密钥	X-SSO-KEY 密钥不存在或不匹配
对接方已停用	该对接方密钥已被后台停用
余额不足	扣款时余额不够
卡密无效	卡密号不存在
卡密已被使用	卡密已核销过

流程对接流程

用户在密探 App 内点击「接码」等入口

密探 App 携带 token 跳转到第三方平台（?token=xxx）

第三方平台调用 /api/sso/verify 验证身份

第三方平台调用 /api/sso/balance 查询余额

用户下单消费 → 调用 /api/sso/charge 扣款

用户充值 → 输入卡密 → 调用 /api/sso/recharge 入账

密探 开发者文档