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

# GraphQL API 的運作方式

> 單一端點、查詢與變更，以及你可以從每次呼叫預期的回應格式。

Fluz 在每個環境中只提供一個 GraphQL 端點。沒有版本化的 REST 路徑，也沒有依功能劃分的基底 URL——你只需將查詢或變更送到 `/graphql`，而權杖會決定你正在操作哪個帳戶。

## 端點

| 環境      | URL                                                              |
| ------- | ---------------------------------------------------------------- |
| Staging | `https://transactional-graph.staging.fluzapp.com/api/v1/graphql` |
| Live    | `https://transactional-graph.fluzapp.com/api/v1/graphql`         |

存取權杖是由位於 `https://oauth-service.fluzapp.com` 的獨立 OAuth 服務簽發。

## 請求結構

```bash theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetWallet($id: ID!) { wallet(id: $id) { balance { value currency } } }",
    "variables": { "id": "wal_01H..." }
  }'
```

* **`query`** — GraphQL 文件。使用具名操作（`query GetWallet`）以取得更佳的日誌紀錄。
* **`variables`** — 型別化的輸入，將值與查詢字串分離。
* **`operationName`** — 選用；當一個文件定義多個操作時很有用。

## Queries 與 mutations

* **Queries** 為唯讀（`viewer`、`wallet`、`transactions`）。
* **Mutations** 會改變狀態（`createVirtualCard`、`purchaseGiftCard`、`depositCashBalance`、`createTransfer`）。

涉及資金移動的 mutations 使用請求去重機制——參見 [Idempotency](/concepts/idempotency)。

## 回應格式

GraphQL 一律以 HTTP 200 回傳，並包含 `data` / `errors` 外層結構：

```json theme={null}
{
  "data": { "wallet": { "balance": { "value": 12500, "currency": "USD" } } },
  "errors": null,
  "extensions": { "requestId": "req_01H..." }
}
```

失敗時，`data` 可能為 `null`，而 `errors` 會描述出錯原因——包含可供程式分支判斷的機器可讀 `code`。請參見 [Errors](/api-reference/errors)。

## 自省與綱要（Schema）

在 staging 中啟用了自省，你可以將 Apollo Studio 或 GraphiQL 等工具指向該端點。在 live 中，自省已停用；請改用 [API reference](/api-reference/overview) 提供的已發佈綱要。

## 下一步

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/concepts/authentication">
    `Authorization` 標頭中的權杖如何被簽發——針對你的帳戶或客戶的帳戶。
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/api-reference/errors">
    `errors` 陣列包含哪些內容以及如何依錯誤代碼進行分支。
  </Card>
</CardGroup>