> ## 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.

# 請求與回應格式

> API 網址、Header、請求參數格式、時間格式與統一回應結構。

## 請求網址

```text theme={null}
{host}/{action}
```

* `{host}` 為我方提供的 API 網域。
* 範例：`https://game.bala.jp/vendor/v2.0/member/create`

## 請求參數格式

* `GET`、`DELETE` 方法：參數以 query string 傳遞。
* 其他方法：請求參數格式為 `multipart/form-data`。

## Header

每個請求都必須帶入以下 Header。若為我方提供的服務，介接商須帶入驗證令牌；若為介接商提供的服務，則需驗證我方帶入的令牌。

| Header | 值 | 說明 |
| - | - | - |
| `Authorization` | 驗證令牌 | 所有方法都需要 |
| `Content-Type` | `multipart/form-data` | 除 `GET`、`DELETE` 方法外都需要 |

## 連線方式

使用此系統時，請提供呼叫 API 的伺服器 IP 加入白名單。

## API 注意事項

* 不同 Channel（渠道）下的帳號會被視為**不同**會員，例如 channel-1 的 `Player001` 與 channel-2 的 `Player001` 在我方系統中是不同的會員。
* Channel 範圍為 `1` \~ `2147483647`。
* 我方提供會員單開服務，每次連線皆為獨立連線，並以各自的 token 識別。
* 會員遊戲時，遊戲端會定期更新該會員餘額並顯示於遊戲畫面；會員每次下注前皆會判斷餘額是否足夠。
* 會員於遊戲畫面閒置（無下注行為）超過 **5 分鐘**，我方會主動關閉該次連線。
* 會員可持有多種幣別錢包，各幣別錢包之間的餘額**無法**互相轉換。
* 部分 API 有呼叫次數限制，會標註於該 API 的說明中；未標註表示無次數限制。

### 時間格式

除特別說明的 API 外，時間格式皆為 **RFC3339**，須精確至**毫秒**並包含**時區資訊**：

```text theme={null}
2022-01-01T00:00:00.000+08:00
```

> [!NOTE]
>
> [取得幣別報表](https://doc.va777.net/api-reference/report/currency.md)與[取得會員報表](https://doc.va777.net/api-reference/report/member.md)使用精確至小時的 RFC3339 格式，例如 `2022-01-01T00+08:00`。

## 回應格式

HTTP 狀態碼固定為 `200`。每次回應皆包含 `data` 與 `status`，請以 `status.code` 判斷請求結果。

**data** `object | string | null`

API 回傳資料，內容依各 API 而定。

**status** `object` *required*

此次請求的處理狀態。

**屬性**

**code** `string` *required*

回應訊息碼，請參考[回應訊息碼](https://doc.va777.net/reference/response-codes.md)。

**message** `string` *required*

回應詳細訊息，為此次請求的回應狀況。

**datetime** `string` *required*

回應時間，記錄此次請求的接收時間，格式為 RFC3339。

**traceCode** `string` *required*

回應追蹤碼，為唯一值，方便雙方比對回應內容。

```json 回應範例 theme={null}
{
  "data": "",
  "status": {
    "code": "0",
    "message": "success",
    "datetime": "2022-07-01T10:13:54.920+08:00",
    "traceCode": "7cf25e1957cc47fe8e01f1a7c6d504d6"
  }
}
```


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