edit

登录注册

账户体系

每个用户有唯一标识(uid), 及企业标识pid(Provider ID)。特别的pid=00000000000的用户属于氦氪用户,也是console所使用的账户体系。 申请企业开发者认证后企业可以拥有自己的账户体系,氦氪会分配一个pid给企业,在【个人中心-企业PID】查看。相同的手机邮箱可以在不同的pid下注册,彼此独立。开发者可以使用氦氪的PID(00000000000)或者自己的PID进行用户注册/登录(企业用户推荐)。

注册条件与限制

  • 同一手机号或者电子邮箱在同一个账户体系(即同一个pid下)中只能注册一次
  • 一个手机号在一天内最多只能发起5次请求短信验证码操作并且在请求之后的一分钟内无法再次发起请求验证码操作
  • 请求注册的手机号码或者邮箱账户必须有效并存在

手机注册

手机注册流程,向手机发送验证码必须先通过通过图片验证码校验:

以企业01282323922下注册用户,手机号13800001234,密码123ABC为例

首先请求图片验证码, 返回体是一张PNG图形验证码:

GET https://uaa-openapi.hekr.me/api/v1/captcha HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

{
    "rid": "74bb30ee-ab03-4cb2-a00a-9e931029195d",
    "png": "iVBORw0KGgoAAAANSUhEUgAAA..."
}

返回体

字段 含义
rid 图片验证码ID
png PNG格式图片数据(base64编码)

校验用户输入验证码返回图片验证临时码,可以不调用该接口,直接拼接{rid}:{code}调用后续接口

GET https://uaa-openapi.hekr.me/images/checkCaptcha?rid={rid}&code={code} HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

{
    "captchaToken": "39a03eab-c461-47c5-a5e9-5d3e8af24bd3:Xn2d"
}

请求参数

参数 是否必须 含义
rid 上述接口(GET /images/getImgCaptcha)传入的rid
code 用户根据图片验证码识别填入

返回体

字段 含义
captchaToken 图片验证临时码,可用于发送注册短信(GET /sms/getVerifyCode)

然后向手机发送验证码:

GET https://uaa-openapi.hekr.me/sms/getVerifyCode?phoneNumber=13800001234&pid=01282323922&token={token}&type=register HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
参数 是否必须 含义
phoneNumber 手机号
pid 企业PID
type 验证码类型 可取值[register, resetPassword, changePhone]
token 图片验证临时码,图片验证码校验通过返回的临时token

如果调用成功,用户手机应该能接受到短信验证码提示。验证码将在5分钟后过期,在验证码失效前调用接口:

POST https://uaa-openapi.hekr.me/register?type=phone HTTP/1.1

{
  "pid" :"01282323922",
  "phoneNumber" :"13800001234",
  "password" :"123ABC",
  "code" : "123456"
}

如果用户注册成功,则氦氪云将返回用户ID,如下所示:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "uid" : "51727051945"
}

邮箱注册

以企业01282323922下注册用户,邮箱user@example.com,密码123ABC为例

首先和手机注册一样获取图形验证码并校验获取token,然后向邮箱发送验证码:

GET https://uaa-openapi.hekr.me/email/getVerifyCode?email=user@example.com&pid=01282323922&token={token}&type=register HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
参数 是否必须 含义
email 邮箱
pid 企业PID
type 验证码类型 可取值[register, resetPassword, changeEmail]
token 图片验证临时码,图片验证码校验通过返回的临时token

如果调用成功,用户邮箱应该能接受到邮件验证码提示。验证码将在1小时后过期,在验证码失效前调用接口:

POST https://uaa-openapi.hekr.me/register?type=email_verify_code HTTP/1.1

{
  "pid" :"01282323922",
  "email": "user@example.com",
  "password" :"123ABC",
  "code" : "123456"
}

如果用户注册成功,则氦氪云将返回用户ID,如下所示:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "uid" : "51727051945"
}

使用账号密码登录

用户注册成功后,可以通过手机号码或者电子邮箱进行登录,使用账号密码登录:

POST https://uaa-openapi.hekr.me/login HTTP/1.1
Content-Type: application/json

{
  "pid" : "01282323922",
  "username" : "13800001234",
  "password" : "123ABC",
  "clientType" : "ANDROID"
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token": "eyJhbGciO...",
  "refresh_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86399,
  "user": "12264113078"
}

请求体

参数 是否必选 含义
pid 企业PID
username 用户手机号或者用户邮箱
password 用户密码
clientType 客户端类型,可取值[IOS, ANDROID, WEB]

