> ## Documentation Index
> Fetch the complete documentation index at: https://doc.va777.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速開始

> 以創建會員、存款、取得遊戲連結、撈取注單、取款的完整流程，示範轉帳錢包的串接方式。

本頁用一個會員從建立到結束遊戲的完整流程，示範轉帳錢包的串接方式。開始前請先完成首頁的[串接前準備](https://doc.va777.net/zh-Hant/v2.md#串接前準備)，取得 API 網域 `{host}`、驗證令牌與 API Key。

## 整體流程

```mermaid theme={null}
sequenceDiagram
    participant M as 會員
    participant S as 貴司伺服器
    participant V as VA API
    S->>V: 1. 創建會員 member/create
    S->>V: 2. 存款 transaction/deposit
    S->>V: 3. 取得遊戲連結 game/link
    V-->>S: 遊戲網址 url
    S-->>M: 導向遊戲網址
    M->>V: 進行遊戲
    loop 定期
        S->>V: 4. 撈取注單 betlog/listByTime
    end
    S->>V: 5. 取款 transaction/withdraw
```

轉帳錢包模式下，會員的遊戲點數存放在我方。會員遊戲前，貴司從自己的錢包轉入點數（存款）；會員離開後，再把點數轉回（取款）。

## 範例說明

* 以下範例都使用 API Key `a188va` 計算 `sign`，實際串接請改用我方提供的 API Key，並依[簽章規則](https://doc.va777.net/zh-Hant/v2/guides/signature.md)計算。
* `POST` 請求以 `multipart/form-data` 傳送（curl 的 `-F`），`GET` 請求以 query string 傳送（curl 的 `-G --data-urlencode`）。
* 每次回應都請以 `status.code` 判斷結果，`0` 為成功，其他代碼請見[回應訊息碼](https://doc.va777.net/zh-Hant/v2/reference/response-codes.md)。

## 1. 創建會員

會員第一次進入遊戲前，先呼叫[創建會員](https://doc.va777.net/zh-Hant/v2/api-reference/member/create.md)。同一個帳號在不同渠道會被視為不同會員，帳號也區分大小寫。

```bash theme={null}
curl -X POST "{host}/vendor/v2.0/member/create" \
  -H "Authorization: {token}" \
  -F channelID=1 \
  -F account=player001 \
  -F currency=CNY \
  -F sign=999d2836a05da3baa7f951d12954c23a
```

如果帳號已存在，會回傳 `202`，可以直接沿用該帳號。

## 2. 存款

呼叫[存款](https://doc.va777.net/zh-Hant/v2/api-reference/transaction/deposit.md)把點數轉入會員錢包。`transactionID` 必須唯一，並以 `deposit-` 開頭。

```bash theme={null}
curl -X POST "{host}/vendor/v2.0/transaction/deposit" \
  -H "Authorization: {token}" \
  -F transactionID=deposit-20250101000001 \
  -F channelID=1 \
  -F account=player001 \
  -F currency=CNY \
  -F amount=10.00 \
  -F sign=4899d19dd28e49b04e1656afb1f7dc4f
```

回應的 `data` 會包含存款前後的餘額 `balanceBefore`、`balanceAfter`。建議貴司保存 `transactionID` 與回應內容，方便日後以[取得存取款詳細資訊](https://doc.va777.net/zh-Hant/v2/api-reference/transaction/detail.md)對帳。

## 3. 取得遊戲連結

呼叫[取得遊戲連結](https://doc.va777.net/zh-Hant/v2/api-reference/game/link.md)，再把會員導向回應中的 `url`。`gameID` 帶 `0` 會進入遊戲大廳；指定遊戲請先以[取得遊戲列表](https://doc.va777.net/zh-Hant/v2/api-reference/game/list.md)查詢遊戲編號。

```bash theme={null}
curl -G "{host}/vendor/v2.0/game/link" \
  -H "Authorization: {token}" \
  --data-urlencode channelID=1 \
  --data-urlencode account=player001 \
  --data-urlencode currency=CNY \
  --data-urlencode gameID=0 \
  --data-urlencode gamePlat=web \
  --data-urlencode app=N \
  --data-urlencode lang=zh-TW \
  --data-urlencode clientIP=203.0.113.10 \
  --data-urlencode sign=13d27c924481027ae6f16b0d79cdaced
```

遊戲連結的有效時間為 300 秒，請在取得後立即導向會員。`clientIP` 是會員的 IP，不參與簽章。可用語系請見[語言列表](https://doc.va777.net/zh-Hant/v2/reference/languages.md)。

## 4. 撈取注單

會員遊戲期間，請定期呼叫[取得注單列表](https://doc.va777.net/zh-Hant/v2/api-reference/betlog/list-by-time.md)取得注單。第一次查詢時 `nextToken` 帶空字串，空字串一樣要納入簽章。

```bash theme={null}
curl -G "{host}/vendor/v2.0/betlog/listByTime" \
  -H "Authorization: {token}" \
  --data-urlencode channelID=1 \
  --data-urlencode startTime=2025-12-01T00:00:00.000+08:00 \
  --data-urlencode endTime=2025-12-01T00:01:00.000+08:00 \
  --data-urlencode nextToken= \
  --data-urlencode maxResults=5000 \
  --data-urlencode sign=d1afe83cb4e05a496cc2311cc0cbc2f6
```

資料超過一頁時，請依[分頁與連續撈單](https://doc.va777.net/zh-Hant/v2/guides/pagination.md)帶入上一次回傳的 `nextToken` 繼續查詢；連續撈取時，上一次的結束時間應等於本次的開始時間，避免漏單。

## 5. 取款

會員結束遊戲後，呼叫[取款](https://doc.va777.net/zh-Hant/v2/api-reference/transaction/withdraw.md)把點數轉回貴司錢包。`transactionID` 必須唯一，並以 `withdraw-` 開頭。取款金額可先以[取得當前遊戲點數](https://doc.va777.net/zh-Hant/v2/api-reference/member/balance.md)查詢。

```bash theme={null}
curl -X POST "{host}/vendor/v2.0/transaction/withdraw" \
  -H "Authorization: {token}" \
  -F transactionID=withdraw-20250101000001 \
  -F channelID=1 \
  -F account=player001 \
  -F currency=CNY \
  -F amount=10.00 \
  -F sign=67628704041cb512f64c16540262d788
```

## 對帳

| 用途 | API |
| - | - |
| 查詢存取款紀錄 | [取得存取款列表](https://doc.va777.net/zh-Hant/v2/api-reference/transaction/list.md)、[取得存取款詳細資訊](https://doc.va777.net/zh-Hant/v2/api-reference/transaction/detail.md) |
| 查詢點數異動 | [取得點數異動紀錄](https://doc.va777.net/zh-Hant/v2/api-reference/transaction/change-list.md) |
| 查詢輸贏統計 | [取得幣別報表](https://doc.va777.net/zh-Hant/v2/api-reference/report/currency.md)、[取得會員報表](https://doc.va777.net/zh-Hant/v2/api-reference/report/member.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.