> ## 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`** — 可选，当一个文档定义多个操作时很有用。

## 查询 vs. 变更

* **查询（Queries）** 是只读的（`viewer`、`wallet`、`transactions`）。
* **变更（Mutations）** 会改变状态（`createVirtualCard`、`purchaseGiftCard`、`depositCashBalance`、`createTransfer`）。

涉及资金流动的变更使用请求去重——参见 [幂等性](/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`。参见 [错误](/api-reference/errors)。

## 内省与模式

在 Staging 环境启用了内省，你可以将 Apollo Studio 或 GraphiQL 等工具指向该端点。在 Live 环境中，内省被禁用；请改用来自 [API 参考](/api-reference/overview) 的已发布模式。

## 后续步骤

<CardGroup cols={2}>
  <Card title="认证" icon="key" href="/concepts/authentication">
    `Authorization` 头中的令牌如何被签发——用于你的账户或客户的账户。
  </Card>

  <Card title="错误" icon="triangle-alert" href="/api-reference/errors">
    `errors` 数组包含什么，以及如何基于错误码进行分支处理。
  </Card>
</CardGroup>