返回体

字段 含义
access_token 用户token,即是接口文档中{JWT_TOKEN},24小时过期
refresh_token 刷新token,可以凭此token刷新access_token,30天过期
token_type token类型,当前仅有bearer
expires_in acess_token 过期时间(秒)
user 用户ID

注意

  1. 如果你要保存 access_token,请确保将其保存到一个安全的地方,且不会被其他应用程序访问到。如果恶意应用程序获得该访问令牌,那么它便可以伪装成该令牌的权属人访问氦氪云。
  2. 氦氪云并没有登出功能,直接将 access_token 从客户端的内存中释放即可登出(这也适用于客户端 SDK)。

微信登录

Note

当该用户未注册时,将注册一个匿名用户(没有手机邮箱密码),并返回其token。

POST https://uaa-openapi.hekr.me/login?type=wechat HTTP/1.1
Content-Type: application/json

{
  "pid": "01282323922",
  "access_token": "JIx_2jIJ...",
  "openid": "cji9iqn..."
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token": "eyJhbGciO...",
  "refresh_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86399,
  "user": "12264113078"
}

请求体

参数 是否必须 含义
pid 企业PID
access_token 微信access_token,必须有效
openid 微信openid

刷新access_token

使用refesh_token刷新access_token

POST https://uaa-openapi.hekr.me/token/refresh HTTP/1.1

{
  "refresh_token" : "eyJhbGciOi",
  "expires_in": 86400
}

使用serverkey刷新access_token

POST https://uaa-openapi.hekr.me/token/refresh HTTP/1.1

{
  "serverKey": "33995635438:YO0J...",
  "expires_in": 86400
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token": "eyJhbGciO...",
  "refresh_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86399,
  "user": "12264113078"
}

请求体

参数 是否必须 默认值 含义
refresh_token 刷新token,必须指定refresh_token 或serverKey其中之一
serverKey 用户serverKey,必须指定refresh_token 或serverKey其中之一
expires_in 86400 token过期时间(秒),最大不能超过86400

Note

如果refresh_token已过期,接口亦返回403 HTTP错误码,那么此时必须调用使用账号密码登录重新登录并获取氦氪云重新签发的access_tokenrefresh_token

使用旧密码修改密码

用户可以通过现有密码进行密码的修改,用户必须登录后方可修改密码。

POST https://uaa-openapi.hekr.me/changePassword HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

{
  "pid" : "01282323922",
  "newPassword" : "ABC123",
  "oldPassword" : "123ABC"
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

使用手机号重置密码

首先向手机发送验证码

GET https://uaa-openapi.hekr.me/sms/getVerifyCode?phoneNumber=13800001234&pid=01282323922&type=resetPassword HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

用户手机接收到验证码后,将短信验证码与新密码填入表单:

POST https://uaa-openapi.hekr.me/resetPassword?type=phone HTTP/1.1

{
  "pid" : "01282323922",
  "phoneNumber" : "13800001234",
  "verifyCode" : "123456",
  "password" : "ABC123"
} 
HTTP/1.1 200 OK

使用邮箱重置密码

首先向邮箱发送验证码

GET https://uaa-openapi.hekr.me/email/getVerifyCode?eamil=user@example.com&pid=01282323922&type=resetPassword HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

用户邮箱接收到验证码后,将验证码与新密码填入表单:

POST https://uaa-openapi.hekr.me/resetPassword?type=email_verify_code HTTP/1.1

{
  "pid" : "01282323922",
  "email" : "user@example.com",
  "verifyCode" : "123456",
  "password" : "ABC123"
} 
HTTP/1.1 200 OK

Note

你可以在console 定制APP管理中自定义邮件和短信的内容。

修改用户的手机号码

首先向旧手机发送验证码

GET https://uaa-openapi.hekr.me/sms/getVerifyCode?phoneNumber=13800001234&pid=01282323922&type=changePhone HTTP/1.1
HTTP/1.1 200 OK

校验验证码并获取到token:

GET https://uaa-openapi.hekr.me/sms/checkVerifyCode?phoneNumber=13800001234&code=101436&type=changePhone HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "phoneNumber": "13800001234",
  "verifyCode": "101436",
  "token": "dd27b62f-ce29-4411-9bc2-d1e3386e176f",
  "expireTime": 1452073528209
}   

向新手机发送验证码:

GET https://uaa-openapi.hekr.me/sms/getVerifyCode?phoneNumber=13800001234&pid=01282323922&type=register HTTP/1.1

