> ## 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 调用

> 对预发布环境发起已认证的 GraphQL 请求，确认你的令牌可用。

拿到访问令牌后，你就可以开始调用 API 了。所有请求都发往同一个 GraphQL 端点，由令牌决定你操作的是哪个账户。

## 端点

| 环境 | 端点 |
| - | - |
| 预发布环境 | `https://transactional-graph.staging.fluzapp.com/api/v1/graphql` |
| 生产环境 | `https://transactional-graph.fluzapp.com/api/v1/graphql` |

没有带版本号的 REST 路径，也没有按功能划分的基础 URL。所有 query 和 mutation 都发送到同一个地址。

## 确认你的令牌是否可用

`getMerchants` 是端到端验证你的配置最简单的方式。它不读取任何敏感信息，不涉及资金转移，只需要 `LIST_OFFERS` 权限范围。

```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 { getMerchants(name: \"Burger King\") { name slug } }"}'
```

有效的令牌会返回该商户信息：

```json theme={null}
{
  "data": {
    "getMerchants": [
      {
        "name": "Burger King",
        "slug": "burger-king"
      }
    ]
  }
}
```

这一次响应就能同时确认四件事：你的端点是正确的，你的令牌是有效的，它携带了该查询所需的权限范围，并且它所对应的账户可以读取商户目录。

<Note>
  **空数组并不代表出错。** `getMerchants` 按名称过滤，因此如果某个商户不在预发布环境的目录中，会返回 `[]`，且没有 `errors` 字段。如果得到空结果，可以尝试不带 `name` 参数发起查询，看看预发布环境目前有哪些数据。
</Note>

## 出现问题时

<AccordionGroup>
  <Accordion title="401 未授权">
    该令牌在查询执行之前就被拒绝了。最常见的原因是凭证来自错误的环境：预发布环境和生产环境使用不同的应用。参见[如果令牌请求返回 401](/get-started/api-credentials#if-the-token-request-returns-401)。
  </Accordion>

  <Accordion title="AUTH-0031 权限不足">
    该令牌有效，但缺少该操作所需的权限范围。错误信息会指明具体缺少的权限范围，例如 `getMerchants requires LIST_OFFERS`。请重新签发一个添加了该权限范围的新令牌：权限范围在签发时就已固定，之后无法扩大。
  </Accordion>

  <Accordion title="GRAPHQL_VALIDATION_FAILED">
    该查询与 schema 不匹配，通常是引用了不存在的字段，或参数形式有误。响应会指出具体是哪个字段出了问题。可以在 [API 参考](/api-reference/overview)中查看该操作。

    当查询超过[查询成本限制](/concepts/rate-limits)时，会返回同样的错误代码，并带有 HTTP `400` 状态码。此时错误信息为 `Query Cost limit of 7000 exceeded`，请减少所选字段，或拆分查询。
  </Accordion>
</AccordionGroup>

## 接下来

<CardGroup cols={2}>
  <Card title="你的第一笔礼品卡购买" icon="gift" href="/quickstart/first-gift-card">
    存入资金、购买礼品卡，然后查看兑换详情，完成完整的标准流程。
  </Card>

  <Card title="创建并使用虚拟卡进行消费" icon="credit-card" href="/quickstart/create-and-spend-with-a-virtual-card">
    选择卡片项目，发行带有消费控制的卡片，并跟踪其使用情况。
  </Card>

  <Card title="幂等性" icon="shield-check" href="/concepts/idempotency">
    涉及资金转移的 mutation 需要传入 `idempotencyKey`。在进行第一次写入操作之前，请先阅读本文。
  </Card>

  <Card title="API 参考" icon="book" href="/api-reference/overview">
    涵盖所有的 query、mutation 和 type。
  </Card>
</CardGroup>