full/wiki/api/06-passport.md

PASSPORT API

账号注册、登录、验证、找回密码和账户资料管理。

本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。

接入方式

• 动态 HTTP：POST /rpc/passport/{Service}/{Method}
• 原生 gRPC：/passport.{Service}/{Method}
• grpc-gateway：POST /passport.{Service}/{Method}
• 鉴权：需要登录的接口通过 Authorization: <JWT> 传递裸 JWT，不添加 Bearer 前缀。
• 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 code、message、details。

服务概览

服务	方法数	说明
Account	6	Account 服务
Forget	2	Forget 服务
Login	3	Login 服务
Register	2	Register 服务
Verify	2	Verify 服务

Account

方法	动态 HTTP 路径	请求	响应	类型
Get	POST /rpc/passport/Account/Get	base_passport_blocks.Empty	passport.GetFullReply	Unary
SetData	POST /rpc/passport/Account/SetData	passport.SetDataRequest	base_passport_blocks.StatusReply	Unary
SetPassword	POST /rpc/passport/Account/SetPassword	passport.SetPasswordRequest	base_passport_blocks.StatusReply	Unary
TagCreate	POST /rpc/passport/Account/TagCreate	passport.TagItem	base_passport_blocks.StatusReply	Unary
TagRemove	POST /rpc/passport/Account/TagRemove	base_passport_blocks.IdentRequest	base_passport_blocks.StatusReply	Unary
Statistics	POST /rpc/passport/Account/Statistics	passport.StatisticsRequest	passport.StatisticsReply	Unary

Account.Get

• 动态 HTTP：POST /rpc/passport/Account/Get
• gRPC：/passport.Account/Get
• 请求示例：

{}

Account.SetData

• 动态 HTTP：POST /rpc/passport/Account/SetData
• gRPC：/passport.Account/SetData
• 请求示例：

{
  "area": "string",
  "avatar": "string",
  "birthday": "string",
  "city": "string",
  "country": "string",
  "cover": "string",
  "level": 0,
  "nickname": "string",
  "province": "string",
  "score": 0,
  "sex": 0,
  "sign": "string"
}

Account.SetPassword

• 动态 HTTP：POST /rpc/passport/Account/SetPassword
• gRPC：/passport.Account/SetPassword
• 请求示例：

{
  "newPassword": "string",
  "oldPassword": "string"
}

Account.TagCreate

• 动态 HTTP：POST /rpc/passport/Account/TagCreate
• gRPC：/passport.Account/TagCreate
• 请求示例：

{
  "icon": "string",
  "name": "string"
}

Account.TagRemove

• 动态 HTTP：POST /rpc/passport/Account/TagRemove
• gRPC：/passport.Account/TagRemove
• 请求示例：

{
  "id": "0",
  "identity": "string"
}

Account.Statistics

• 动态 HTTP：POST /rpc/passport/Account/Statistics
• gRPC：/passport.Account/Statistics
• 请求示例：

{
  "field": [
    "string"
  ]
}

Forget

方法	动态 HTTP 路径	请求	响应	类型
Verify	POST /rpc/passport/Forget/Verify	passport.ForgetVerifyRequest	base_passport_blocks.StatusReply	Unary
Reset	POST /rpc/passport/Forget/Reset	passport.ForgetResetRequest	base_passport_blocks.StatusReply	Unary

Forget.Verify

• 动态 HTTP：POST /rpc/passport/Forget/Verify
• gRPC：/passport.Forget/Verify
• 请求示例：

{
  "code": "string",
  "phone": "string"
}

Forget.Reset

• 动态 HTTP：POST /rpc/passport/Forget/Reset
• gRPC：/passport.Forget/Reset
• 请求示例：

{
  "identity": "string",
  "password": "string"
}

Login