最后调用修改手机号请求:

POST https://uaa-openapi.hekr.me/changePhoneNumber HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

{
  "pid" : "01282323922",
  "token" : "dd27b62f-ce29-4411-9bc2-d1e3386e176f",
  "verifyCode" : "123456",
  "phoneNumber" : "13800001234"
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8 

请求体

参数 是否必须 含义
pid 企业PID
token 旧手机验证码验证返回的token
verifyCode 新手机验证码
phoneNumber 新手机号

修改用户电子邮箱

首先向旧邮箱发送验证码

GET https://uaa-openapi.hekr.me/email/getVerifyCode?email=aa@hekr.me&pid=01282323922&type=changeEmail HTTP/1.1
HTTP/1.1 200 OK

校验验证码并获取到token:

GET https://uaa-openapi.hekr.me/email/checkVerifyCode?email=aa@hekr.me&code=101436&type=changeEmail HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "email": "aa@hekr.,e",
  "verifyCode": "101436",
  "token": "dd27b62f-ce29-4411-9bc2-d1e3386e176f",
  "expireTime": 1452073528209
}   

向新邮箱发送验证码:

GET https://uaa-openapi.hekr.me/email/getVerifyCode?email=bb@hekr.me&pid=01282323922&type=register HTTP/1.1

最后调用修改邮箱请求:

POST https://uaa-openapi.hekr.me/changeEmail HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

{
  "pid" : "01282323922",
  "token" : "dd27b62f-ce29-4411-9bc2-d1e3386e176f",
  "verifyCode" : "123456",
  "email" : "bb@hekr.me"
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8 

请求体

参数 是否必须 含义
pid 企业PID
token 旧邮箱验证码验证返回的token
verifyCode 新邮箱验证码
email 新邮箱

第三方登录

以QQ登录为例:

GET https://uaa-openapi.hekr.me/OAuth?type=QQ&pid=01282323922&clientType=WEB HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
HTTP/1.1 301 OK
Location: https://graph.qq.com/oauth/show...

调用后将返回一个重定向,浏览器将跳转到QQ等第三方登录页面,用户登录验证后若未在氦氪云上注册过,那么将跳转到https://webapp.hekr.me/#/app/bindAccount?token=1ed9feaefec744efac32074b5c74cd87&nick=allurelove&avatar=http:%2F%2Fqzapp.qlogo.cn%2Fqzapp%2F101298527%2FE46044B96ACD76913E2E074437F078E3%2F100,在webapp.hekr.me 上渲染的界面如下图

原有逻辑中用户填写已有的主账号的账户和密码,并点选登录且绑定则会将主账号和该三方账户绑定。如果没有主账户,那么用户还需要点击没有账号?马上注册进行主账号的创建,再来通过三方账户登录进行绑定。整个流程如下:

移动端第三方登录

GET https://uaa-openapi.hekr.me/MOAuth?type=QQ&pid=01282323922&clientType=IOS&certificate={certificate}&certificateSecret={certificateSecret}&uid={uid} HTTP/1.1

请求参数

参数 是否必选 含义
clientType 客户端类型, 可取值[IOS, ANDROID, WEB]
pid 企业PID
type 第三方登录类型,可取值[GOOGLE, WECHAT, QQ, SINA, FACEBOOK, TWITTER]
certificate 第三方登录返回的access_token,type=WECHAT为authorization_code
certificateSecret type=TWITTER时使用
uid type=SINA时指定,为新浪用户UID

若该三方账户已经与某个主账户绑定,则登录成功,那么接口返回:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token": "eyJhbGciO...",
  "refresh_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86399,
  "user": "12264113078"
}

若该三方账户未与主账户绑定,那么接口返回:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "uid": null,
  "pid": "01xxxxxxxxx",
  "oAuthType": "ANDROID",
  "bindToken": "qazxswedcvfrtgbnhyujmkilop",
  "unionId": "xxxxxxx",                               
  "nick": "",                                         
  "avatar": "https://xxx.xxx.xxx/xxxx.png"  
}
字段 含义
bindToken 临时绑定token,作为创建匿名主账户并绑定中的token参数传入
unionId 用户在各个OAuth平台上的唯一ID
nick 用户在各个OAuth平台上的昵称
avatar 用户在各个OAuth平台上的头像图片链接

此时APP需要增加用户协议交互页面,用户点击接受协议后,调用接口创建匿名主账户并绑定之后将该三方账户与接口内部新建的 一个主账户进行绑定,并最终返回token,流程结束。

绑定OAUTH账号

