聚石塔 Postman 接口使用指南

导入 Schema

下载 聚石塔.postman_collection.json，导入到 Postman 中：

打开 Postman，单击Import按钮，在弹出对话框中选择File标签页，单击Upload Files。

选择已下载的聚石塔.postman_collection.json文件，单击Import完成导入。

导入完成后，目录结构如下：

左侧栏显示聚石塔集合，包含登录相关、用户同步相关、自适应二次认证相关等文件夹，以及初始化变量和获取 AccessToken等请求。

添加一个环境，然后切换到该环境：

单击 Postman 右上角环境区域的Add按钮创建新环境。

将新建的环境命名并在环境下拉框中切换至该环境。

至此，准备工作已经完成，接下来开始调试接口。请按顺序执行接口，接口之间存在依赖关系，先执行的接口为后执行的接口提供环境变量。

初始化变量

首先，需要执行【初始化变量】：

该请求的 Pre-request Script 标签页包含初始化脚本，自动设置 host、clientId、clientSecret、username、password、phoneNumber、merchantName、ivsAppKey 等环境变量。单击 Send 执行。

url 可以任意填写，目的是为了能够执行脚本。

如果客户尚未购买实例，需要先对接，IDaaS 可以提供测试服务器供客户提前对接。

接下来介绍如何获取以上变量值。

host

登录 IDaaS 控制台，在实例列表中查看实例开放接口域名列。

host 即 IDaaS 控制台实例列表中的“实例开放接口域名”，特别注意聚石塔的版本为 idaas-jst-xxx，如果不是请立即联系 IDaaS。

clientId 和 clientSecret

在 IDaaS 控制台的应用列表页面，选择目标应用，在页面底部的 API 区域查看 API Key 和 API Secret。

API Key为 clientId， API Secret为 clientSecret。

username、password、phoneNumber

接下来会使用这里的用户信息调用接口创建账号。用户信息可以自行修改，但需要满足约束条件。如果提示不满足密码策略，可以在 IDaaS 控制台调整：

在 IDaaS 控制台的安全设置页面，找到密码策略区域，根据需要调整规则类型及密码复杂度等要求。

merchantName

在淘宝店铺主页中，查看掌柜字段的值。

商户名称即淘宝店铺主页中的掌柜字段值，务必传对，否则无法计分。

更准确的是从接口中获取，参考 接口文档：

在接口返回参数中，找到 seller_user_nick 字段，该值即为商户名称。

两者值若不同，以接口为准。

ivsAppKey

参考 接口文档：

在淘宝开放平台的应用管理页面，找到 APP 证书区域，查看 App Key。

ivsAppKey 即淘宝开放平台应用管理页面中的 App Key，务必传对，否则无法计分。

创建用户流程

获取 AccessToken

在 Postman 中打开获取 AccessToken请求（POST {{host}}/oauth/token），Authorization 标签页中认证类型为 Bearer Token，单击 Send 发送请求。

获取 AccessToken ，为后续接口提供认证需要的 token：

该请求的 Tests 标签页包含脚本，发送成功后自动将响应中的 access_token 写入环境变量 accessToken。

组织 / 查询

在 Postman 中打开组织/查询请求（GET 方式），单击 Send 发送请求。Tests 脚本自动将组织 ID 写入环境变量。

查询组织，将最后一个组织添加到环境变量，创建用户时需要设置所属的组织。

用户 / 新建

在 Postman 中打开用户/新建请求（POST 方式），Body 标签页中包含 source、displayName、username、phoneNumber、password 等用户信息字段，单击 Send 发送请求创建用户。

新建用户时，会使用上一步查询出来的组织。创建用户后，从 IDaaS 控制台开启用户二次认证：

在 IDaaS 控制台的账户管理页面，找到新建的用户，开启二次认证开关。

短信二次认证流程

登录

登录时，会自动计算签名并加密密码。

登录完成后，如果开启了二次认证，会自动添加 fid 环境变量。

短信二次认证 - 发送验证码

该请求的 Body 中包含 fid 和 authenticatorType 字段，单击 Send 发送请求。

使用登录返回的 fid，发送短信二次认证验证码。

发送二次认证验证码成功后，更新 fid。

短信二次认证 - 校验验证码

该请求的 Body 中包含 fid、authenticatorType 和 code 等字段。

使用上一步返回的 fid，校验短信二次认证验证码。code 传入手机上收到的验证码，如果没有收到验证码，请在 IDaaS 控制台通过日志核实是否发送成功：

在 IDaaS 控制台左侧导航中选择审计 > 操作日志，筛选操作类型为短信，查看日志内容确认验证码是否发送成功。

OTP 绑定流程

登录

同上。

OTP - 获取绑定二维码

在 Postman 中打开该请求，Body 中包含 fid 和 username 字段，单击 Send。响应中返回 base64QRCode 字段。

获取成功自动设置 fid 环境变量。

使用 Base64 图片转换网站 https://tool.chinaz.com/tools/imgtobase/ 展示 OTP 绑定二维码，拷贝base64QRCode的值，添加前缀 data:image/png;base64,。

将拼接后的字符串粘贴到网站输入框中，页面会生成可供扫描的二维码图片。

使用 Google 身份认证器（或其他认证器），扫描二维码，获取 OTP Code。

OTP - 绑定

在 Postman 中打开该请求，Body 中已填入 fid 和 username，需手动填入 otp 字段的值。

输入上一步中获取的 OTP Code。如果上一步操作时间过长，会导致 fid 失效，需要重新登录。登录后调用【OTP - 获取绑定二维码】，因为之前已经绑定过了，现在直接从认证器获取 OTP Code 调用【OTP - 绑定】。

OTP 二次认证流程

登录

同上。

OTP - 校验

该请求的 Body 中包含 fid、secondFactor（值为 OTP）和 otp 字段。

输入从认证器中获取的 OTP Code。