访客注册与用户关联

用于把第三方系统的访客注册到 AIS，取得稳定用户编码并查询用户资料。适合网站、App、小程序等访客场景；需要部门、角色和员工登录能力时，请使用组织员工接口。

鉴权与权限

由对接服务端使用 Authorization: Bearer tk-...。API Key 对应租户决定数据归属，不传 tenantId。

接口	模块	最低权限
`POST /openapi/paas/v1/user/add`	`org_user`	`WRITE`
`GET /openapi/paas/v1/user/queryByCode`	`org_user`	`READ`

注册访客

POST /openapi/paas/v1/user/add，JSON 请求。

字段	类型	必填	规则
`code`	string	否	最长 50；英文字母、数字、下划线、短横线，至少有一个字母或数字；全局唯一；省略或空字符串时系统生成
`name`	string	是	不允许空白，最长 20
`nickName`	string	否	最长 20；未填写有效内容时使用 `name`
`logoImage`	string	否	头像地址

curl --request POST "${BASE_URL}/openapi/paas/v1/user/add" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept-Language: zh-CN" \
  --data '{
    "code": "partner_visitor_10001",
    "name": "访客10001",
    "nickName": "访客",
    "logoImage": "https://example.com/avatar/10001.png"
  }'

{
  "code": 8200,
  "message": "新增成功",
  "data": {
    "code": "partner_visitor_10001",
    "name": "访客10001",
    "nickName": "访客",
    "logoImage": "https://example.com/avatar/10001.png",
    "type": "VISITOR",
    "state": 1,
    "createTime": "2026-09-05T10:30:00"
  }
}

响应字段

注册与查询共用下列用户对象，外层字段见普通响应。

字段	JSON 类型	说明
`data.code`	string	AIS 用户业务编码，保存为外部用户映射
`data.name`	string	用户名称
`data.nickName`	string	昵称；注册未提供有效昵称时使用 name
`data.logoImage`	string / null	头像地址，未设置时可空
`data.type`	string	注册固定 VISITOR；查询员工时返回相应员工类型
`data.state`	integer	1 正常，0 停用；注册成功初始为 1
`data.createTime`	string	创建日期时间，无时区偏移，例如 2026-09-05T10:30:00

data.code 是后续关联使用的 AIS 用户编码。type 固定为 VISITOR，state 为 1（正常），createTime 为不带时区偏移的本地日期时间。logoImage 可以为空。

接口不创建登录密码、角色或部门关系；访客不因注册而具备 AIS 员工登录能力，默认不出现在普通组织成员列表。响应不包含手机号、邮箱、密码、租户编码或数据库主键。

查询用户

GET /openapi/paas/v1/user/queryByCode

Query 参数 code 必填，使用注册响应中的值：

curl --get "${BASE_URL}/openapi/paas/v1/user/queryByCode" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --data-urlencode "code=partner_visitor_10001"

响应示例：

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {
    "code": "partner_visitor_10001",
    "name": "访客10001",
    "nickName": "访客",
    "logoImage": null,
    "type": "VISITOR",
    "state": 1,
    "createTime": "2026-09-05T10:30:00"
  }
}

成功响应字段与注册一致，但查询不限于访客，type 可能为员工类型，state 可能为 0（停用）。只能查询 API Key 所属租户的用户；不存在时返回业务错误，不能把空结果当成注册成功。

重复请求

注册不执行覆盖更新。相同 code 再次注册会失败，即使另一租户已占用该编码也不能重复创建。建议加入合作方与租户的非敏感前缀，不使用手机号、邮箱或证件号作为编码。

保存外部用户到 AIS data.code 的映射。网络超时时先按预先生成的稳定编码查询，确认不存在后再决定是否重试；如果让 AIS 自动生成编码，超时后不要无条件再次注册，以免产生多个用户。

关联对话与历史

用户编码、对话身份与会话 ID 是三个不同概念：

入口	用户字段	当前行为
注册、用户查询	`code`	AIS 用户稳定编码
应用对话 `/openapi/community/v1/chat/completions`	`user`	将传入值用于对话用户标识；使用对应应用 AccessToken
标准对话 `/openapi/api/v1/chat/completions`	`userId`	当前以鉴权用户编码为准，传该字段不会切换身份
会话主题与历史查询	`userId`	传入生成记录时使用的用户标识；不传时使用鉴权用户
各类对话与历史查询	`conversationId`	保存并复用对话返回的会话 ID

典型访客流程为：注册并保存 data.code → 使用应用对话，在 user 中传该编码 → 保存 conversationId → 按会话查询传相同编码和会话 ID。

应用对话的 user 用于标识和关联记录，不会给访客增加知识库权限，也不替代应用认证。若使用标准 Chat，以鉴权身份为准；已开通渠道契约的项目可以按指定用户契约提供真实用户上下文，仍需满足该用户的业务权限。

对接服务端应根据已登录的外部用户确定 AIS 编码，校验用户与会话归属后再查询，不能直接信任客户端提交任意 userId 或 conversationId。

参数格式、重复编码、无权限、用户不存在等情况，按错误编码处理；不要按固定中文 message 判断结果。

鉴权与权限​

注册访客​

响应字段​

查询用户​

重复请求​