# 真人视讯百家乐 · B2B 运营商单一无缝钱包 OpenAPI 接入指南（v1.0.0）

- OpenAPI 3.1 YAML: `https://openapi.lt.cniia.cloud/openapi.yaml`
- OpenAPI 3.1 JSON: `https://openapi.lt.cniia.cloud/openapi.json`
- 联调沙箱 S2S 网关: `https://api.lt.cniia.cloud`
- 联调沙箱玩家端大厅: `https://play.lt.cniia.cloud`（24×7 常驻真视觉桌台 `T-A2`、演示桌 `T-A1`）

## 1. 鉴权、签名与信封规范

1. **双向公共请求头**：入站 `/operator/v1/*` 与出站 `{callbackUrl}/wallet/*` 均携带：
   - `Content-Type: application/json`
   - `X-API-Key: ak_<32位十六进制>`
   - `X-Signature: <64位小写十六进制>` = `HMAC-SHA256(rawJsonBodyBytes, hmacSecret)`（**必须对原始 UTF-8 请求体字节计算，严禁解析后再序列化**）。
2. **统一响应信封**：所有接口返回 `HTTP 200`，成功体为 `{ "traceId": "...", "status": "SC_OK", "data": { ... } }`，业务或校验拒绝返回 `{ "traceId": "...", "status": "SC_*", "message": "...", "validation"?: { ... } }`。
3. **金额精度**：所有出站金额字段均为精确十进制字符串（如 `"100.00"`）；商户回调 `data.balance` 推荐返回十进制字符串（亦兼容有限非负 JSON 数字），`data.timestamp` 为入账毫秒时间戳。

## 2. 入站 S2S 接口清单（运营商 → 平台）

### `POST /operator/v1/game/url` — Issue one-time player launch URL & wallet session token

Validates operator table/currency permissions and responsible-gaming status, performs a synchronous pre-launch `POST {callbackUrl}/wallet/balance` probe with the newly minted `b2bt_` token, persists the single-use launch token (default TTL 900s), and returns the H5/Web launch URL.

```json
{
  "traceId": "e62ceec8-1c18-48fc-af0e-9f9f943b2554",
  "username": "player_9527",
  "tableId": "T-A2",
  "language": "zh-CN",
  "platform": "H5",
  "currency": "USD",
  "lobbyUrl": "https://merchant.example.com/lobby",
  "ipAddress": "203.0.113.42"
}
```

```json
{
  "traceId": "e62ceec8-1c18-48fc-af0e-9f9f943b2554",
  "status": "SC_OK",
  "data": {
    "gameUrl": "https://play.lt.cniia.cloud/?token=b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819&tableId=T-A2&lang=zh-CN",
    "token": "b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819"
  }
}
```

### `POST /operator/v1/game/tables` — List permitted live tables & dynamic betting limits

Returns paginated configured/suspended tables permitted for the authenticated operator, including effective `minBet`, `maxBet` (intersected with table override, global cap, FX benchmark, and operator risk limit template), `chipUnit`, and cover image URL.

```json
{
  "traceId": "7f19b4a2-3d10-4c9a-9e21-5518a0c21101",
  "currency": "USD",
  "pageNo": 1,
  "pageSize": 50
}
```

```json
{
  "traceId": "7f19b4a2-3d10-4c9a-9e21-5518a0c21101",
  "status": "SC_OK",
  "data": {
    "tables": [
      {
        "tableId": "T-A2",
        "gameCode": "BACCARAT_T-A2",
        "tableName": "Studio VIP Baccarat A2",
        "gameType": "BACCARAT",
        "currency": "USD",
        "status": "OPEN",
        "minBet": "10.00",
        "maxBet": "5000.00",
        "chipUnit": "1.00",
        "languages": [
          "en",
          "zh-CN"
        ],
        "platforms": [
          "web",
          "H5"
        ],
        "coverImageUrl": "https://play.lt.cniia.cloud/player/v1/table-images/4b825dc642cb6eb9a060e54bf8d69288fbee4904f1e2d3c4b5a6978877665544.jpg"
      }
    ],
    "pageNo": 1,
    "pageSize": 50,
    "total": 1
  }
}
```