方法	动态 HTTP 路径	请求	响应	类型
Pwd	POST /rpc/passport/Login/Pwd	passport.LoginByPwdRequest	passport.LoginReply	Unary
Code	POST /rpc/passport/Login/Code	passport.LoginByCodeRequest	passport.LoginReply	Unary
Quick	POST /rpc/passport/Login/Quick	passport.LoginByCodeRequest	passport.LoginReply	Unary

Login.Pwd

• 动态 HTTP：POST /rpc/passport/Login/Pwd
• gRPC：/passport.Login/Pwd
• 请求示例：

{
  "account": "string",
  "password": "string"
}

Login.Code

• 动态 HTTP：POST /rpc/passport/Login/Code
• gRPC：/passport.Login/Code
• 请求示例：

{
  "agencyId": "0",
  "code": "string",
  "country": "string",
  "owner_id": "0",
  "owner_identity": "string",
  "phone": "string",
  "staffId": "0"
}

Login.Quick

• 动态 HTTP：POST /rpc/passport/Login/Quick
• gRPC：/passport.Login/Quick
• 请求示例：

{
  "agencyId": "0",
  "code": "string",
  "country": "string",
  "owner_id": "0",
  "owner_identity": "string",
  "phone": "string",
  "staffId": "0"
}

Register

方法	动态 HTTP 路径	请求	响应	类型
Pwd	POST /rpc/passport/Register/Pwd	passport.RegisterRequest	passport.RegisterReply	Unary
Code	POST /rpc/passport/Register/Code	passport.RegisterRequest	passport.RegisterReply	Unary

Register.Pwd

• 动态 HTTP：POST /rpc/passport/Register/Pwd
• gRPC：/passport.Register/Pwd
• 请求示例：

{
  "account": "string",
  "agencyId": "0",
  "code": "string",
  "country": "string",
  "email": "string",
  "owner_id": "0",
  "owner_identity": "string",
  "password": "string",
  "phone": "string",
  "staffId": "0"
}

Register.Code

• 动态 HTTP：POST /rpc/passport/Register/Code
• gRPC：/passport.Register/Code
• 请求示例：

{
  "account": "string",
  "agencyId": "0",
  "code": "string",
  "country": "string",
  "email": "string",
  "owner_id": "0",
  "owner_identity": "string",
  "password": "string",
  "phone": "string",
  "staffId": "0"
}

Verify

方法	动态 HTTP 路径	请求	响应	类型
Request	POST /rpc/passport/Verify/Request	passport.VerifyRequest	base_passport_blocks.StatusReply	Unary
JumioCallback	POST /rpc/passport/Verify/JumioCallback	passport.JumioCallbackPayload	base_passport_blocks.StatusReply	Unary

Verify.Request

• 动态 HTTP：POST /rpc/passport/Verify/Request
• gRPC：/passport.Verify/Request
• 请求示例：

{
  "args": {
    "key": "string"
  },
  "provider": "string"
}

Verify.JumioCallback

• 动态 HTTP：POST /rpc/passport/Verify/JumioCallback
• gRPC：/passport.Verify/JumioCallback
• 请求示例：

{
  "callbackDate": "string",
  "clientIp": "string",
  "customerInternalReference": "string",
  "document": {
    "issuingCountry": "string",
    "number": "string",
    "status": "string",
    "type": "string"
  },
  "faceMap": {
    "similarity": 0,
    "status": "string"
  },
  "personalInformation": {
    "dateOfBirth": "string",
    "firstName": "string",
    "lastName": "string",
    "nationality": "string"
  },
  "scanReference": "string",
  "verificationStatus": {
    "reason": "string",
    "state": "string"
  }
}

消息结构

base_passport_blocks.Empty

空消息：请求时发送 {}。

base_passport_blocks.IdentRequest

JSON 字段	类型	规则
id	int64	可选
identity	string	可选

base_passport_blocks.StatusReply

JSON 字段	类型	规则
code	int32	可选
message	string	可选
details	string	可选
timeseq	int64	可选

base_passport_blocks.VerifyStatus

JSON 字段	类型	规则
emailVerify	int32	可选
phoneVerify	int32	可选
faceVerify	int32	可选
documentVerify	int32	可选
kycVerify	int32	可选

