> ## 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 端點——由權杖決定你正在操作的是哪個帳戶。

## 端點

| Environment | Endpoint |
| - | - |
| Staging | `https://transactional-graph.staging.fluzapp.com/api/v1/graphql` |
| Live | `https://transactional-graph.fluzapp.com/api/v1/graphql` |

沒有版本化的 REST 路徑，也沒有依功能區分的基礎 URL。你會將每一個查詢與變更操作都送到同一個位址。

## 確認你的權杖可以運作

`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 Unauthorized">
    權杖在查詢執行前就被拒絕。最常見的原因是憑證來自錯誤的環境——測試環境與正式環境使用各自獨立的應用程式。請參閱[如果權杖請求回傳 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">
    存入資金、購買禮品卡，並揭露其兌換細節——完整的 happy path。
  </Card>

  <Card title="建立虛擬卡並開始消費" icon="credit-card" href="/quickstart/create-and-spend-with-a-virtual-card">
    選擇卡片方案、發行具備消費控管的卡片，並追蹤其活動。
  </Card>

  <Card title="冪等性" icon="shield-check" href="/concepts/idempotency">
    搬移資金的變更操作都需要 `idempotencyKey`。第一次寫入前，請先閱讀本文。
  </Card>

  <Card title="API 參考" icon="book" href="/api-reference/overview">
    每一個查詢、變更操作與型別。
  </Card>
</CardGroup>