### `POST /operator/v1/game/terminate` — Force-terminate player sessions & unused launch tokens

Immediately revokes all active player Web/WS sessions (`revokeReason = "TERMINATED"`) and unredeemed `b2b_launch_tokens` for `username` under the calling operator. Already-accepted in-flight bets remain bound to their round and settle or void normally without losing idempotency.

```json
{
  "traceId": "9c8812d0-0420-4f71-8c1b-33a90012ef90",
  "username": "player_9527"
}
```

```json
{
  "traceId": "9c8812d0-0420-4f71-8c1b-33a90012ef90",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "terminatedSessions": 1,
    "revokedLaunchTokens": 0
  }
}
```

### `POST /operator/v1/transaction/list` — Paginated settled/voided ticket reconciliation feed

Queries settled/voided tickets belonging to the authenticated operator filtered inclusively by `settledAt` in `[fromTime, toTime]` (epoch milliseconds), ordered deterministically by `(settledAt ASC, ticketId ASC)`. Default `pageSize = 2000`, maximum `20000`.

```json
{
  "traceId": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "fromTime": 1763611200000,
  "toTime": 1763614800000,
  "pageNo": 1,
  "pageSize": 2000
}
```

```json
{
  "traceId": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "status": "SC_OK",
  "data": {
    "transactions": [
      {
        "betId": "cm3p9z1x0000108l47a9g2k1m",
        "roundId": "cm3p9y0a0000008l4b1122334",
        "externalTransactionId": "cm3p9z1x0000108l47a9g2k1m",
        "username": "player_9527",
        "currencyCode": "USD",
        "gameCode": "BACCARAT_T-A2",
        "betSide": "PLAYER",
        "betAmount": "100.00",
        "winAmount": "200.00",
        "winLoss": "100.00",
        "effectiveTurnover": "100.00",
        "status": 1,
        "vendorBetTime": 1763612010120,
        "vendorSettleTime": 1763612038450
      }
    ],
    "pageNo": 1,
    "pageSize": 2000,
    "total": 1
  }
}
```

### `POST /operator/v1/transaction/detail` — Inspect single ticket & verified round card outcome

Looks up a single ticket `betId` within `[fromTime, toTime]` (window **must be `<= 7 days`**, i.e. `604800000` ms). Matches if either `vendorBetTime` or `vendorSettleTime` falls inside `[fromTime, toTime]`, including unsettled (`status = 0`) tickets, and attaches verified `roundResult` points/pairs/natural flags when settled.

```json
{
  "traceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "betId": "cm3p9z1x0000108l47a9g2k1m",
  "fromTime": 1763550000000,
  "toTime": 1763636400000
}
```

```json
{
  "traceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "SC_OK",
  "data": {
    "betId": "cm3p9z1x0000108l47a9g2k1m",
    "roundId": "cm3p9y0a0000008l4b1122334",
    "externalTransactionId": "cm3p9z1x0000108l47a9g2k1m",
    "username": "player_9527",
    "currencyCode": "USD",
    "gameCode": "BACCARAT_T-A2",
    "betSide": "PLAYER",
    "betAmount": "100.00",
    "winAmount": "200.00",
    "winLoss": "100.00",
    "effectiveTurnover": "100.00",
    "status": 1,
    "vendorBetTime": 1763612010120,
    "vendorSettleTime": 1763612038450,
    "roundResult": {
      "outcome": "PLAYER",
      "playerPoints": 8,
      "bankerPoints": 5,
      "playerPair": false,
      "bankerPair": false,
      "natural": true
    }
  }
}
```

## 3. 出站无缝钱包回调（平台 → 运营商 `{callbackUrl}`）

### `POST {callbackUrl}/wallet/balance — Query player available balance`

Invoked synchronously during `/operator/v1/game/url` pre-launch check and when the player refreshes wallet balance in the live table UI. Read-only; must never mutate player balance.

```json
{
  "traceId": "e62ceec8-1c18-48fc-af0e-9f9f943b2554",
  "username": "player_9527",
  "currency": "USD",
  "token": "b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819"
}
```

