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

# API 概览

> 端点、请求格式，以及如何读取 Fluz GraphQL API 的响应。

Fluz API 在每个环境中都是单一的 GraphQL 端点。本页是[GraphQL API 的工作原理](/concepts/graphql)的参考补充。

## 浏览参考

<CardGroup cols={2}>
  <Card title="查询（Queries）" icon="search" href="/api-reference/queries/approval-requests">
    读取操作 —— 获取钱包、交易、商户、卡片优惠和账户数据。
  </Card>

  <Card title="变更（Mutations）" icon="square-pen" href="/api-reference/mutations/add-authorized-user">
    写入操作 —— 发卡、转账、注册用户和企业，以及管理审批。
  </Card>
</CardGroup>

### 类型

<CardGroup cols={3}>
  <Card title="对象（Objects）" icon="box" href="/api-reference/types/account">
    查询与变更返回的响应结构。
  </Card>

  <Card title="输入对象（Input objects）" icon="text-cursor-input" href="/api-reference/types/add-bank-card-input">
    你传递给操作的参数。
  </Card>

  <Card title="枚举（Enums）" icon="list-ordered" href="/api-reference/types/account-type">
    固定的允许值集合，例如状态与卡网络。
  </Card>

  <Card title="联合（Unions）" icon="combine" href="/api-reference/types/stock-info-type">
    解析为多个对象类型之一的字段。
  </Card>

  <Card title="接口（Interfaces）" icon="plug" href="/api-reference/types/basic-user-cash-balance">
    由多个对象实现的共享字段契约。
  </Card>

  <Card title="标量（Scalars）" icon="hash" href="/api-reference/types/date-time">
    原始值，例如 DateTime 和 UUID。
  </Card>
</CardGroup>

### 约定

<CardGroup cols={2}>
  <Card title="认证（Authentication）" icon="key" href="/api-reference/authentication">
    Authorization 头、令牌端点，以及 OAuth 授权重定向。
  </Card>

  <Card title="错误（Errors）" icon="triangle-alert" href="/api-reference/errors">
    错误封装、域代码前缀，以及重试指南。
  </Card>

  <Card title="速率限制（Rate limits）" icon="gauge" href="/api-reference/rate-limits">
    各表面请求限制，以及 429 的含义。
  </Card>

  <Card title="分页（Pagination）" icon="chevrons-right" href="/api-reference/pagination">
    偏移量输入、页面大小上限，以及连接式响应。
  </Card>
</CardGroup>

<Card title="REST 端点" icon="route" horizontal href="/api-reference/rest/upload-sole-proprietorship-document">
  有一个操作在 GraphQL 之外 —— 独资注册所用的文件上传。
</Card>

## 端点

| 环境      | GraphQL 端点                                                       |
| ------- | ---------------------------------------------------------------- |
| Staging | `https://transactional-graph.staging.fluzapp.com/api/v1/graphql` |
| Live    | `https://transactional-graph.fluzapp.com/api/v1/graphql`         |

访问令牌通过 `generateUserAccessToken` 变更在同一端点签发，使用你的 API Key 授权 —— 参见[认证](/api-reference/authentication)。

## 请求头

| Header          | 是否必需 | 说明                                                                         |
| --------------- | ---- | -------------------------------------------------------------------------- |
| `Authorization` | 是    | `Bearer <access_token>`（调用 `generateUserAccessToken` 时为 `Basic <API_KEY>`） |
| `Content-Type`  | 是    | `application/json`                                                         |

## 响应封装

```json theme={null}
{
  "data": { ... },
  "errors": [ ... ]
}
```

* `data` —— 成功的负载（在错误时可能为部分数据）。
* `errors` —— 失败项数组，每项包含 `code`、`message` 和 `path`。

## 模式（Schema）

Staging 开放了自省，因此你可以直接将工具（Apollo Studio、GraphiQL、代码生成）指向它。在 live 环境，请向你的客户团队索取当前的 SDL。