LOTTERY INTEGRATION GUIDE

彩票代理接入技术文档

本页面用于给客户技术团队直接阅读和联调，按文档页方式展示接入说明，包含目录、数据流、接口约束、联调步骤和上线前检查项。

接入方式

SSO + 钱包接口

适用对象

客户技术团队

文档形态

后台独立页面

@foreach ($sections as $section) {{ $section['title'] }} @endforeach

1. 文档概览

本文档用于指导客户将自有主站接入我方彩票端，形成完整的登录、跳转、余额、投注扣款与派奖加款链路。

登录接入

客户主站登录后，通过 SSO 进入彩票端，无需再次认证。

钱包接入

投注与派奖资金动作由我方调用客户钱包接口完成。

联调验收

客户、我方技术与测试按照同一套流程完成联调和上线验收。

适用范围

适用于 H5、Web、App 内嵌 WebView 等进入彩票端的接入方式。

2. 接入架构

客户系统与彩票端的职责边界如下，登录由主站发起，资金由主站钱包记账，彩票端负责业务过程编排。

01 客户主站

用户登录与身份来源

客户负责维护会员账号、登录态和唯一用户标识。

02 SSO 网关

生成短期 token

客户服务端生成签名凭证，浏览器携带后进入彩票端。

03 彩票端

验签并建立会话

我方校验 token 后创建会话，承接投注、撤单、派奖等业务流程。

04 客户钱包

余额与账务真理源

余额查询、扣款、加款由客户钱包接口统一响应并负责幂等记账。

端到端链路

1. 用户在客户主站完成登录。
2. 客户服务端生成 SSO token。
3. 浏览器跳转到彩票端入口地址。
4. 彩票端校验 token 并建立用户会话。
5. 用户查询余额、进行投注或等待派奖。
6. 彩票端按业务场景调用客户钱包接口。
7. 钱包返回处理结果，彩票端落业务状态并反馈前端。

3. 对接前准备

双方开始联调前，需要先完成以下准备项，避免联调阶段反复返工。

客户需提供

• 站点名称、站点编码、测试环境与生产环境标识。
• 技术联系人、测试联系人、上线当天紧急联系人。
• 客户主站域名、钱包接口域名、可嵌入来源域名。
• 测试账号、测试余额和可重复联调的测试场景说明。

双方需共同确认

• SSO 密钥或 JWT 验签密钥。
• 钱包 API 鉴权方式、签名算法、请求头规范。
• 钱包三类接口地址：余额、扣款、加款。
• 请求超时、重试策略、幂等键和错误码表。

4. SSO 单点登录

客户用户在主站登录后，通过服务端签发的短期 token 进入彩票端，我方校验通过后自动建立会话。

推荐接入流程

1. 客户主站用户完成登录。
2. 客户服务端按约定字段组装 SSO 负载。
3. 使用共享密钥签发 token，并设置短期过期时间。
4. 浏览器跳转我方彩票端地址，携带 token 参数。
5. 我方校验签名、时间戳、站点编码和用户标识后建立彩票端登录态。

SSO 关键约束

• token 必须是短时有效，建议 60 到 300 秒。
• `user_id` 在客户站点内必须稳定且唯一。
• `site_code` 必须与约定站点保持一致。
• 生产密钥与测试密钥必须隔离。
• 不可把签名密钥暴露在前端代码里。

SSO 负载示例

{
  "user_id": "100001",
  "username": "demo_user",
  "site_code": "demo",
  "timestamp": 1718000000,
  "nonce": "N8F2X9Q1",
  "currency": "CNY",
  "device": "h5"
}

5. 钱包接口

我方会调用客户钱包完成账务动作。客户至少需要实现余额查询、扣款、加款三类能力。

余额查询

用于进入彩票端、下注前或关键账务时机同步可用余额。

POST /wallet/balance

扣款接口

用于用户下注成功后的资金扣减，必须以交易号作为唯一幂等键。

POST /wallet/debit

加款接口

用于派奖、退款或撤单返还资金，重复请求不得重复记账。

POST /wallet/credit

扣款报文示例

{
  "site_code": "demo",
  "user_id": "100001",
  "transaction_id": "BET202606100001",
  "order_id": "TICKET202606100001",
  "amount": "20.00",
  "timestamp": 1718000001,
  "sign": "xxxxxx"
}

成功返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "transaction_id": "BET202606100001",
    "balance": "980.00"
  }
}

6. 签名与安全

签名规则和密钥保护是接入稳定性的基础。推荐统一采用服务端签名并在所有敏感请求中校验。

推荐签名规则

1. 请求字段按字段名升序排序。
2. 以 `key=value` 形式拼接原始串。
3. 原始串尾部追加共享密钥。
4. 使用 `HMAC-SHA256` 计算签名。
5. 结果输出为十六进制小写字符串。

安全要求

• 所有请求必须使用 HTTPS。
• token 和钱包请求必须校验时间戳与签名。
• 建议增加 nonce 或 request_id 防止重放。
• 测试环境与生产环境密钥不得共用。
• 密钥轮换时必须预留并行切换窗口。

7. 错误码与幂等

为了保证交易可重试、可审计，客户钱包接口必须统一错误码并支持强幂等。

建议错误码

• `0`：成功
• `1001`：参数错误
• `1002`：签名错误
• `1003`：用户不存在
• `1004`：余额不足
• `1006`：重复交易
• `1099`：系统异常

幂等处理要求

• 扣款和加款必须使用 `transaction_id` 作为唯一交易键。
• 同一 `transaction_id` 的重复请求，不得重复扣款或重复加款。
• 已成功处理的交易，重复请求必须返回首次处理结果。
• 钱包超时或网络抖动时，我方可能发起重试，因此客户必须按幂等方式落账。

8. 联调与验收

建议双方按固定节奏联调，先通登录链路，再通钱包链路，最后做异常回归和上线核验。

联调顺序

1. 域名连通与证书校验。
2. SSO token 生成与跳转验证。
3. 余额查询接口联调。
4. 扣款和加款接口联调。
5. 超时、重复请求和余额不足场景回归。

上线前检查清单

• 正式域名、正式密钥和正式白名单均已配置。
• 测试环境和生产环境参数已分离。
• 核心错误码、日志和告警已对齐。
• 关键交易链路已通过验收回归。
• 上线当天应急联系人与回滚预案已确认。

9. 附录

为了减少不同系统之间的解析差异，建议双方统一基础字段格式。

金额字段

统一使用字符串传输，例如 `1000.00`，避免浮点精度误差。

时间字段

建议使用 Unix 时间戳秒级，双方也可统一为 ISO8601。

报文格式

字符编码统一 UTF-8，请求内容类型统一 `application/json`。