上傳與讀取檔案

這篇會帶你做到什麼

上傳一個檔案，拿到它的 path；接著決定「誰可以讀」：

• public：任何人拿到網址就能讀，適合商品圖片、公開 PDF。
• gated：要帶憑證才讀得到，適合購買後才開放的內容。

先打這 3 支就好

GET /v1/files 是列出你目前有哪些檔案路徑，卡住時先打它看資料在不在。

第 1 步：上傳（App 金鑰）

curl -s -X POST https://api.hsystem.halphastech.com/v1/files \
  -H "Authorization: Basic $(printf '%s:%s' "$HS_CLIENT_ID" "$HS_CLIENT_SECRET" | base64)" \
  -F "file=@./cover.png" \
  -F "path=products/cover.png"

回應會給你這筆檔案的 path、size 與 access。上傳一定要用 App 金鑰（終端用戶 token 不行），因為這是「你的 App 在放檔案」。

不想用 multipart 的話，可以改成 raw body 並在 header 帶 X-File-Path: products/cover.png。

第 2 步：確認 meta

curl -s "https://api.hsystem.halphastech.com/v1/files/by-path?path=products/cover.png" \
  -H "Authorization: Basic $HS_BASIC"

這裡看得到 access、size、expiresAt。如果 access 是 gated，第 3 步的公開網址會讀不到——那是預期行為。

第 3 步：讀取

public 檔案：直接組網址，不用憑證。

https://api.hsystem.halphastech.com/v1/files/public/{你的 appId}/products/cover.png

gated 檔案：呼叫 GET /v1/files/content?path=...，帶使用者 Bearer 或 App 金鑰。伺服器會依 access 設定決定放行或拒絕。

要改權限（例如從 gated 改成 public），用同一個 path 呼叫 PATCH /v1/files/by-path。

什麼時候該用 gated

• 付費內容、課程影片、發票 PDF。
• 使用者上傳的私人檔案。

購買後才開放的檔案還多一層：POST /v1/files/download-tokens 申請一次性下載憑證，再 GET /v1/files/download 換檔案；憑證用過即失效，適合不能外流的本體。

常見錯誤

• 用終端用戶 token 上傳：會失敗。上傳只認 App 金鑰。
• public 網址 404：先確認 access 是 public、且沒有過期；再確認 appId 沒填錯（是 App ID，不是 client_id）。
• 把 gated 檔案網址貼給使用者：他會讀不到；要給的是「你的後端代理」或一次性下載憑證。
• path 帶開頭的斜線：/products/cover.png 與 products/cover.png 是不同 path，統一用不帶斜線的形式。