GET https://uaa-openapi.hekr.me/account/bind?token={token} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8 

创建匿名主账户并绑定

GET https://uaa-openapi.hekr.me/account/createUserAndBind?pid=01282323922&token=${token}&clientType=${clientType} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token": "eyJhbGciO...",
  "refresh_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86399,
  "user": "12264113078"
}
参数 是否必选 含义
clientType 客户端类型, 可取值[IOS, ANDROID, WEB]
pid 企业PID
token 移动端第三方登录 中可能返回的bindToken

第三方账号用手机升级主账号

首先和以手机注册用户一样向手机发送验证码

GET https://uaa-openapi.hekr.me/sms/getVerifyCode?phoneNumber=13800001234&pid=01282323922&token={token}&type=register HTTP/1.1
HTTP/1.1 200 OK

如果调用成功,用户手机应该能接受到短信验证码提示。验证码将在5分钟后过期,在验证码失效前调用接口:

POST https://uaa-openapi.hekr.me/accountUpgrade HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
{
  "phoneNumber" : "13800001234",
  "verifyCode" : "123456",
  "password" : "ABC123"
} 
HTTP/1.1 200 OK

第三方账号用邮箱升级主账号

首先向邮箱发送验证码

GET https://uaa-openapi.hekr.me/email/getVerifyCode?email=user@example.com&pid=01282323922&token={token}&type=register HTTP/1.1
HTTP/1.1 200 OK

如果调用成功,用户邮箱应该能接受到邮件验证码提示。验证码将在1小时后过期,在验证码失效前调用接口:

POST https://uaa-openapi.hekr.me/accountUpgrade?type=email HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
{
  "email": "user@example.com",
  "verifyCode" : "123456",
  "password" : "ABC123"
} 
HTTP/1.1 200 OK

解token

GET https://uaa-openapi.hekr.me/token/check_token?token={token} HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "uid": "68848240316",
    "exp": 1504789751,
    "authorities": [
        "ROLE_USER"
    ],
    "jti": "8ecc3d94-6f63-4dc9-8830-6f17b39953c1",
    "pid": "01585462418"
}

请求参数

参数 是否必须 含义
token 用户access_token

返回体

字段 含义
uid 用户UID
exp token过期时间戳(秒)
pid 企业PID

企业注册用户

氦氪云提供了一个供厂家管理员直接注册用户的接口,该接口的意义在于,厂家有自己的账号体系,并且想要将这些用户关联到氦氪云上,并使用氦氪云的服务,那么厂家自有用户无需操作氦氪云的账户信息,而厂家可以代理用户进行操作,比如在注册厂家的账号的同时,厂家后台同步调用氦氪云接口创建一个与之关联的账号,这样就屏蔽了用户和氦氪云之间的关系,用户只需要关心并操作厂家提供的 app 或者 web等上的操作即可。

这里,氦氪云提供了两个接口用于帮助厂家注册用户到氦氪云平台。

单一注册

POST https://uaa-openapi.hekr.me/enterprise/register HTTP/1.1
Authorization: key={serverKey}
Content-Type: application/json;charset=UTF-8

{
  "phone":"xx",
  "email":"xx",
  "password":"hashedChars"
}

参数

参数 必填 说明
phone 和 email 二选一,这两个必须有一个必填
email 和 phone 二选一,这两个必须有一个必填
password 哈希后的密码,建议不要和自有账号体系密码一致,增强安全性。最小长度6,最大长度1000
serverKey 后台个人中心生成

返回

status code

  • 200 正常
  • 409 手机号或者邮箱已经存在
  • 400 参数错误

返回体和普通注册一样,参见这里

Tip

下面提供了批量注册接口,可以一次性注册多个账号。推荐方式:用户调用企业的登录接口的时候,企业后台先判断该用户有没有在氦氪云平台注册过,如果注册了,直接调用登录,获取凭证,如果没有注册,则调用上面的接口进行注册,然后在后台保留映射关系。这个方式的好处在于,APP 的情况下,一般情况下并不是所有用户都会更新到最新的 app,企业在上了这个功能的时候,旧的用户如果切换到新的 app,企业也无需重新调用批量注册接口重新注册。而且,单独调用批量接口还是需要先判断哪些用户已经注册过,并且不能保持实时注册。

批量注册

批量注册没有数量上的限制,如果用户数量较大,建议分批次调用该接口,方便注册失败时候排查问题。

POST https://uaa-openapi.hekr.me/enterprise/register/batch HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: key={serverKey}

