Workiva Support Center

本指南将引导您使用 OpenAPI 规范将 Workiva API 集合导入到 Postman中 ，配置环境变量，并端到端验证请求。

先决条件

开始之前，请确保您已准备好以下物品：

• Postman 已安装（建议版本 10 或更高）
• 有效的 Workiva 客户 端ID 和 客户端密钥
• 通过 Workiva开发者门户访问 Workiva OpenAPI .yaml 文件
• 了解您正在使用的 Workiva 环境： app、 eu或 apac

背景

Workiva API 以 OpenAPI (.yaml) 格式发布。这些规范可以直接导入到 Postman 中，无需手动构建请求即可加快开发、测试和集成工作流程。

步骤 1：导入 Workiva API 集合

1. 导航至 Workiva 平台代码生成 页面。
2. 下载 OpenAPI .yaml 文件。 
   
3. 打开Postman ，选择 导入，然后上传下载的文件。 
   
4. 确认 Postman 中是否出现名为 Workiva API 的新集合。 
   

步骤 2：设置环境

在 Postman 中，打开 环境 选项卡并创建一个新环境。为了进行测试，本指南使用一个名为“<WorkspaceName> _Workiva_API。

建议：使用一致的命名约定 ， 例如OrganizationName_WorkspaceName ，以便清楚地区分不同 Workiva 工作区中的变量。

使用 当前值 列添加以下变量，然后单击 保存。

📘 如何在 Postman 中使用环境变量

步骤 3：配置 OAuth2 – 获取令牌

1. 选择 Workiva API 集合。
2. 设置授权以使用 {{access_token}} 变量。
3. 选择 脚本 选项卡。

4. 将以下脚本添加到 预请求 部分。 

   对于 2026 平台 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}} 而不是硬编码的域名。

原文：
https://api.app.wdesk.com/iam/v1

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

步骤 4：保存访问令牌

1. 从 获取令牌， 选择 脚本 选项卡，并将以下代码添加到 请求后 部分。

   pm.test("状态码为 200", function () { pm.response.to.have.status(200); }); pm.test("将访问令牌保存到环境变量", 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等环境之间切换。
   • 确保每个请求都设置为 从父级继承身份验证。
   • 对 Chains API 集合重复上述步骤，确保授权设置和 baseUrl 变量以相同的方式配置。

疑难解答

• 请确保您引用的是正确的 环境。如果集合默认为“无环境”，则将其切换为 您指定的环境。
• 请确认 baseUrl 变量在您的环境和集合设置中保持一致。
• 请确保将 baseUrl 集合变量设置为使用 {{environment}}；否则，您的请求可能会失败。
• 如果您的请求返回 401 或空白响应，请重新检查您的客户端 ID、客户端密钥、API_version 和环境值是否正确。