Baccarat B2B OpenAPI · AI Integration Prompt
← 返回中文文档 English Docs OpenAPI Explorer

AI 辅助一键对接提示词(Claude Code / Codex / Cursor)

复制下方完整提示词发送给你的 AI 编程助手,即可严格按照本平台 OpenAPI 3.1 规范、HMAC 原始字节验签与幂等规则生成商户侧无缝钱包回调服务、S2S 客户端与全套边界单测。

You are implementing a production-grade B2B Operator Seamless Wallet integration with Baccarat Live Platform (OpenAPI 3.1 / C01).

Authoritative machine-readable contracts:
- OpenAPI 3.1 YAML: https://openapi.lt.cniia.cloud/openapi.yaml
- OpenAPI 3.1 JSON: https://openapi.lt.cniia.cloud/openapi.json
- Chinese Markdown Guide: https://openapi.lt.cniia.cloud/openapi-docs.md
- English Markdown Guide: https://openapi.lt.cniia.cloud/en/openapi-docs.md
- Sandbox S2S Base URL: https://api.lt.cniia.cloud (24x7 live studio tableId = "T-A2")

Mandatory implementation rules (DO NOT deviate):
1. Authentication & Signature (Both Directions):
   - Every inbound S2S request to /operator/v1/* AND every outbound wallet webhook to {callbackUrl}/wallet/* uses:
     - Header X-API-Key: ak_<32hex>
     - Header X-Signature: 64-char lowercase hex HMAC-SHA256(rawUtf8BodyBytes, hmacSecret)
   - CRITICAL: Verify webhook X-Signature over the EXACT raw HTTP request body bytes BEFORE JSON parsing, using constant-time comparison (crypto.timingSafeEqual / hmac.compare_digest). Return HTTP 200 with { traceId, status: "SC_INVALID_SIGNATURE", message } on mismatch, and { traceId, status: "SC_AUTHENTICATION_FAILED", message } on unknown X-API-Key.
2. Protocol Envelope & Monetary Precision:
   - All endpoints return HTTP 200 with { traceId, status: "SC_OK", data: ... } or { traceId, status: "SC_*", message }.
   - Never use traceId as an idempotency key.
   - Store and compute money using exact Decimal / integer minor units (never IEEE-754 floats). Return data.balance as an exact non-negative Decimal string (e.g. "1000.00" for USD) and data.timestamp in epoch milliseconds.
3. Implement all 4 Seamless Wallet Webhook endpoints under {callbackUrl}:
   - POST /wallet/balance: Verify token & currency -> return { traceId, status: "SC_OK", data: { username, currency, balance, timestamp } }. Read-only.
   - POST /wallet/bet: Deduplicate strictly by unique transactionId ("bet_<32hex>").
     - Same transactionId + same (username, betId, roundId, currency, amount): DO NOT deduct again; return HTTP 200 + status "SC_OK" + current balance. NEVER return SC_TRANSACTION_DUPLICATED for same-payload retries!
     - Same transactionId + different payload: return status "SC_TRANSACTION_DUPLICATED".
     - Insufficient funds: return status "SC_INSUFFICIENT_FUNDS".
   - POST /wallet/bet_result: Deduplicate strictly by unique transactionId ("stl_<32hex>").
     - Credit winAmount to player balance (WIN: winAmount = betAmount + netPayout; PUSH tie refund: resultType="WIN", winAmount=betAmount, winLoss="0.00"; LOSE: resultType="LOSE", winAmount="0.00"). Return SC_OK + updated balance.
   - POST /wallet/rollback: Deduplicate strictly by unique transactionId ("rb_<ticketId>" or "late_<betTxId>").
     - If betId was previously deducted and not rolled back, refund amount once and return SC_OK + updated balance.
     - If betId was NEVER deducted on our side, return SC_TRANSACTION_NOT_EXISTS (or SC_OK without crediting) — empty-success rule.
4. Implement S2S client methods + automated tests:
   - POST /operator/v1/game/tables, POST /operator/v1/game/url, POST /operator/v1/game/terminate, POST /operator/v1/transaction/list, POST /operator/v1/transaction/detail (window <= 7 days).
   - Include unit/integration tests covering raw-byte HMAC verification, same-key replay SC_OK, same-key mutated-amount SC_TRANSACTION_DUPLICATED, insufficient funds, Tie PUSH, LOSE 0.00, and non-existent bet rollback.