一、应用场景
企业成员登录是指物联云平台B端用户的登录认证服务。包含
- 物联云平台密码登录
- 第三方平台认证后免验证登录
- 物联云平台登录后授权给第三方平台免验证登录
企业可根据实际使用场景选择提供的登录方式。采用第三方平台验证或授权第三方平台登录,则需要完成与物联云平台的对接。
物联云平台支持企业通过第三方平台认证通过后,可以在平台进行免验证登录。物联云平台提供两种方式进行免验证登录。
第一种需要企业在物联云平台配置对应的免验证登录接口,并且登录至物联云平台时,需要提供登入企业id、第三方平台open_id、第三方access_token。物联云平台使用open_id和access_token作为一组信息,通过免验证登录接口确认登录人的认证状态。企业成员通过免验证首次登录时,未建立企业成员的情况下,平台会自动完成企业成员的创建。
第二种需要企业提前将带有第三方成员标识的企业成员同步至物联云平台中,并获取empower级别的access_token。企业成员登录至物联云平台时,需要提供access_token和第三方成员标识。物联云平台根据第三方企业标识进行认证。
物联云平台的账号体系为企业下唯一,即同一个账号(邮箱、手机号)可以存在于多个企业租户中。当账号存在于多个企业时,则需要登录人选择需要登入的企业。
二、功能说明
企业可通过实际场景选择提供给企业成员的登录方式。根据选用的登录方式进行对接。
物联云平台密码登录:支持通过物联云平台已创建企业成员的邮箱/手机号和密码进行登录,邮箱和手机号二选一,优先使用手机号。企业可以在【系统设置->组织与用户->用户管理】中创建企业成员。也可以通过数据同步的方式将企业成员同步至物联云平台中。
第三方平台免验证登录:第三方平台可以将接口地址配合在物联云平台中,完成与物联云平台的联调后,企业成员可以通过第三方平台身份进行登录。
第三方平台成员标识登录:第三方平台将企业成员同步至物联云平台后,企业成员登录时候,通过第三方成员标识进行认证登录。
三、前提条件
1.通过物联云平台登录,需要完成企业成员信息的创建。
2.通过第三方平台免验证登录,需要完成与物联云平台的对接。
3.通过第三方平台成员标识登录,需要完成企业成员的同步。
四、关键流程
4.1 成员登录
流程说明:
- 首先,**B端成员 **在企业管理台输入要登录的手机或者邮箱后物联网中台发起 根据账号查询企业虚拟信息列表 请求,得到手机或者邮箱所在的企业信息列表,并选择要登录的企业。
- 其次,**B端成员 **选择需要登录的企业后,输入对应的密码向物联网中台发起 成员登录 请求。
- 最后,物联网中台接收到 成员登录 请求后进行一系列业务逻辑校验,为登录者颁发成员级调用凭证以及刷新凭证。
4.2 成员图片验证码登录
流程说明:
- 首先,**B端成员 **在企业管理台输入要登录的手机或者邮箱后物联网中台发起 根据账号查询企业虚拟信息列表 请求,得到手机或者邮箱所在的企业信息列表,并选择要登录的企业。
- 其次,**企业管理台 **向物联网中台发起 申请图片验证码 请求,物联网中台接收到请求后生成图片验证码以及与之匹配的会话标识返回给企业管理台进行展示。
- 再次,**B端成员 **选择需要登录的企业输入图片验证码以及密码向物联网中台发起 成员图片验证码登录 请求。
- 最后,物联网中台接收到 成员图片验证码登录 请求后进行一系列业务逻辑校验,为登录者颁发成员级调用凭证以及刷新凭证。
4.3 成员第三方登录
流程说明:
- 首先,B端成员 登录到物联云平台标准第三方平台,获得第三方平台调用凭证以及第三方标识。
- 其次,B端成员 依据第三方平台调用凭证以及第三方标识向物联网中台发起 成员第三方登录 请求。
- 最后,物联网中台接收到 成员第三方登录 请求后查找出对应的第三方平台校验地址和校验凭证,向物联云平台第三方平台发起校验请求,校验通过后为登录者颁发成员级调用凭证以及刷新凭证。
4.4 平台访问授权授权成员登录
流程说明:
- 首先,第三方系统页面跳转到物联网中台企业管理台 时只会带上第三方系统的信息以及临时授权码。
- 其次,企业管理台 提取临时授权码向第三方对接系统发起请求 临时凭证第三方登录 请求,此接口为定制接口。
- 再次,第三方对接系统 向第三方系统发起 校验临时授权码是否有效 请求,如有效即可得到需要登录的B端成员账号。
- 接着,第三方对接系统 根据配置的平台访问授权标识和秘钥向物联网中台发起 获取平台访问授权 得到平台访问授权级调用凭证Empower。
- 最后,第三方对接系统 根据需要登录的B端成员账号 和 平台访问授权级调用凭证Empower 向物联网中台发起 平台访问授权授权成员登录 请求得到成员级调用凭证以及刷新凭证,进而返回给企业管理台。
4.5 成员调用凭证管理
流程说明:
- 首先,企业管理台在B端成员登录到物联网中台 得到物联网中台成员级调用凭证和刷新凭证,临时存储在浏览器中。
- 其次,企业管理台 在感知成员级别调用凭证过期时,利用调用凭证对应的刷新凭证向物联网中台发起 成员刷新调用凭证 请求。
- 最后,物联网中台接收到 成员刷新调用凭证 请求后校验刷新凭证的有效性,校验通过后为登录者颁发新的成员级调用凭证以及刷新凭证。
五、API列表
5.1 成员登录
5.1.1 根据账号查询企业虚拟信息列表
接口描述
无凭证下根据邮箱或手机号码查询企业虚拟信息列表,企业名称需要脱敏;企业标识需要虚拟化, 虚拟化标识一小时有效;查询逻辑为根据邮箱或者手机号查询成员列表信息, 然后根据成员所在的企业标识查询所在的企业虚拟信息
请求方式
POST
请求地址
/v2/service/corp-service/members/corp-virtual/infos
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Access-Token | true | String | 调用凭证 企业成员 |
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
body | false | String | 邮箱地址 | |
phone | body | false | String | 手机号码 |
type | body | true | Int | 查询类型 1:邮箱 2:手机号 |
请求示例:
{
"type": 1,
"email": "liqinghua@xlink.cn",
"phone": "13838383388"
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
count | true | Int | 符合条件企业总数 |
list | true | Array | 符合条件企业列表 |
list.id | true | String | 成员标识 |
list.name | true | String | 成员名称 |
返回示例:
{
"count": 1,
"list": [{
"id": "132165654612",
"name": "物联云平台"
}]
}
错误码:
错误码 | 描述 |
---|---|
4001001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
5.1.2 成员登录
接口描述
企业成员选定要登录的企业,然后根据账号密码进行登录
请求方式
POST
请求地址
/v2/corp_auth
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Access-Token | true | String | 调用凭证 企业成员 |
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
account | body | true | String | 成员账号 |
password | body | true | String | 成员密码 |
terminal | body | false | Int | 登录所属端,默认管理台 0: 管理台 1: 移动端 2: IOC大屏端 |
version | body | false | Int | 登录版本 0: 默认版本 1: V1版本, 新版权限使用V1版本 |
corp_id | body | false | String | 企业标识, 可为 1.真实企业标识 2.虚拟企业标识 |
请求示例:
{
"account": "138383388",
"password": "Test@#$12354",
"terminal": 0,
"version": 1,
"corp_id": "123498564153"
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
corp_id | true | String | 企业标识 |
member_id | true | String | 成员标识 |
access_token | true | String | 调用凭证 |
refresh_token | true | String | 刷新凭证 |
expire_in | true | Int | 调用凭证过期时长 |
role_type | true | Int | 企业成员角色类型,枚举: 0:创建者 1:管理员 99:自定义 |
返回示例:
{
"corp_id": "23136532",
"member_id": "23652655651",
"access_token": "32112456326sdfsdfewfdsafdsads3sfweafadscwedf",
"refresh_token": "32112456326sdfsdfewfdsafdsads31sd3f1sd3f1sdf",
"expire_in": 7200,
"role_type": 1
}
错误码:
错误码 | 描述 |
---|---|
4001001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
4031024 | 权限不足 |
4031023 | 权限不足 |
4041003 | 成员不存在 |
4001008 | 账号不合法 |
4001009 | 账号状态不合法 |
4001521 | 成员已过期 |
5.2 成员图片验证码登录
5.2.1 根据账号查询企业虚拟信息列表
接口描述
无凭证下根据邮箱或手机号码查询企业虚拟信息列表,企业名称需要脱敏;企业标识需要虚拟化, 虚拟化标识一小时有效;查询逻辑为根据邮箱或者手机号查询成员列表信息, 然后根据成员所在的企业标识查询所在的企业虚拟信息
请求方式
POST
请求地址
/v2/service/corp-service/members/corp-virtual/infos
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Access-Token | true | String | 调用凭证 企业成员 |
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
body | false | String | 邮箱地址 | |
phone | body | false | String | 手机号码 |
type | body | true | Int | 查询类型 1:邮箱 2:手机号 |
请求示例:
{
"type": 1,
"email": "liqinghua@xlink.cn",
"phone": "13838383388"
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
count | true | Int | 符合条件企业总数 |
list | true | Array | 符合条件企业列表 |
list.id | true | String | 成员标识 |
list.name | true | String | 成员名称 |
返回示例:
{
"count": 1,
"list": [{
"id": "132165654612",
"name": "物联云平台"
}]
}
错误码:
错误码 | 描述 |
---|---|
4001001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
5.2.2 申请图片验证码
接口描述
企业成员在登录之前申请一个验证码, 验证码有效期5分钟, 直到被验证之后, 同一个IP一秒钟只能申请一个验证码
请求方式
GET
请求地址
/v2/captcha/corp-auth
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
无 | 无 | 无 | 无 | 无 |
请求示例:
{
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
session_id | true | String | 会话标识, 一个图片验证码必须绑定一个session_id, 验证码的时候必须传session_id |
captcha_url | true | String | 图片验证码地址 |
返回示例:
{
"session_id": "12365625132",
"captcha_url": "http://www.baidu.com"
}
错误码:
错误码 | 描述 |
---|---|
4001001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
4001504 | IP超过了一秒钟申请一次的限制 |
5.2.3 成员图片验证码登录
接口描述
企业成员通过帐号和密码以及图片验证码登录,多用于企业管理台
请求方式
POST
请求地址
/v2/corp-auth-captcha
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
account | body | true | String | 成员账号 |
password | body | true | String | 成员密码 |
terminal | body | false | Int | 登录所属端,默认管理台 0: 管理台 1: 移动端 2: IOC大屏端 |
version | body | false | Int | 登录版本 0: 默认版本 1: V1版本, 新版权限使用V1版本 |
corp_id | body | false | String | 企业标识, 可为 1.真实企业标识 2.虚拟企业标识 |
session_id | body | true | String | 会话标识 |
captcha_code | body | true | String | 会话关联的验证码 |
请求示例:
{
"account": "13838383388",
"password": "Test@#$fdd",
"terminal": 0,
"session_id": "4123413651233",
"captcha_code": "784562",
"corp_id": "123454522",
"version": 1
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
corp_id | true | String | 企业标识 |
member_id | true | String | 成员标识 |
access_token | true | String | 调用凭证 |
refresh_token | true | String | 刷新凭证 |
expire_in | true | Int | 调用凭证过期时长 |
role_type | true | Int | 企业成员角色类型,枚举: 0:创建者 1:管理员 99:自定义 |
返回示例:
{
"corp_id": "23136532",
"member_id": "23652655651",
"access_token": "32112456326sdfsdfewfdsafdsads3sfweafadscwedf",
"refresh_token": "32112456326sdfsdfewfdsafdsads31sd3f1sd3f1sdf",
"expire_in": 7200,
"role_type": 1
}
错误码:
错误码 | 描述 |
---|---|
4001001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
4031024 | 权限不足 |
4031023 | 权限不足 |
4041003 | 成员不存在 |
4001008 | 账号不合法 |
4001009 | 账号状态不合法 |
4001521 | 成员已过期 |
4041119 | 图片验证码不存在 |
4001505 | 图片验证码不正确 |
4001506 | 账号密码不匹配, 当返回该错误码时, 返回参数msg表示账号还可以尝试多少次 |
4001507 | 账号被锁定, 当返回该错误码时, 返回参数msg表示账号还需要等待多少分钟才可以重试 |
5.3 成员第三方登录
5.3.1 成员第三方登录
接口描述
外部企业成员系统登录平台,自动将外部企业成员转为平台企业成员。多用于云云对接
请求方式
POST
请求地址
/v2/corp-auth-third
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
corp_id | body | true | String | 企业要登录的企业标识 |
open_id | body | true | String | 第三方业务系统成员标识 |
access_token | body | false | String | 第三方业务系统鉴权标识 |
source | body | false | Int | 第三方业务系统源, 目前仅支持source=2 |
请求示例:
{
"corp_id": "1235645822",
"open_id": "12312365515662",
"access_token": "595613214564654123465466646",
"source": 2
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
corp_id | true | String | 企业标识 |
member_id | true | String | 成员标识 |
access_token | true | String | 调用凭证 |
refresh_token | true | String | 刷新凭证 |
expire_in | true | Int | 调用凭证过期时长 |
role_type | true | Int | 企业成员角色类型,枚举: 0:创建者 1:管理员 99:自定义 |
返回示例:
{
"corp_id": "1365652131656512",
"member_id": "1231631631321565",
"access_token": "26321325665232sdafsdafweafweafddsf123132132",
"refresh_token": "32112456326sdfsdfewfdsafdsads31sd3f1sd3f1sdf",
"expire_in": 7200,
"role_type": 1
}
错误码:
错误码 | 描述 |
---|---|
4001001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
4031024 | 权限不足 |
4031023 | 权限不足 |
4041003 | 成员不存在 |
4001008 | 账号不合法 |
4001009 | 账号状态不合法 |
4001521 | 成员已过期 |
5.4 平台访问授权授权成员登录
5.4.1 获取平台访问授权
接口描述
第三方系统利用在企业管理台处获取平台访问的访问标识和访问秘钥,利用标识和秘钥请求物联网中台从而获得平台访问授权凭证。
请求方式
POST
请求地址
/v2/accesskey_auth
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
id | body | true | String | 平台访问授权标识 |
secret | body | true | String | 平台访问授权秘钥 |
请求示例:
{
"id":"4561321655663",
"secret":"1234654fds464fsd4f"
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
access_token | true | String | 调用凭证 |
返回示例:
{
"access_token": "32112456326sdfsdfewfdsafdsads3sf"
}
错误码:
错误码 | 描述 |
---|---|
4001001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
4031024 | 权限不足 |
4031023 | 权限不足 |
4041024 | 平台访问授权不存在 |
4001071 | 平台访问授权被禁用 |
4001072 | 平台访问授权秘钥错误 |
5.4.2 平台访问授权授权成员登录
接口描述
第三方系统利用平台授权登录得到调用凭证,代理企业成员登录,免密码;主要用于对接方案实施时对接第三方系统账号,前提第三方系统账号同步至物联云平台。
请求方式
POST
请求地址
/v2/empower-corp-auth
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Access-Token | true | String | 调用凭证 Empower |
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
account | body | true | String | 成员账号 |
请求示例:
{
"account":"13838383388"
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
corp_id | true | String | 企业标识 |
member_id | true | String | 成员标识 |
access_token | true | String | 调用凭证 |
refresh_token | true | String | 刷新凭证 |
expire_in | true | Int | 调用凭证过期时长 |
role_type | true | Int | 企业成员角色类型,枚举: 0:创建者 1:管理员 99:自定义 |
返回示例:
{
"corp_id": "23136532",
"member_id": "23652655651",
"access_token": "32112456326sdfsdfewfdsafdsads3sfweafadscwedf",
"refresh_token": "32112456326sdfsdfewfdsafdsads31sd3f1sd3f1sdf",
"expire_in": 7200,
"role_type": 1
}
错误码:
错误码 | 描述 |
---|---|
4001001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
4031024 | 权限不足 |
4031023 | 权限不足 |
4041003 | 成员不存在 |
4001008 | 账号不合法 |
4001009 | 账号状态不合法 |
4001521 | 成员已过期 |
5.5 成员调用凭证管理
5.5.1 成员刷新调用凭证
接口描述
企业成员通过刷新调用凭证, 刷新得到新的调用凭证。
请求方式
POST
请求地址
/v2/corp/token/refresh
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
refresh_token | body | true | String | 刷新调用凭证 |
请求示例:
{
"refresh_token": "32112456326sdfsdfewfdsafdsads31sd3f1sd3f1sdf"
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
access_token | true | String | 调用凭证 |
refresh_token | true | String | 刷新凭证 |
expire_in | true | Int | 调用凭证过期时长 |
返回示例:
{
"access_token": "32112456sdfsdafewfdsafdsafdsfsdacsdcds13222",
"refresh_token": "32112456326sdfsdfewfdsafdsasfweafwacsdcascsad113222",
"expire_in": 7200
}
错误码:
错误码 | 描述 |
---|---|
4001001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
4031024 | 权限不足 |
4031023 | 权限不足 |
4041003 | 成员不存在 |
4001008 | 账号不合法 |
4001009 | 账号状态不合法 |
4001521 | 成员已过期 |
4001010 | 刷新调用凭证不存在 |