跳轉到

驗證與授權

除了 /health，每個請求都必須在 x-functions-key header 帶上 API 金鑰。

1. 取得 API 金鑰

總部會為每個合作夥伴、每個環境（測試／正式）各核發一把 API 金鑰，由總部窗口以安全管道提供。

Warning

API 金鑰等同密碼。不得寫進程式碼、版本控制、log、Email 或聊天訊息；請放在密鑰管理工具或環境變數。

2. 呼叫 API

在 x-functions-key header 帶入金鑰：

POST https://func-posingest-dev.azurewebsites.net/pos/v1/trade-records
Content-Type: application/json
x-functions-key: {api_key}

curl -H "x-functions-key: $API_KEY" \
  https://func-posingest-dev.azurewebsites.net/pos/v1/reference/transaction-types

未帶金鑰或金鑰錯誤，回 401 Unauthorized。

3. 金鑰更換

  • 總部可能更換金鑰（例如疑似外流時），會事先通知，並以安全管道提供新金鑰。
  • 若懷疑金鑰外流，請立即通知總部更換。

合作夥伴與門市授權

  • 合作夥伴身分由 API 金鑰決定，不需自行帶入 partner_id。
  • 只能推送／查詢總部登記給您的門市；其他 store_id 回 403 STORE_NOT_ALLOWED。新增門市請先請總部登記。
  • 合作夥伴狀態非啟用時，所有請求回 403 PARTNER_INACTIVE。

預計變更

總部之後預計改用 OAuth 2.0（Microsoft Entra ID client credentials）。屆時會提前通知，過渡期間 API 金鑰仍可使用。