HSystem
HSystemHalphas Technology
文件站
控制台

整合指南

從 curl 打通、Playground 模擬、到在本機開一個 HTML。全程不需要公開網域，也不需要先懂 OAuth。
難度 入門約 30 分鐘
你會做出什麼

終端機印出 {"ok":true}、Playground 看到真正的回應形狀、本機瀏覽器成功送出一次登入請求。

需要什麼憑證

免憑證公開端點，不需要 client_secret；若 body 需要 client_id，直接放在 body 即可。

做完會看到

curl 回 200；Playground 模擬模式吐出 JSON；本機 HTML 的請求得到 200 或你認得的 4xx（代表請求真的送到 API，而不是卡在本機）。

本篇大綱（9 節）
  1. 這一篇是給誰看的
  2. 先分清楚兩把鑰匙（30 秒）
  3. 第 1 步：先打通（2 分鐘）
  4. 第 2 步：在 Playground 看回應（5 分鐘）
  5. 第 3 步：建一個 App（5 分鐘）
  6. 第 4 步：在本機開一個 HTML（10 分鐘）
  7. 你剛剛完成了什麼
  8. 下一步
  9. 常見錯誤

這一篇是給誰看的

如果你符合下面任何一項，就從這裡開始：

  • 剛裝好編輯器，還沒接過任何 API。
  • 看過 API 文件，但不知道第一行指令要打什麼。
  • 想先確認「這東西到底能不能動」，再決定要不要花時間整合。

整篇只有四步，每一步都會給你「怎麼知道成功了」的判準。卡住就停在那一步，不要往下走。

先分清楚兩把鑰匙（30 秒）

文件裡會一直出現「免憑證」、「App 金鑰」、「Bearer」。先記這兩句就好：

你要做什麼需要什麼放在哪裡
你的伺服器代表 App 呼叫 API（寄信、開商品、查用戶）client_id ＋ client_secret（俗稱 App 金鑰）後端。永遠不要放進瀏覽器
代表某個已登入的使用者呼叫 API（讀他的資料）access_token（Bearer）該使用者的 session／你的後端
「免憑證」不等於「什麼都不用準備」：它只代表這一支不需要 client_secret。少數端點（例如登入）仍然要帶 client_id 說明「你是哪個 App」。看到免憑證時，先想「它還需要 client_id 嗎」，而不是「我什麼都不用填」。

另外，文件站只有三個地方需要記住：

  • Playground：不用任何金鑰就能看到「回應長什麼樣」。
  • API 參考：每一支的參數、欄位、錯誤碼。
  • 指南：也就是你現在看的這種，帶你做完一件事。

第 1 步：先打通（2 分鐘）

打開終端機（Windows：PowerShell；macOS：Terminal），貼上這一行：

curl -s https://api.hsystem.halphastech.com/api/public/ping

你應該看到：

{"ok":true,"plane":"public"}

看到 JSON 就代表：網路、DNS、TLS、API 本身全部正常。沒看到就先把網路／公司代理搞定，不要急著去找金鑰——這一步失敗跟你的 App 完全無關。

第 2 步：在 Playground 看回應（5 分鐘）

開 Playground，首頁會列出「快速開始」四支最常見的接口，第一張就是終端用戶登入。

  1. 點那張卡。
  2. 確認上方是「模擬」，按「發送（模擬）」。
  3. 下方「回應」分頁會出現 JSON。

模擬模式不會真的呼叫 API，它只回一份「與正式介面同形狀」的資料。用途是讓你現在就知道：

  • 成功時有哪些欄位（例如 access_token、expires_in）。
  • 失敗時錯誤長什麼樣（試著把 body 的 password 清空再送一次）。

這一刻你已經完成「打一次 API」了，只是還沒碰到真資料。

第 3 步：建一個 App（5 分鐘）

到開發者控制台註冊／登入，建一個 App。建完你會拿到兩樣東西：

  • client_id：公開識別碼，可以放在前端。
  • client_secret：密碼。只放後端；貼進 HTML 或 commit 進 git 就等於外洩。
想更細地了解這四種憑證分別放哪裡、外洩會怎樣，看憑證與認證。但現在先不用讀完，知道「secret 只放後端」就夠了。

第 4 步：在本機開一個 HTML（10 分鐘）

你不需要公開網域，也不需要架伺服器。在電腦上建一個資料夾，放兩個檔案：

index.html

<!DOCTYPE html>
<html lang="zh-Hant">
<head>
  <meta charset="UTF-8" />
  <title>第一次呼叫</title>
</head>
<body>
  <button id="send">送出登入請求</button>
  <pre id="out">尚未送出</pre>
  <script>
    const API = "https://api.hsystem.halphastech.com";
    const CLIENT_ID = "貼上你的 client_id";

    document.getElementById("send").addEventListener("click", async () => {
      const res = await fetch(`${API}/v1/auth/login`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          client_id: CLIENT_ID,
          email: "demo@example.com",
          password: "DemoPassw0rd!",
        }),
      });
      const data = await res.json();
      document.getElementById("out").textContent =
        `HTTP ${res.status}\n` + JSON.stringify(data, null, 2);
    });
  </script>
</body>
</html>

怎麼開它（三選一）：

  1. 直接雙擊 index.html，瀏覽器會用 file:// 開。多數情況可以直接送出請求。
  2. 用編輯器的 Live Server（VS Code／Cursor 的擴充功能）開啟，網址會是 http://localhost:5500。
  3. 有 Python 的話，在資料夾裡執行 python -m http.server 5500，再開 http://localhost:5500。

按下按鈕後，你應該看到 HTTP 400、HTTP 401 或 HTTP 200 的 JSON。看到任何一種 HTTP 狀態碼，都代表請求真的送到 API 了——這就是這一步的目標。（用假帳號登入本來就會失敗，重點是你已經打通。）

如果瀏覽器主控台顯示 CORS 或 Failed to fetch，那是「你的網域沒被允許」。把 http://localhost:5500 這類來源加進 App 的允許來源清單即可。

你剛剛完成了什麼

  • 用 curl 確認平台與網路正常。
  • 用 Playground 看過真實的回應形狀，不用先有金鑰。
  • 建了 App，知道 client_id 與 client_secret 的分工。
  • 從自己的電腦送出了一個真實的 HTTP 請求。

這四件事加起來，就是「接手一個 API」最花時間的部分。剩下的都是把參數換成你要的東西。

下一步

常見錯誤

  • curl 指令找不到：Windows 請用 PowerShell（內建 curl 別名）或安裝 Git for Windows 後用 Git Bash。
  • 複製到的網址是 localhost:8787：那是開發環境的內部位址。對外一律是 https://api.hsystem.halphastech.com，文件站的範例已全部改成正式網址。
  • 把 client_secret 寫進 HTML：等於公開你的 App 金鑰。前端只能用 client_id。
  • 以為 access_token 可以重複使用一輩子：它有 expires_in，過期要用 refresh token 換新的。

這篇用到的接口

參數、回應與錯誤碼看文件；想先看回應長什麼樣，直接開 Playground 的模擬模式。