Workiva 支援中心

本指南逐步引導您完成使用 OpenAPI 規範將 Workiva API 集合匯入 Postman 、配置環境變數以及端到端驗證要求的流程。

必要條件

開始之前，請確保您具有以下內容：

• 已安裝 Postman (建議使用版本 10+)
• 有效的 Workiva 用戶端 ID 和 用戶端密碼
• 透過 Workiva 開發人員入口網站存取 Workiva OpenAPI .yaml 檔案
• 了解您正在工作的 Workiva 環境： 應用程式、 歐盟或 亞太地區

背景

Workiva API 以 OpenAPI (.yaml) 格式發布。這些規格說明可以直接匯入 Postman 中，從而能夠加速開發、測試與整合工作流程，而無需手動建構要求。

第 1 步：匯入 Workiva API 集合

1. 巡覽至 Workiva 平台代碼產生 頁面。
2. 下載 OpenAPI .yaml 檔案。 
   
3. 開啟 Postman，選取 Import，然後上傳下載的檔案。 
   
4. 確認標題為 Workiva API 的新集合出現在 Postman 中。 
   

步驟 2：設定您的環境

在 Postman 中，開啟 Environments 索引標籤並建立新環境。出於測試目的，本指南使用名為<WorkspaceName>_Workiva_API。

建議： 使用一致的命名慣例，例如 OrganizationName_WorkspaceName ，以清楚地區分不同 Workiva 工作區的變數。

使用 Current Value 資料欄新增以下變數，然後按一下 Save。

📘 如何在 Postman 中使用環境變數

步驟 3：設定 OAuth2 – 擷取權杖

1. 選取 Workiva API 集合。
2. 設定授權以使用 {{access_token}} 變數。
3. 選取 Scripts 索引標籤。

4. 新增以下指令碼至 Pre-request 區段。 

   對於 2026 Platform API，每個要求都需要 X-Version 標頭。此指令碼可確保標頭在整個集合中套用的一致性，符合 Workiva 的 2026 API 版本要求。

   注意： 此要求目前僅適用於平台 API。

   // 新增或更新 X-Version 標頭 pm.request.headers.upsert({ key: "X-Version", value: pm.environment.get("api_version") });

   

    

5. 選擇變數 索引標籤。
6. 更新baseUrl 變數，以使用{{environment}} 來取代硬體編碼的網域。

Original:
https://api.app.wdesk.com/iam/v1

更新：
https://api.{{environment}}.wdesk.com/iam/v1

步驟 4：儲存存取權杖

1. 從 Retrieve a token， 選擇Scripts 標籤，並將下列程式碼新增至Post-request 區段。

   pm.test("Status code is 200",function () { pm.response.to.have.status(200); }); pm.test("Save access token to environment variable",function () {var jsonData = pm.response.json(); pm.environment . set("access_token", jsonData.access_token); })；

   

2. 傳送請求。您應該會收到200 OK 回應，您的access_token 會自動儲存。

步驟 5：匯入並配置 Wdata 和 Chains API 集合

1. 前往 Wdata 程式碼產生 頁面。
2. 下載 .yaml 檔案並將其匯入 Postman（按照 步驟 1：匯入 Workiva API 集合中概述的步驟進行操作）。注意： .yaml 檔案名稱可能與 Workiva API 集合相同。
3. 在 Wdata 集合中：
   • 將授權類型設定為Bearer Token。

   • 使用{{access_token}} 作為令牌值。

     

   • 在變數 索引標籤中，更新baseUrl 變數，以使用{{environment}} 代替硬編碼網域。這樣可以更容易地在不同的環境中切換，例如app,eu, 或apac 。
   • 確保每個請求都設定為Inherit auth from parent。
   • 對 Chains API Collection重複上述相同步驟，確保以相同方式配置授權設定和 baseUrl 變數。

疑難排解

• 確保您引用了正確的環境 。如果集合預設為無環境，請將它切換到您指定的環境 。
• 確認baseUrl 變數在您的環境和集合設定中是一致的。
• 請確定將baseUrl 集合變數設定為使用{{environment}} ；否則，您的請求可能會失敗。
• 如果您的要求傳回 401 或空白回應，請重新檢查您的用戶端 ID、用戶端密碼、API_version 和環境值是否正確。