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

# 快速開始

> 從註冊帳號到發出第一個 API 請求，5 分鐘上手帳獸

## 開始使用帳獸

本指南將帶你完成從註冊到第一次 API 呼叫的完整流程。完成後，你將能夠透過 API 建立客戶與訂單，並在儀表板上看到即時數據。

<Steps>
  <Step title="註冊帳號">
    前往 [帳獸後台](https://app.zangsho.com) 註冊你的商家帳號。註冊完成後，系統會自動建立你的商家空間。
  </Step>

  <Step title="取得 API Token">
    登入後台後，前往 **金鑰管理** 頁面（側邊欄的 🔑 圖示）：

    1. 點擊**建立新金鑰**
    2. 輸入 Token 名稱（例如 `my-first-token`）
    3. 系統會產生一組 API Token

    <Warning>
      Token 只會顯示一次，請立即複製並妥善保存。如果遺失，你需要重新生成金鑰。
    </Warning>
  </Step>

  <Step title="驗證 Token">
    使用你取得的 Token 發出第一個 API 請求，確認認證成功：

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X GET https://api.zangsho.com/v1/customers \
        -H "Authorization: Bearer YOUR_API_TOKEN" \
        -H "Content-Type: application/json"
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://api.zangsho.com/v1/customers', {
        headers: {
          'Authorization': 'Bearer YOUR_API_TOKEN',
          'Content-Type': 'application/json'
        }
      });

      const data = await response.json();
      console.log(data);
      ```

      ```php PHP (Laravel) theme={null}
      $response = Http::withToken('YOUR_API_TOKEN')
          ->get('https://api.zangsho.com/v1/customers');

      $data = $response->json();
      ```
    </CodeGroup>

    如果回傳 `200 OK` 並包含空的 `data` 陣列，代表認證成功！
  </Step>

  <Step title="建立第一位客戶">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.zangsho.com/v1/customers \
        -H "Authorization: Bearer YOUR_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "email": "wang.xiaoming@example.com",
          "name": "王小明",
          "phone": "0912345678"
        }'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://api.zangsho.com/v1/customers', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_TOKEN',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          email: 'wang.xiaoming@example.com',
          name: '王小明',
          phone: '0912345678'
        })
      });

      const customer = await response.json();
      console.log('客戶 ID:', customer.data.id);
      ```

      ```php PHP (Laravel) theme={null}
      $response = Http::withToken('YOUR_API_TOKEN')
          ->post('https://api.zangsho.com/v1/customers', [
              'email' => 'wang.xiaoming@example.com',
              'name' => '王小明',
              'phone' => '0912345678',
          ]);

      $customerId = $response->json('data.id');
      ```
    </CodeGroup>
  </Step>

  <Step title="建立第一筆訂單">
    使用剛建立的客戶 ID 來建立訂單：

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.zangsho.com/v1/orders \
        -H "Authorization: Bearer YOUR_API_TOKEN" \
        -H "Content-Type: application/json" \
        -H "X-Idempotency-Key: order-001" \
        -d '{
          "order_no": "ORD-20260209-001",
          "customer_email": "wang.xiaoming@example.com",
          "customer_name": "王小明",
          "amount": "1990.00",
          "currency": "TWD",
          "status": "paid",
          "payment_method": "credit_card",
          "billing_cycle": "monthly",
          "paid_at": "2026-02-09T08:00:00Z"
        }'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://api.zangsho.com/v1/orders', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_TOKEN',
          'Content-Type': 'application/json',
          'X-Idempotency-Key': 'order-001'
        },
        body: JSON.stringify({
          order_no: 'ORD-20260209-001',
          customer_email: 'wang.xiaoming@example.com',
          customer_name: '王小明',
          amount: '1990.00',
          currency: 'TWD',
          status: 'paid',
          payment_method: 'credit_card',
          billing_cycle: 'monthly',
          paid_at: '2026-02-09T08:00:00Z'
        })
      });

      const order = await response.json();
      console.log('訂單編號:', order.data.order_no);
      ```

      ```php PHP (Laravel) theme={null}
      $response = Http::withToken('YOUR_API_TOKEN')
          ->withHeaders(['X-Idempotency-Key' => 'order-001'])
          ->post('https://api.zangsho.com/v1/orders', [
              'order_no' => 'ORD-20260209-001',
              'customer_email' => 'wang.xiaoming@example.com',
              'customer_name' => '王小明',
              'amount' => '1990.00',
              'currency' => 'TWD',
              'status' => 'paid',
              'payment_method' => 'credit_card',
              'billing_cycle' => 'monthly',
              'paid_at' => '2026-02-09T08:00:00Z',
          ]);
      ```
    </CodeGroup>

    <Tip>
      使用 `X-Idempotency-Key` 標頭可以避免重複建立訂單，即使網路中斷導致重試也不會產生重複資料。
    </Tip>
  </Step>

  <Step title="在儀表板查看結果">
    回到 [帳獸後台](https://app.zangsho.com)，你應該可以在儀表板上看到：

    * **Revenue** 卡片顯示 NT\$1,990
    * **Orders** 卡片顯示 1 筆訂單
    * **Customers** 卡片顯示 1 位客戶
    * **即時交易活動流**中出現你剛建立的訂單
  </Step>
</Steps>

## 下一步

<CardGroup cols={2}>
  <Card title="核心概念" icon="book-open" href="/concepts/customers">
    深入了解客戶、訂單、訂閱的資料模型。
  </Card>

  <Card title="資料匯入" icon="upload" href="/guides/data-import">
    使用批次 API 匯入歷史資料。
  </Card>

  <Card title="Webhook 設定" icon="webhook" href="/guides/webhooks">
    設定自動化通知，串接你的工作流。
  </Card>

  <Card title="金流整合" icon="credit-card" href="/integrations/newebpay">
    接入藍新或綠界金流，自動接收付款通知。
  </Card>
</CardGroup>