```json
{
  "traceId": "e62ceec8-1c18-48fc-af0e-9f9f943b2554",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "currency": "USD",
    "balance": "1000.00",
    "timestamp": 1763612005000
  }
}
```

### `POST {callbackUrl}/wallet/bet — Deduct player stake (idempotent by transactionId)`

Invoked outside PostgreSQL transactions after risk & betting-window checks pass. Guarded by `opbet:{operatorId}:{transactionId}` (`transactionId = bet_<32hex>`).

- **Idempotent replay**: Same `transactionId` + same payload -> do NOT deduct again; return `HTTP 200` + `status: "SC_OK"` + current `data.balance`.
- **Conflict**: Same `transactionId` + different payload -> return `status: "SC_TRANSACTION_DUPLICATED"`.
- **Insufficient balance**: Return `status: "SC_INSUFFICIENT_FUNDS"`.

```json
{
  "traceId": "3d55f1a9-7c80-4e11-b022-8f9910a4bc12",
  "username": "player_9527",
  "transactionId": "bet_4a19f08c2e77b3109d44e6128a5bc091",
  "betId": "cm3p9z1x0000108l47a9g2k1m",
  "externalTransactionId": "cm3p9z1x0000108l47a9g2k1m",
  "amount": "100.00",
  "currency": "USD",
  "token": "b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819",
  "gameCode": "BACCARAT_T-A2",
  "roundId": "cm3p9y0a0000008l4b1122334",
  "timestamp": 1763612010120
}
```

```json
{
  "traceId": "3d55f1a9-7c80-4e11-b022-8f9910a4bc12",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "currency": "USD",
    "balance": "900.00",
    "timestamp": 1763612010185
  }
}
```

### `POST {callbackUrl}/wallet/bet_result — Per-ticket settlement payout / loss / push`

Invoked per ticket upon verified round settlement. Guarded by `opsettle:{operatorId}:{transactionId}` (`transactionId = stl_<32hex>`).

- **WIN**: `resultType = "WIN"`, `winAmount = betAmount + netPayout`, `winLoss = +netPayout`, `effectiveTurnover = betAmount`.
- **LOSE**: `resultType = "LOSE"`, `winAmount = "0.00"`, `winLoss = -betAmount`, `effectiveTurnover = betAmount`.
- **PUSH (Tie refund)**: `resultType = "WIN"`, `winAmount = betAmount`, `winLoss = "0.00"`, `effectiveTurnover = "0.00"`.

```json
{
  "traceId": "8b7719c2-61a4-49d0-92ef-1102a3b4c5d6",
  "username": "player_9527",
  "transactionId": "stl_90e12d4b7c6a8812f34509ab12cd34ef",
  "betId": "cm3p9z1x0000108l47a9g2k1m",
  "externalTransactionId": "cm3p9z1x0000108l47a9g2k1m",
  "roundId": "cm3p9y0a0000008l4b1122334",
  "betAmount": "100.00",
  "winAmount": "200.00",
  "effectiveTurnover": "100.00",
  "winLoss": "100.00",
  "jackpotAmount": "0.00",
  "resultType": "WIN",
  "isFreespin": 0,
  "isEndRound": 1,
  "currency": "USD",
  "token": "b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819",
  "gameCode": "BACCARAT_T-A2",
  "betTime": 1763612010120,
  "settledTime": 1763612038450
}
```

```json
{
  "traceId": "8b7719c2-61a4-49d0-92ef-1102a3b4c5d6",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "currency": "USD",
    "balance": "1100.00",
    "timestamp": 1763612038510
  }
}
```

### `POST {callbackUrl}/wallet/rollback — Void refund or late-round-close compensation`

Reverses a prior `/wallet/bet` stake for round `VOID`, manual held-ticket void (`rb_<ticketId>`), or late-round-close race compensation (`late_<betTxId>`). Guarded by `oprollback:{operatorId}:{transactionId}`.

- **Empty-Success Rule**: If the original `betId` was never deducted on the operator side, return `SC_TRANSACTION_NOT_EXISTS` (or `SC_OK` without crediting) — the platform converges both to `COMPLETED` empty-success.

