伺服器端呼叫 · 現有客戶

API 串接指南

現有客戶可管理金鑰並從伺服器端呼叫 API。新 API 銷售與新帳戶開通暫停。

API 可以做什麼

你的伺服器可以提交 RGB 數值比對相近顏色、搜尋色名，並查閱 161 種顏色的色庫與用量資訊。API 不提供完整色庫下載；瀏覽器也不能直接呼叫，因為不支援 CORS。

1. 下載並解壓縮工具

需要 Node.js 20 或更新版本。以下範例使用 POSIX 相容終端機，例如 macOS 或 Linux 終端機；尚未驗證 Windows 原生指令。ZIP 內含客戶端輔助指令，不含色庫資料或 API 金鑰，也不需要執行 npm install。

API 串接工具（ZIP）

將 ZIP 存到「下載項目」資料夾，解壓縮至私人工作資料夾，再於該資料夾執行：

mkdir -p ~/cathycolor-api
unzip ~/Downloads/key-delivery-tools.zip -d ~/cathycolor-api
cd ~/cathycolor-api
node --version

解壓縮後會看到 tools/api-key-delivery/。請將接入檔案留在網站公開目錄和 Git 原始碼目錄之外。

2. 產生公鑰檔與私鑰檔

如現有客戶需要 API 支援協助處理金鑰變更，公鑰檔可讓 CathyColor 加密 API 金鑰，只有配對的私鑰能解開。僅在支援人員提出要求時提供公鑰檔；私鑰留在自己掌控的裝置上。JWK 是一種 JSON 金鑰檔格式。

在解壓縮資料夾中執行：

umask 077
node tools/api-key-delivery/generate-keypair.mjs \
  --public-out ./customer.public.jwk \
  --private-out ./customer.private.jwk

工具會產生 3072 位元 RSA 金鑰組，使用 RSA-OAEP 與 SHA-256。兩個檔案的權限皆設為 0600，也不會覆寫已存在的檔案。

確認兩個檔案已建立：

ls -l ./customer.public.jwk ./customer.private.jwk

3. 現有客戶帳戶與金鑰支援

目前暫停新的 API 銷售與新客戶帳戶開通。現有客戶可繼續使用 API 和有效金鑰；續訂與支援服務持續。如需現有帳戶協助，請使用帳戶電子郵件地址聯絡支援團隊。 support@chinesecoloratlas.com

請提供帳戶電子郵件和相關的 X-Request-Id。僅在支援人員為現有帳戶金鑰變更提出要求時，才提供公鑰 JWK。

帳戶電子郵件: 現有帳戶的電子郵件地址
收件者: support@chinesecoloratlas.com
主旨: CathyColor API 支援
選用附件: 僅在支援人員為現有帳戶金鑰變更提出要求時附上 customer.public.jwk

請勿附上 customer.private.jwk、API 金鑰、完整 Authorization 標頭或付款卡資料。請勿在公開議題或聊天中貼上任何金鑰。

4. 讀取加密金鑰回執

如支援團隊為現有帳戶金鑰變更提供加密回執，請將檔案存成 provisioning-receipt.json，放在私人工作資料夾中。檔案內的 API 金鑰是加密資料，不是可直接讀取的明文。請勿修改回執，並妥善保管。

使用你的私鑰 JWK 執行解密工具：

umask 077
node tools/api-key-delivery/decrypt-envelope.mjs \
  --envelope ./provisioning-receipt.json \
  --private-key ./customer.private.jwk \
  --key-out ./cathycolor.api-key \
  --purpose cathycolor_api_key_provisioning

工具會驗證回執，並以 0600 權限將 API 金鑰寫入 cathycolor.api-key。它不會印出金鑰，也不會覆寫已存在的輸出檔。請將金鑰存入密鑰管理工具，絕不要傳給支援團隊。

5. 驗證金鑰（執行一次）

請使用發給你帳戶的有效金鑰。驗證會呼叫 /v1/library（不扣額度）並送出一次 /v1/search 請求（消耗 1 次搜尋額度）。重複執行會繼續消耗搜尋額度。

以下範例搜尋 red：

node tools/api-key-delivery/verify-key.mjs \
  --key-file ./cathycolor.api-key \
  --base-url https://api.chinesecoloratlas.com \
  --query red

成功時，library.status 與 search.status 都會回傳 HTTP 200。工具會捨棄回應本文，只顯示狀態和非敏感用量資訊。如狀態不同，請保留請求資訊並聯絡支援團隊，但不要傳送金鑰。

6. API 參考

請從你的後端向正式主機送出請求。將 API 金鑰保存在密鑰管理工具中；讀取金鑰時請關閉 Shell 追蹤，也不要匯出該變數。