passport.Document

JSON 字段	类型	规则
status	string	可选
type	string	可选
issuingCountry	string	可选
number	string	可选

passport.FaceMap

JSON 字段	类型	规则
status	string	可选
similarity	float	可选

passport.ForgetResetRequest

JSON 字段	类型	规则
identity	string	可选
password	string	可选

passport.ForgetVerifyRequest

JSON 字段	类型	规则
phone	string	可选
code	string	可选

passport.GetFullReply

JSON 字段	类型	规则
identity	string	可选
account	string	可选
phone	string	可选
email	string	可选
rights	string	可选
nickname	string	可选
avatar	string	可选
birthday	string	可选
sex	int32	可选
country	string	可选
province	string	可选
city	string	可选
area	string	可选
sign	string	可选
cover	string	可选
score	int32	可选
level	int32	可选
verifyStatus	base_passport_blocks.VerifyStatus	可选
tags	[]passport.TagItem	数组

passport.JumioCallbackPayload

JSON 字段	类型	规则
scanReference	string	可选
customerInternalReference	string	可选
verificationStatus	passport.VerificationStatus	可选
document	passport.Document	可选
personalInformation	passport.PersonalInformation	可选
faceMap	passport.FaceMap	可选
callbackDate	string	可选
clientIp	string	可选

passport.LoginByCodeRequest

JSON 字段	类型	规则
country	string	可选
phone	string	可选
code	string	可选
agencyId	int64	可选
staffId	int64	可选
owner_id	int64	可选
owner_identity	string	可选

passport.LoginByPwdRequest

JSON 字段	类型	规则
account	string	可选
password	string	可选

passport.LoginReply

JSON 字段	类型	规则
id	int64	可选
identity	string	可选
token	string	可选
extend	map<string, string>	对象映射
verifyStatus	base_passport_blocks.VerifyStatus	可选

passport.LoginReply.ExtendEntry

JSON 字段	类型	规则
key	string	可选
value	string	可选

passport.PersonalInformation

JSON 字段	类型	规则
firstName	string	可选
lastName	string	可选
dateOfBirth	string	可选
nationality	string	可选

passport.RegisterReply

JSON 字段	类型	规则
id	int64	可选
identity	string	可选
token	string	可选
extend	map<string, string>	对象映射
verifyStatus	base_passport_blocks.VerifyStatus	可选

passport.RegisterReply.ExtendEntry

JSON 字段	类型	规则
key	string	可选
value	string	可选

passport.RegisterRequest

JSON 字段	类型	规则
country	string	可选
email	string	可选
account	string	可选
phone	string	可选
password	string	可选
code	string	可选
agencyId	int64	可选
staffId	int64	可选
owner_id	int64	可选
owner_identity	string	可选

passport.SetDataRequest

JSON 字段	类型	规则
nickname	string	可选
avatar	string	可选
birthday	string	可选
sex	int32	可选
country	string	可选
province	string	可选
city	string	可选
area	string	可选
sign	string	可选
cover	string	可选
score	int32	可选
level	int32	可选

passport.SetPasswordRequest

JSON 字段	类型	规则
oldPassword	string	可选
newPassword	string	可选

passport.StatisticsReply

JSON 字段	类型	规则
Data	map<string, int64>	对象映射

passport.StatisticsReply.DataEntry

JSON 字段	类型	规则
key	string	可选
value	int64	可选

passport.StatisticsRequest

JSON 字段	类型	规则
field	[]string	数组

passport.TagItem

JSON 字段	类型	规则
name	string	可选
icon	string	可选

passport.VerificationStatus

JSON 字段	类型	规则
state	string	可选
reason	string	可选

passport.VerifyRequest

JSON 字段	类型	规则
provider	string	可选
args	map<string, string>	对象映射

passport.VerifyRequest.ArgsEntry

JSON 字段	类型	规则
key	string	可选
value	string	可选