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: Bearer <token>` 传递凭证。
- 动态 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`](#base_passport_blocksempty) | [`passport.GetFullReply`](#passportgetfullreply) | Unary |
| `SetData` | `POST /rpc/passport/Account/SetData` | [`passport.SetDataRequest`](#passportsetdatarequest) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
| `SetPassword` | `POST /rpc/passport/Account/SetPassword` | [`passport.SetPasswordRequest`](#passportsetpasswordrequest) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
| `TagCreate` | `POST /rpc/passport/Account/TagCreate` | [`passport.TagItem`](#passporttagitem) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
| `TagRemove` | `POST /rpc/passport/Account/TagRemove` | [`base_passport_blocks.IdentRequest`](#base_passport_blocksidentrequest) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
| `Statistics` | `POST /rpc/passport/Account/Statistics` | [`passport.StatisticsRequest`](#passportstatisticsrequest) | [`passport.StatisticsReply`](#passportstatisticsreply) | Unary |

### Account.Get

- 动态 HTTP：`POST /rpc/passport/Account/Get`
- gRPC：`/passport.Account/Get`
- 白名单键：`passport.Account.Get`
- 请求示例：

```json
{}
```

### Account.SetData

- 动态 HTTP：`POST /rpc/passport/Account/SetData`
- gRPC：`/passport.Account/SetData`
- 白名单键：`passport.Account.SetData`
- 请求示例：

```json
{
  "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`
- 白名单键：`passport.Account.SetPassword`
- 请求示例：

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

### Account.TagCreate

- 动态 HTTP：`POST /rpc/passport/Account/TagCreate`
- gRPC：`/passport.Account/TagCreate`
- 白名单键：`passport.Account.TagCreate`
- 请求示例：

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

### Account.TagRemove

- 动态 HTTP：`POST /rpc/passport/Account/TagRemove`
- gRPC：`/passport.Account/TagRemove`
- 白名单键：`passport.Account.TagRemove`
- 请求示例：

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

### Account.Statistics

- 动态 HTTP：`POST /rpc/passport/Account/Statistics`
- gRPC：`/passport.Account/Statistics`
- 白名单键：`passport.Account.Statistics`
- 请求示例：

```json
{
  "field": [
    "string"
  ]
}
```

## Forget

| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
|---|---|---|---|---|
| `Verify` | `POST /rpc/passport/Forget/Verify` | [`passport.ForgetVerifyRequest`](#passportforgetverifyrequest) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
| `Reset` | `POST /rpc/passport/Forget/Reset` | [`passport.ForgetResetRequest`](#passportforgetresetrequest) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |

### Forget.Verify

- 动态 HTTP：`POST /rpc/passport/Forget/Verify`
- gRPC：`/passport.Forget/Verify`
- 白名单键：`passport.Forget.Verify`
- 请求示例：

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

### Forget.Reset

- 动态 HTTP：`POST /rpc/passport/Forget/Reset`
- gRPC：`/passport.Forget/Reset`
- 白名单键：`passport.Forget.Reset`
- 请求示例：

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

## Login

| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
|---|---|---|---|---|
| `Pwd` | `POST /rpc/passport/Login/Pwd` | [`passport.LoginByPwdRequest`](#passportloginbypwdrequest) | [`passport.LoginReply`](#passportloginreply) | Unary |
| `Code` | `POST /rpc/passport/Login/Code` | [`passport.LoginByCodeRequest`](#passportloginbycoderequest) | [`passport.LoginReply`](#passportloginreply) | Unary |
| `Quick` | `POST /rpc/passport/Login/Quick` | [`passport.LoginByCodeRequest`](#passportloginbycoderequest) | [`passport.LoginReply`](#passportloginreply) | Unary |

### Login.Pwd

- 动态 HTTP：`POST /rpc/passport/Login/Pwd`
- gRPC：`/passport.Login/Pwd`
- 白名单键：`passport.Login.Pwd`
- 请求示例：

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

### Login.Code

- 动态 HTTP：`POST /rpc/passport/Login/Code`
- gRPC：`/passport.Login/Code`
- 白名单键：`passport.Login.Code`
- 请求示例：

```json
{
  "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`
- 白名单键：`passport.Login.Quick`
- 请求示例：

```json
{
  "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`](#passportregisterrequest) | [`passport.RegisterReply`](#passportregisterreply) | Unary |
| `Code` | `POST /rpc/passport/Register/Code` | [`passport.RegisterRequest`](#passportregisterrequest) | [`passport.RegisterReply`](#passportregisterreply) | Unary |

### Register.Pwd

- 动态 HTTP：`POST /rpc/passport/Register/Pwd`
- gRPC：`/passport.Register/Pwd`
- 白名单键：`passport.Register.Pwd`
- 请求示例：

```json
{
  "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`
- 白名单键：`passport.Register.Code`
- 请求示例：

```json
{
  "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`](#passportverifyrequest) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
| `JumioCallback` | `POST /rpc/passport/Verify/JumioCallback` | [`passport.JumioCallbackPayload`](#passportjumiocallbackpayload) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |

### Verify.Request

- 动态 HTTP：`POST /rpc/passport/Verify/Request`
- gRPC：`/passport.Verify/Request`
- 白名单键：`passport.Verify.Request`
- 请求示例：

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

### Verify.JumioCallback

- 动态 HTTP：`POST /rpc/passport/Verify/JumioCallback`
- gRPC：`/passport.Verify/JumioCallback`
- 白名单键：`passport.Verify.JumioCallback`
- 请求示例：

```json
{
  "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` | 可选 |