API串接白名單設定介紹（需另外購買）
最後更新時間：2026/11/04
使用情境：
- 商家需要將 BVSHOP 與外部系統進行資料串接，可透過 Open API 提供授權存取方式。
- 透過 API Token 管理第三方系統的呼叫授權，並設定有效期限，降低長期使用相同憑證的風險。
- 搭配 IP 白名單，限制可呼叫 Open API 的來源 IP，提升串接安全性。
- 僅後台主帳號有編輯和瀏覽權限。
適用系統： ECPOS
小提示：點擊目錄中的章節標題，即可快速前往該章節閱讀。
一、Open API 功能介紹
什麼是 Open API？
Open API（開放應用程式介面）是一種讓不同系統之間進行資料交換與功能串接的方式。
商家可透過 BVSHOP Open API，依照開放的 API 端點及規格，建立外部系統與 BVSHOP 之間的整合。
此功能需額外付費才可以使用，如有需要可以諮詢業務或到群組詢問。
Open API 管理功能包含：
01｜API Token 管理
產生、保存及刪除 API Token，作為外部系統呼叫 API 時的授權憑證。
02｜Token 有效期限
可設定 Token 的有效期限，到期後自動失效，避免授權憑證無期限使用。
03｜IP 白名單限制
指定允許呼叫 Open API 的來源 IP，防止未列入白名單的 IP 存取 API。
注意：Open API 屬於系統串接功能，通常需要具備 API 開發或技術串接能力的人員協助操作。實際可讀取、寫入或操作的資料，應依 BVSHOP 提供的 API 規格為準。
二、API Token 產生與管理教學
使用 Open API 前，需先產生 API Token。Token 相當於系統串接時使用的授權憑證，外部系統必須攜帶有效的 Token，才能通過 Token 授權驗證。
STEP 01 ｜進入 Open API 管理頁面
至商家管理後台：
右上角可以看到API的購買效期。
STEP 02 ｜產生 API Token
在 Token 管理區域，新增一組 API Token，並依照頁面提供的設定項目，設定 Token 有效期限。
- 有效期限：可依照串接需求設定 Token 的使用期限（不限制、30天、60天、180天、360天）。
- 到期失效：超過設定期限後，該 Token 將自動失效。
- 數量限制：每間商店最多可保留 10 支 Token。
STEP 3 ｜複製並妥善保存 Token
Token 產生完成後，系統會顯示該組 Token 內容，請立即複製並保存至安全的位置。
⚠️ 重要提醒：Token 僅顯示一次
基於安全性考量，API Token 只會在產生當下顯示一次，關閉畫面後將無法再次查看完整內容。
若未保存或不慎遺失，請刪除原 Token，重新產生一組新的 Token。
STEP 4 ｜管理或刪除 Token
完成建立後，可透過 Token 管理列表查看及管理已產生的 Token。
若 Token 已不再使用、遺失或需要更換，請刪除舊 Token 後重新產生。
Token 管理注意事項：
- 每間商店最多可保留 10 支 Token。
- Token 到期後將自動失效，需重新產生。
- 刪除 Token 後，使用該 Token 的 API 呼叫將無法再通過授權驗證。
- Open API 服務停用或到期後，所有 Token 將無法使用。
三、IP 白名單設定教學
為提升 Open API 串接安全性，商家可透過 IP 白名單限制允許呼叫 API 的來源 IP。
設定 IP 白名單後，即使外部系統持有有效的 API Token，只要呼叫來源 IP 不在白名單內，仍無法成功呼叫 Open API。
STEP 1 ｜找到 IP 白名單設定區域
至商家管理後台：
進入 Open API 管理頁面後，找到下方的「IP 白名單」設定區域。
STEP 2 ｜設定允許呼叫的 IP
依照實際串接需求，將外部系統呼叫 API 時使用的來源 IP 加入白名單。
例如：若商家的外部系統使用固定 IP 對 BVSHOP 發送 API 請求，即可將該 IP 加入允許名單。
IP 白名單管理注意事項：
- 每間商店最多可保留 10 支 Token。
- Token 到期後將自動失效，需重新產生。
- 刪除 Token 後，使用該 Token 的 API 呼叫將無法再通過授權驗證。
- Open API 服務停用或到期後，所有 Token 將無法使用。
- 若要查自己的IP可以查看允許的IP欄位下方的文字（目前連線IP：XXX.XXX.XX）。
⚠️ 請留意 IP 白名單限制
IP 白名單並非留空就代表允許所有來源。若清空白名單，所有來源 IP 都會受到限制，請務必確認已加入需要使用的來源 IP。
STEP 3 ｜完成設定並測試串接
完成 IP 白名單設定後，請依照後台頁面的操作方式儲存或確認設定，再由外部系統進行 API 呼叫測試。
若無法成功呼叫，請優先確認：
- 外部系統實際呼叫來源 IP 是否已加入白名單。
- IP 白名單是否有正確保存。
- API Token 是否仍在有效期限內。
- API 請求是否正確攜帶授權標頭。
小提示：若外部系統使用雲端主機、動態 IP 或第三方自動化服務，建議先與串接服務商確認實際對外發送請求的 IP，避免因來源 IP 變動而無法正常呼叫 API。
四、API 授權驗證方式
BVSHOP Open API 使用 Bearer Token 作為授權驗證方式。外部系統呼叫 API 時，需在 HTTP 請求標頭（Header）中帶入已產生的 Token。
API 路徑：
HTTP 授權標頭格式：
請將 {Token} 替換成實際產生的 API Token，並由外部系統在發送 API 請求時帶入。
授權驗證需符合以下條件：
- 使用有效且未刪除的 API Token。
- Token 尚未超過設定的有效期限。
- Open API 服務仍在有效使用期間。
- 呼叫來源 IP 已列入 IP 白名單。
- 請求標頭已正確設定 Bearer Token。
完成上述設定後，即可依照 BVSHOP Open API 提供的端點、HTTP 方法及參數規格進行串接測試。
安全提醒：API Token 屬於重要的授權憑證，請勿公開於網站前端程式碼、公開文件、截圖或不受信任的第三方平台。建議交由技術人員以安全方式保存及管理。
五、常見問題 FAQ
Q1：我有購買API ，但系統後台看不到這個功能？
僅主帳號可以編輯／瀏覽此功能。
Q2：API Token 產生後，可以再次查看完整內容嗎？
不行。Token 僅會在產生當下顯示一次，請務必立即複製並妥善保存。若忘記或遺失，需刪除原 Token 後重新產生。
Q3：每間商店最多可以產生幾組 API Token？
每間商店最多可保留 10 支 Token。若已達數量上限，需先刪除不再使用的 Token，再產生新的 Token。
Q4：Token 到期後還能繼續使用嗎？
不行。Token 到達設定的有效期限後將自動失效，若需繼續使用 Open API，請重新產生 Token，並同步更新外部系統所使用的授權憑證。
Q5：如果 Open API 服務停用或到期，原本的 Token 還能使用嗎？
不行。當 Open API 服務停用或到期後，該商店所有 Token 都將無法使用，外部系統也無法再透過這些 Token 呼叫 Open API。
Q6：IP 白名單沒有設定任何 IP，是否代表所有來源都可以使用？
不是。當 IP 白名單為空白時，系統將限制所有來源 IP。若要正常呼叫 Open API，請先將需要使用的來源 IP 加入白名單。
Q7：已經有 API Token，為什麼還是無法成功串接？
請確認以下項目：
- Token 是否已過期或遭到刪除。
- Open API 服務是否仍在有效期間。
- Authorization Header 是否正確帶入 Bearer Token。
- 呼叫來源 IP 是否包含在 IP 白名單內。
- API 路徑、請求方法及參數是否符合串接規格。
Q8：可以讓不同的第三方系統使用不同的 Token 嗎？
可以。商家可依照實際串接需求建立多組 Token，並分別提供給不同的串接系統使用，但每間商店最多可保留 10 支 Token。
建議不要讓多個不相關的系統共用同一組憑證，以利後續管理及更換。
Q9：已設定 IP 白名單，是否就不需要 Token？
仍然需要，IP 白名單與 API Token 屬於不同的安全驗證機制。
IP 白名單用於限制可呼叫 API 的來源，Token 則用於驗證 API 呼叫的授權資格，兩者都需要符合設定條件。
Q10：如果外部系統的 IP 會變動，該如何設定？
建議先向第三方串接服務商確認實際使用的對外 IP。
若使用動態 IP，可評估改由具備固定對外 IP 的伺服器發送 API 請求，並將該 IP 加入白名單。
若來源 IP 發生變更，也需同步調整白名單設定。
串接前建議確認
若您需要委託第三方廠商進行串接，建議先確認 API 所支援的功能、資料存取範圍、串接方式及來源 IP，並由具備技術能力的人員協助設定與測試。
有任何問題請立即諮詢