[{
  "phone":"phone",
  "email":"email",
  "password":"hashedChars"
}]

参数

和单一注册一样

返回

[
  {
    "uid":"xxx",
    "phone":"xxx",
    "email":"email",
    "success":true, // 注册结果,true 成功,false 失败
    "msg":"" // 失败详细信息
  }
]

企业直接使用用户名和密码登录

注意,这里是企业直接通过使用用户的用户名(手机号或者邮箱)和哈希后的密码登录氦氪云平台,获取登录凭证,普通用户请使用上面的使用账号密码登录接口进行登录。

POST https://uaa-openapi.hekr.me/enterprise/userLogin HTTP/1.1
Authorization: key={serverKey}
Content-Type: application/json;charset=UTF-8

{
  "username":"phoneOrEmail",
  "password":"hashedChars"
}

返回

参见使用账号密码登录接口的返回。

企业修改用户的密码

POST https://uaa-openapi.hekr.me/enterprise/changePassword HTTP/1.1
Authorization: key={serverKey}
Content-Type: application/json;charset=UTF-8

{
  "username":"phoneOrEmail",
  "password":"hashedChars",
}
204 No Content

status code

  • 400 参数错误
  • 404 用户不存在

企业修改用户的手机号

POST https://uaa-openapi.hekr.me/enterprise/changePhone HTTP/1.1
Authorization: key={serverKey}
Content-Type: application/json;charset=UTF-8

{
  "username":"phoneOrEmail",
  "phone":"newPhone",
}
204 No Content

status code

  • 409 手机号已经存在
  • 400 参数错误
  • 404 用户不存在

企业修改用户的邮箱

POST https://uaa-openapi.hekr.me/enterprise/changeEmail HTTP/1.1
Authorization: key={serverKey}
Content-Type: application/json;charset=UTF-8

{
  "username":"phoneOrEmail",
  "email":"newEmail",
}
204 No Content

status code

  • 409 邮箱已经存在
  • 400 参数错误
  • 404 用户不存在

错误码表

错误码 提示信息 中文释义 可能造成的原因
400016 Rate limit exceeded 调用接口频率过快受限 调用接口频次过频繁
400017 Times limit exceeded 调用次数受限 调用接口次数超过限制
3200000 Success 调用成功 调用成功
3400000 Error 未知错误 该行下面的以3400开头的错误码需要单独处理
3400001 Phone number invalid 手机号无效 手机号码无效
3400002 Verify code error 验证code错误 验证code错误
3400003 Verify code expire 验证code过期 验证code过期
3400004 Verify code send too fast 发送code过快 发送code过快
3400005 Verify code send too many 发送code次数过多 发送code次数过多
3400006 Invalid request type 无效的请求类型 验证请求type填错了
3400007 Invalid old password 无效的旧密码 旧密码错误
3400008 User has been registered 用户已注册 用户已经注册
3400009 Your account has not been verified 账户尚未认证 用户尚未验证
3400010 Could not authenticate user. Verify the user name and password, and try again 用户名或密码错误 用户名或密码错误
3400011 User does not exist 用户不存在 用户不存在
3400012 Invalid email token 无效的邮件token 无效的邮件token
3400013 Your account has already been verified 账户已认证 账户已认证
3400014 Your account has already been linked to a {0} account 账户已经关联了某个三方账号 一个账户只能绑定一种三方账户,例如一个账户只能绑定一个微博
3400015 Invalid token 无效的token 使用了不合法或者过期的token
3400016 Account can not upgrade 账户无法升级为主账户 该三方账户无法升级为主账户
3400017 Invalid captcha token 无效的验证码token 提交了错误的验证码token
3400018 {0} 用户密保问题校验失败 用户还未设置密保问题或用户密保校验失败
3400019 Invalid token {0} 无效的token 在一些需要token的校验的方法中 用户的提供的token无效
3400020 Invalid captcha params 无效的验证码参数 用户获取图片校验码参数错误
3400021 captch code can not match 校验码不能匹配 用户的输入的图形校验码不能匹配
3400022 request failure {0} 接口调用失败 云端调用萤石云接口失败或者萤石云返回的错误信息异常
3400023 not open ys service 未开通萤石云服务 该用户还没有开通萤石云服务(获取accessToken前需先开通萤石云服务)
3400024 Phone number invalid 手机号无效 手机号码无效
3400025 oauth not cofig 厂家未配置对应的三方登录配置信息 果app端开启了三方登录,但是console上未进行配置相应信息
3500000 Internal error ({0}) 内部错误 服务内部错误