讀取色庫與用量資訊

GET /v1/library — 只回傳發佈資訊，不消耗額度。
GET /v1/usage — 查閱目前 UTC 月份的兩種用量，不消耗額度。
POST /v1/match — 比對請求中的每個 RGB 顏色會消耗 1 個比對輸入。colors 接受 1–5 個 RGB 數值；選用的 top 範圍為 1–3。
GET /v1/search — 每次搜尋消耗 1 次搜尋額度。去除前後空白後，q 必須為 2–64 個字元；limit 上限為 10。

/v1/library 只回傳版本等發佈資訊，不會回傳顏色資料。比對與搜尋只回傳 161 種顏色中的有限結果；沒有完整色庫下載端點。

比對顏色與搜尋色名

set +x
API_BASE_URL="https://api.chinesecoloratlas.com"
API_KEY_FILE="./cathycolor.api-key"
API_KEY="$(tr -d '\n' < "$API_KEY_FILE")"

curl --silent --show-error --include \
  --header "Authorization: Bearer $API_KEY" \
  "$API_BASE_URL/v1/library"

curl --silent --show-error --include \
  --header "Authorization: Bearer $API_KEY" \
  "$API_BASE_URL/v1/usage"

MATCH_IDEMPOTENCY_KEY="match-$(node -e 'process.stdout.write(require("node:crypto").randomUUID())')"
curl --silent --show-error --include \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $MATCH_IDEMPOTENCY_KEY" \
  --data '{"colors":[{"r":12,"g":34,"b":56}],"top":2}' \
  "$API_BASE_URL/v1/match"

SEARCH_IDEMPOTENCY_KEY="search-$(node -e 'process.stdout.write(require("node:crypto").randomUUID())')"
curl --silent --show-error --include \
  --header "Authorization: Bearer $API_KEY" \
  --header "Idempotency-Key: $SEARCH_IDEMPOTENCY_KEY" \
  "$API_BASE_URL/v1/search?q=black&limit=3"

unset API_KEY

比對請求中的每個 RGB 顏色會消耗 1 個比對輸入。colors 接受 1–5 個 RGB 數值；選用的 top 範圍為 1–3。每次搜尋消耗 1 次搜尋額度。去除前後空白後，q 必須為 2–64 個字元；limit 上限為 10。

安全重試計量請求

POST /v1/match 和 GET /v1/search 必須帶上 Idempotency-Key（8–128 個 ASCII 英文字母、數字或 ., _, :、-）。每個新的邏輯請求都要產生一組鍵。請求逾時、回傳 5xx 或 request_in_progress 時，使用同一組鍵重試完全相同的請求；重播不會再次扣量。同一組鍵搭配不同請求資料會回傳 409 idempotency_conflict。只有真正要送出新請求時才產生新鍵。

常見錯誤

401 — API 金鑰遺漏、無效、已撤銷或過期。請檢查金鑰檔和 Authorization 標頭；聯絡支援時不要附上金鑰。
403 `account_unavailable` — 停止重試，聯絡支援團隊並提供請求 ID 和錯誤資訊。
409 — 解決冪等鍵衝突；若請求仍在處理中，請用相同的鍵和請求內容重試。
422 — 修正無效輸入，例如超出 0–255 範圍的 RGB 數值，或長度不符規定的搜尋詞。
429 `rate_limited` 表示觸發濫用防護，請遵循 `Retry-After`（通常為 60 秒）。`quota_exceeded` 表示月度硬性額度已用完，請遵循重試提示（通常為 86,400 秒）；這不代表額度會在該時間重設。只有額度錯誤會附上用量標頭。請勿平行重試或繞過限制。
500 或 503 — 若計量請求結果不確定，請使用相同冪等鍵重試完全相同的請求，並逐步拉長重試間隔。

需要協助？

聯絡支援時，請提供訂閱電子郵件、請求路徑、UTC 時間、HTTP 狀態碼、錯誤碼和 X-Request-Id。請勿傳送請求本文、RGB 數值、搜尋詞、私鑰、API 金鑰或 Authorization 標頭。 support@chinesecoloratlas.com

參考資料下載

以上步驟可直接在線上完成。需要離線閱讀時，請下載與目前頁面語言相同的指南。其他檔案分別用於以下開發工作：

離線 API 串接指南（Markdown）

可保存在本機的完整串接步驟與第一次呼叫說明。

OpenAPI 介面定義（YAML）

供工具讀取的端點、參數、回應和結構參考。

API 串接工具（ZIP）

用於產生金鑰組、解密回執和驗證有效金鑰的指令；不含色庫資料或 API 憑證。