```json
{
  "traceId": "c1094e22-8831-42b7-9901-77a6b5c4d3e2",
  "username": "player_9527",
  "transactionId": "rb_cm3p9z1x0000108l47a9g2k1m",
  "betId": "cm3p9z1x0000108l47a9g2k1m",
  "externalTransactionId": "cm3p9z1x0000108l47a9g2k1m",
  "roundId": "cm3p9y0a0000008l4b1122334",
  "amount": "100.00",
  "currency": "USD",
  "token": "b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819",
  "gameCode": "BACCARAT_T-A2",
  "timestamp": 1763612042000
}
```

```json
{
  "traceId": "c1094e22-8831-42b7-9901-77a6b5c4d3e2",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "currency": "USD",
    "balance": "1000.00",
    "timestamp": 1763612042060
  }
}
```

## 4. 状态码字典（`SC_*`）

| 状态码 | 分类 | 可同键重试 | 说明 |
| --- | --- | --- | --- |
| `SC_OK` | SUCCESS | NO | 请求成功，或相同业务内容的资金幂等重放（重放必须返回最新余额 + SC_OK） |
| `SC_INVALID_REQUEST` | VALIDATION | NO | 请求体缺少必填参数、类型/长度/格式非法，或分页/时间窗口越界（附 validation 字段明细） |
| `SC_AUTHENTICATION_FAILED` | AUTH | NO | 缺少/无效/已停用的 X-API-Key、来源 IP 不在白名单，或商户未配置 callbackUrl |
| `SC_INVALID_SIGNATURE` | AUTH | NO | X-Signature HMAC-SHA256 校验失败（请确保对原始 UTF-8 JSON 请求体字节签名，64 位十六进制） |
| `SC_INVALID_TOKEN` | SESSION | NO | 进桌会话令牌 token 无效、已过期或不属于当前用户/商户 |
| `SC_INVALID_GAME` | GAME | NO | 桌台 tableId 不存在、尚未完成初始化配置，或未授权给当前商户（allowedTables） |
| `SC_USER_NOT_EXISTS` | USER | NO | 指定 username 在当前商户下不存在映射玩家（如 /game/terminate 踢人时） |
| `SC_USER_DISABLED` | USER | NO | 玩家账号已被禁用，或处于负责任博彩冷静期（COOLING_OFF）/ 自我排除（SELF_EXCLUSION）期内 |
| `SC_WRONG_CURRENCY` | CURRENCY | NO | 请求币种与桌台运行币种不一致，或商户钱包回调返回的 data.currency 与请求币种不符 |
| `SC_CURRENCY_NOT_SUPPORTED` | CURRENCY | NO | 平台未配置该币种，或该币种未对当前商户开通（allowedCurrencies） |
| `SC_INSUFFICIENT_FUNDS` | WALLET | NO | 玩家在商户无缝钱包中的可用余额不足以扣除本次下注金额 |
| `SC_TRANSACTION_DUPLICATED` | IDEMPOTENCY | NO | 幂等冲突：同一 transactionId 被用于不同业务内容的请求（同键同体重放严禁返回此码，应返回 SC_OK） |
| `SC_TRANSACTION_NOT_EXISTS` | RECONCILE | NO | 查询单笔注单不存在/超出请求时间窗；或在 /wallet/rollback 时原注从未扣款成功（平台按空成功收敛） |
| `SC_TRANSACTION_STILL_PROCESSING` | TRANSIENT | YES | 同一幂等键正在处理中（租约期内），调用方应保持原 transactionId 稍后重试 |
| `SC_OPERATOR_TIMEOUT` | TRANSIENT | YES | 平台出站调用商户无缝钱包超时（默认 8000ms）或收到 HTTP 408/429/5xx 瞬态错误，后续将同键重试/冲正 |
| `SC_UNDER_MAINTENANCE` | MAINTENANCE | NO | 目标桌台处于维护挂起状态（SUSPENDED），或商户绑定的风控限额模板当前不可用 |
| `SC_GAME_DISABLED` | MAINTENANCE | NO | 对应游戏类型在当前站点已停用 |
