让gpt帮我完成接口文档
2026-03-19
我问：
这是我的controller：
/**
* 对方批量校验用户，并返回我方用户唯一ID列表
*
* 请求体示例：
* {
* "tenantId": "93xxxxx",
* "creditCode": "913xxxxxxxxxxxxxxx",
* "userList": [
* {
* "organizationList": "xxx公司/xx部门/xx一部",
* "userName": "江天",
* "mobile": "18310425848",
* "nmUserId": "xxxxxx123456"
* }
* ]
* }
*/
public function actionVerifyPartnerUsers()
{
$request = Yii::$app->request;
try {
$service = new PsassUserService();
$result = $service->handleVerifyPartnerUsers($request);
return [
'code' => 0,
'message' => 'success',
'data' => $result,
];
} catch (\Exception $e) {
return [
'code' => 1,
'message' => $e->getMessage(),
'data' => [],
];
}
}
以下是我们约定的参数和返回格式：
{
"tenantId": "93xxxxx",
"creditCode": "913xxxxxxxxxxxxxxx",
userList:[ {
"organizationList": "xxx公司/xx部门/xx一部",
"userName": "江天",
"mobile": "18310425848",
"nmUserId":"xxxxxx123456"
},{
"organizationList": "xxx公司/xx部门/xx一部",
"userName": "江天",
"mobile": "18310425848",
"nmUserId":"xxxxxx123456"
}]
}
这个参数也是用base64编码后，以参数名encryption传，post方法。接口名为/v2/business/nuoming/check-valid
返回数据格式：
{
"tenantId": "93xxxxx",
"creditCode": "913xxxxxxxxxxxxxxx",
userList:[ {
"智评云唯一id"：xxxx654321”
"nmUserId":"xxxxxx123456"
},{
"智评云唯一id"：xxxx654321
"nmUserId":"xxxxxx123456"
}]
}，这一部分以base64方式编码后放到下面这个结构的items里：
[
'code' => 0,
'message' => 'success',
'data' => [
'items' => 'W3sienB5VXNlcklkIjozNTAzNDU1MzQ4NjY3MTg3Miwibm1Vc2VySWQiOiJubV91c2VyXzAwMDEyMyJ9XQ==',
'_links' => [
'self' => [
'href' => '/v1/psass/verify-partner-users?page=1&size=100',
],
'first' => [
'href' => '/v1/psass/verify-partner-users?page=1&size=100',
],
'last' => [
'href' => '/v1/psass/verify-partner-users?page=1&size=100',
],
],
'_meta' => [
'totalCount' => 1,
'pageCount' => 1,
'currentPage' => 1,
'perPage' => 100,
],
],
]
现在，把前面咱们写的这个接口写一个接口文档。格式如下：
获取 Token
允许已完成对接配置的第三方系统通过 SSO Token Exchange 方式获取我方 access_token。
● URL：/v2/oauth/nuoming/getTokenBySso
● Method：POST
● 需要登录：否
● 需要鉴权：否
请求参数
参数 类型 约束
encryption String 必填，JWT 加密串，header.payload.signature
💡 注意，encryption 解密后的载荷中必须包含以下字段：thirdparty、module、tenantId、creditCode、expireTime、nonce。缺少任一字段都将校验失败。
请求示例
可以通过表单方式提交请求参数。
{
"encryption": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxxxxxxxxxxxxxxxxxxxxxx.yyyyyyyyyyyyyyyyyyyyyyyyy"
}
encryption 对应的 JWT 载荷示例：
{
"thirdparty": "nuoming",
"module": "SELFBUILT",
"tenantId": "A1",
"creditCode": "91310112071234567X",
"expireTime": 1773649727,
"nonce": "nm_test_20260316_ab12cd34"
}
成功响应
条件：请求参数合法，企业配置有效，JWT 校验通过，nonce 未重复，对方 verify 接口校验通过，系统成功签发 access_token。
状态码：200 OK
响应示例：
{
"code": 0,
"message": "success",
"data": {
"access_token": "3f8d0a7e1c9b5f6a2d4e8c1b7a9d0f2c6e4a8b1d3f5c7e9a1b2d4f6c8e0a9b1d5f7c9e1a3b5d7f9c2e4a6b8d0f1c3e5f7a9b1d3c5e7f9a2b4d6c8e0f2a4",
"expires_in": 7200
}
}
错误响应
条件：请求参数缺失、JWT 解析失败、企业未配置、企业状态不可用、JWT 过期、nonce 重复、对方 verify 失败、系统未签发 token 等。
状态码：200 OK
响应示例：
{
"code": 0,
"message": "A1201|JWT已过期",
"data": []
}
错误码
错误码 含义
A0000 通用成功
A1001 缺少 encryption 参数
A1002 JWT解析失败
A1003 JWT缺少必要字段
A1004 expireTime无效
A1101 企业未配置
A1102 企业已停用
A1103 企业未到生效时间
A1104 企业已过期
A1105 未配置对方SSO基础地址
A1201 JWT已过期
A1202 JWT有效期超过允许上限
A1203 请求重复
A1301 请求对方 verify 接口失败
A1302 第三方 verify 失败
A1303 第三方 verify 响应格式异常
A1401 未签发token
A1402 access_token签发成功
A1403 换token成功
A9999 系统异常
注意事项
access_token 为系统签发的访问令牌，当前设计为 128 位长度字符串，需在有效期内使用，过期后需要重新调用本接口获取。
💡 nonce 仅允许在短时间窗口内使用一次，用于防重放攻击；同一个 nonce 重复提交会直接失败。
💡 expireTime 为秒级时间戳，若早于当前允许时间窗口，或超过系统允许的最大有效期，都会被拒绝。
💡 接口成功返回并不代表仅完成本地解析，还包含了对第三方 verify 的联动校验；只有全部通过后才会签发最终 access_token。
AI答：
对方批量校验用户
允许已完成对接配置的第三方系统，通过批量传入人员信息的方式，校验这些人员是否为我方系统中的有效用户，并返回校验通过人员对应的智评云唯一 ID 列表。
● URL：/v2/business/nuoming/check-valid
● Method：POST
● 需要登录：否
● 需要鉴权：否
请求参数
参数 类型 约束
encryption String 必填，base64 编码后的 JSON 字符串
💡 注意，encryption 解码后的载荷中必须包含以下字段：tenantId、creditCode、userList。
💡 其中 tenantId 为第三方系统侧企业标识，仅作为原始请求信息透传与记录，不作为我方业务校验依据。
💡 我方实际校验时，用户仅使用 userName、mobile 两个字段进行匹配；企业归属使用 creditCode 进行校验。
💡 userList 必须为数组，数组中的每一项建议包含 organizationList、userName、mobile、nmUserId。
💡 当前接口中，organizationList 不作为最终通过条件；nmUserId 作为第三方侧用户标识原样透传返回。
请求示例
可以通过表单方式提交请求参数。
{
"encryption": "eyJ0ZW5hbnRJZCI6IjkzeHh4eHgiLCJjcmVkaXRDb2RlIjoiOTEzeHh4eHh4eHh4eHh4eHh4eCIsInVzZXJMaXN0IjpbeyJvcmdhbml6YXRpb25MaXN0IjoieHh45YWs5Y+4L3h45Yy66YOoL3h45LiA6YOoIiwidXNlck5hbWUiOiLmsZ/lpKkiLCJtb2JpbGUiOiIxODMxMDQyNTg0OCIsIm5tVXNlcklkIjoieHh4eHh4MTIzNDU2In1dfQ=="
}
encryption 解码后的载荷示例：
{
"tenantId": "93xxxxx",
"creditCode": "913xxxxxxxxxxxxxxx",
"userList": [
{
"organizationList": "xxx公司/xx部门/xx一部",
"userName": "江天",
"mobile": "18310425848",
"nmUserId": "xxxxxx123456"
},
{
"organizationList": "xxx公司/xx部门/xx一部",
"userName": "江天",
"mobile": "18310425848",
"nmUserId": "xxxxxx123457"
}
]
}
成功响应
条件：请求参数合法，企业配置存在，creditCode 对应企业有效，用户存在且状态正常，并且用户确实归属于该 creditCode 对应企业。
状态码：200 OK
响应示例：
{
"code": 0,
"message": "success",
"data": {
"items": "W3sienB5VXNlcklkIjoieHh4eDY1NDMyMSIsIm5tVXNlcklkIjoieHh4eHh4MTIzNDU2In0seyJ6cHlVc2VySWQiOiJ4eHh4NjU0MzIyIiwibm1Vc2VySWQiOiJ4eHh4eHgxMjM0NTcifV0=",
"_links": {
"self": {
"href": "/v2/business/nuoming/check-valid?page=1&size=100"
},
"first": {
"href": "/v2/business/nuoming/check-valid?page=1&size=100"
},
"last": {
"href": "/v2/business/nuoming/check-valid?page=1&size=100"
}
},
"_meta": {
"totalCount": 2,
"pageCount": 1,
"currentPage": 1,
"perPage": 100
}
}
}
items 解码后的示例：
[
{
"zpyUserId": "xxxx654321",
"nmUserId": "xxxxxx123456"
},
{
"zpyUserId": "xxxx654322",
"nmUserId": "xxxxxx123457"
}
]
错误响应
条件：请求参数为空、encryption 缺失、base64 解码失败、JSON 非法、creditCode 缺失、userList 为空、企业未配置、企业组织不存在、用户不存在、用户已删除、用户已离职、用户不属于当前企业等。
状态码：200 OK
响应示例：
{
"code": 1,
"message": "C1201|用户不存在",
"data": []
}
错误码
错误码 含义
C0000 通用成功
C1001 请求参数不能为空
C1003 creditCode不能为空
C1004 userList不能为空
C1005 userList单项格式不正确
C1006 userName不能为空
C1007 mobile不能为空
C1009 encryption不能为空
C1010 encryption解码失败或解码后不是合法JSON
C1011 page必须大于等于1
C1012 size必须大于等于1
C1101 未找到对接企业配置
C1102 未找到对应企业组织
C1103 企业组织已删除
C1104 用户存在，但不属于当前creditCode对应企业
C1201 用户不存在
C1202 用户已被逻辑删除
C1203 用户已离职
C1204 用户未挂载到任何有效企业
C1205 用户在企业下状态异常
C1206 用户所在组织不存在或已删除
注意事项
本接口为批量校验接口，请求体实际提交形式为 encryption，内容是原始 JSON 的 base64 编码字符串，而不是直接提交明文字段。
tenantId 为第三方系统侧企业编码，仅用于请求透传和日志记录，不作为我方主业务校验依据。我方不会使用该字段直接判断企业归属关系。
我方用户匹配仅使用 userName 与 mobile 两个字段。也就是说，单个人员是否命中，核心取决于姓名与手机号在我方系统中是否存在唯一且有效的人员记录。
企业归属不是通过第三方传入的 tenantId 判断，而是通过我方内部用户挂载关系进行判断。具体为：先找到用户，再根据用户挂载的企业任职关系与组织节点，反查所属企业根节点，并将其统一社会信用代码与 creditCode 进行匹配。
organizationList 当前不作为最终通过条件，主要作为第三方传值保留字段；如后续业务需要，也可以扩展为组织链路精确比对。
nmUserId 为第三方侧用户唯一标识，本接口不会拿它做人员识别，仅在校验通过后原样返回，便于第三方系统进行结果映射。
items 字段中的内容为 base64 编码后的 JSON 数组，第三方系统收到后需自行解码，再获取实际的 zpyUserId 与 nmUserId 对应关系。
接口返回 success，只代表本次接口调用本身成功完成；实际校验结果体现在 items 中，仅校验通过的用户才会进入返回列表，未通过用户不会出现在 items 中。
分页参数 page、size 如未显式传入，则默认按 page=1、size=100 处理；size 超过系统允许上限时，将按系统最大值截断处理。
如果你要，我下一条可以直接继续给你整理成可直接贴到语雀/apifox 的表格化版本，包括：
更整齐的“请求参数表”
“items 解码前后示例”
“成功/失败响应模板”
“字段说明版返回示例”
发表评论: