API 金鑰與驗證
每個 Connect API 呼叫都需要在 X-Api-Key 標頭中帶入 API 金鑰。公開訂位 API（/public/v1）不需要金鑰。
可公開金鑰與私密金鑰
您建立的每把 API 金鑰都是一組兩把：
| 部分 | 前綴 | 用於 | 存取範圍 |
|---|---|---|---|
| 可公開金鑰 | pk_ | 您的顧客 App 或網站 | 只限顧客能做的事：據點、登入、菜單、餐廳訂單、商品目錄、付款狀態，以及顧客自己的帳號。 |
| 私密金鑰 | cnct_ | 您自己的伺服器 | 所有端點，包括購物車、網路商店訂單和運送查詢。 |
請像對待密碼一樣保管私密金鑰。絕對不要把它放進 App 或網頁中。
以下端點需要私密金鑰。使用可公開金鑰會收到 403 PUBLISHABLE_KEY_NOT_ALLOWED：
GET /store/shipping/locationsGET /store/shipping/delivery-optionsPOST /store/orders/store/cart/…下的所有端點
金鑰屬於您的組織，可用於該組織任何啟用中的銷售通路。沒有分開的測試金鑰和正式金鑰。
建立金鑰
- 以 Admin 或 Manager 身分登入 my.conciar.com。Employee 無法管理金鑰。
- 開啟 Management → API Keys，點選 New API Key（清單為空時則點選 Create first key）。
- 輸入 Key Name（最多 100 個字元），然後點選 Create Key。
- 在 API Key Created 中，用 Copy 按鈕複製可公開金鑰和私密金鑰，然後點選 Done。
金鑰只會顯示一次
Conciar 只儲存每把金鑰的雜湊值。如果遺失金鑰，請建立新的金鑰。
清單會顯示每把金鑰的開頭字元、建立日期，以及最後使用時間。
更換或撤銷金鑰
Conciar 沒有「輪替」按鈕。若要更換金鑰：
- 建立新的金鑰。
- 把您的 App 或伺服器改用新金鑰。
- 撤銷或刪除舊金鑰。
Revoke 會立即停用金鑰；金鑰會以「Revoked」狀態留在清單中，且無法重新啟用。Delete 會把金鑰從清單中移除。兩者都作用於整組金鑰：撤銷可公開金鑰也會一併撤銷其私密金鑰。
從瀏覽器呼叫
Connect API 不會傳送 CORS 標頭，因此瀏覽器會封鎖從其他網域的 JavaScript 發出的呼叫。請從您的伺服器或原生 App 呼叫。網路商店可以透過自己的後端轉送呼叫，這樣也能讓私密金鑰不出現在網頁上。
錯誤
錯誤會以 JSON 回傳。請先檢查 HTTP 狀態碼。
| 狀態碼 | 內容 | 原因 |
|---|---|---|
| 401 | {"message": "API key required."} | 沒有 X-Api-Key 標頭。 |
| 401 | {"message": "Invalid or expired API key."} | 金鑰錯誤、已撤銷或已刪除。 |
| 401 | {"message": "Unauthenticated."} | 呼叫顧客端點時沒有有效的 bearer 權杖。 |
| 403 | {"status": false, "message": "PUBLISHABLE_KEY_NOT_ALLOWED"} | 此端點需要私密金鑰。 |
| 404 | {"message": "X-Sales-Channel header is required."} | /store/… 呼叫沒有 X-Sales-Channel 標頭。 |
| 404 | {"message": "…"} | 通路權杖無法辨識、未啟用，或屬於其他組織。 |
| 409 | {"status": false, "message": "IDEMPOTENCY_KEY_REUSED"} | 同一個 Idempotency-Key 被用於另一筆訂單，或第一筆訂單仍在建立中（IDEMPOTENCY_KEY_IN_PROGRESS）。 |
| 422 | {"message": "…", "errors": {…}} | 驗證失敗。其他請求錯誤會回傳 {"status": false, "message": "CODE"}。 |
| 429 | {"message": "Too Many Attempts."} | 超過速率限制。請等待 Retry-After 中的秒數。 |
| 503 | {"maintenance": true, "message": "…"} | 該銷售通路處於維護模式。 |
公開訂位 API 會回傳 {"status": false, "code": "…"}，例如 NOT_FOUND、UNAVAILABLE 或 INVALID。
速率限制
回應會帶有 X-RateLimit-Limit 和 X-RateLimit-Remaining。
Connect API
| 限制 | 計算單位 |
|---|---|
| 整個 API 每分鐘 300 個請求 | IP 位址 |
POST /app/init：每分鐘 30 次 | 金鑰 |
POST /store/cart/init：每分鐘 30 次 | 金鑰 |
| 其他購物車變更：每分鐘 120 次 | 金鑰 |
| 付款狀態：每分鐘 60 次 | 金鑰 |
| 下單、支付或取消餐廳訂單：每分鐘 10 次 | 金鑰 |
| 餐廳訂單狀態：每分鐘 30 次 | 金鑰 |
| 同一家店的所有餐廳訂單：每分鐘 60 筆新訂單，以及 120 次付款或取消呼叫 | 店家 |
register、otp/request 和 otp/resend：每分鐘 5 次 | IP 位址 |
otp/verify：每分鐘 20 次 | IP 位址 |
| 登入驗證碼：每分鐘 1 次、每小時 5 次 | 電子郵件地址 |
對可公開金鑰而言，「每把金鑰」是指每把金鑰加上每個 IP 位址，因此單一頻繁使用的 App 使用者不會耗盡其他人的額度。
太快要求新的登入驗證碼，會回傳 429 {"status": false, "message": "OTP_COOLDOWN", "retry_after": 42}。
公開訂位 API
| 限制 | 計算單位 |
|---|---|
| 每分鐘 120 次讀取，以及 10 次訂位或變更 | 餐廳加 IP 位址 |
| 禮物卡：每分鐘 60 次讀取和 6 次購買 | 餐廳加 IP 位址 |