ecologyDoc/AI/腾讯人脸增强版接口.md

### 注意事项
1. 以下接口请求头必须加入`Authorization`，值为授权token([如何获取token](../core/Token使用文档.md))
2. 接口数据格式 `Json`

### 合作方后台上传身份信息
> 合作方后台上传身份信息，活体+比对需传入自带源照片；活体+核身需传入姓名、身份证号<br>
> 请求方式  ` POST http://172.20.109.105:7007/tech/ai/face/faceAdv` <br> 


| 请求参数  || 类型 | 是否必填 | 说明 |
| --- | --- |--- | --- | --- | 
| async || boolean| 否 | 是否开启异步反馈模式，默认为false |
| extData  || | 否 | 附加参数登记，详见[接口调用附加信息登记](./接口调用附加信息登记.md) |
| userId || String| 是 | 用户ID ，用户的唯一标识（不能带有特殊字符)。<br/>同一个用户的 userId 请保持一致，不同用户请不要使用同一个userId  | 
| type || String| 是 | 活体+自带源比对传入 match <br/>活体+权威源比对传入 authmatch | 
| sourcePhotoStr || -| - | 活体+自带源比对时必须传入 |
|| origin | String| 否 | sourcePhotoStr的数据类型。<br/> base64字符串：self (**base64内容需在400k以内**)<br/>来自文件服务器：fds （**带压缩效果，推荐使用，详见[fds使用文档](../file/文件服务器接口.md)）**<br/>图片链接：uri <br/>默认为 self |
|| data | String| 是 | 图片数据（base64，文件服务器文件路径或链接） |
| name || String| 否 | 姓名，活体+权威源比对时必须传入 | 
| idNo || String| 否 | 身份证号，活体+权威源比对时必须传入 | 


| 返回参数  || | 类型 | 是否必返 | 说明 |
| --- | --- | --- |--- | --- | --- |
| errcode ||| Num| 是 | 0交易成功<br>其它为异常情况 |
| errmsg ||| String | 否 | errcode不为0时有值 | 
| data| || - | - | 包含数据见下 |
| |status || String | 是 | “success”为业务成功 |
| |traceNo || String | 是 | 当前业务的唯一id |
| |result|| String | 是 | 业务结果 |
| ||bizSeqNo | String | 否 | 业务流水号 |
| ||orderNo | String | 否 | 订单编号 |
| ||faceId | String | 否 | 此次刷脸用户标识，调 SDK 时传入 |
| ||sign | String | 否 | 签名 |
| ||nonce | String | 否 | 随机数 |
| ||appId | String | 否 | 业务流程唯一标识，即 WBappid |

请求示例

```
{
     "async":false,
     "userId":"user123",
     "type":"match",
     "sourcePhotoStr":{
         "origin":"fds",
         "data":"xxxxxxxxxxxxxx.jpg"
     }
}
```

返回示例

```
{
    "errcode":0,
    "data":{
        "status":"SUCCESS",
        "traceNo":"45646513218465123",
        "result":{
            "bizSeqNo":"业务流水号"，
            "orderNo":"合作方订单号", 
            "faceId":"cc1184c3995c71a731357f9812aab988"
        }, 
    },
    "errmsg":"SUCCESS"
}
```

### 人脸核身结果查询
> 查询人脸核身结果<br>
> 请求方式  ` POST http://172.20.109.105:7007/tech/ai/face/faceAdvResult`

| 请求参数  || 类型 | 是否必填 | 说明 |
| --- | ---| --- | --- | --- | 
| async || boolean| 否 | 是否开启异步反馈模式，默认为false |
| extData  || | 否 | 附加参数登记，详见[接口调用附加信息登记](./接口调用附加信息登记.md) |
| orderNo || String| 是 | 订单编号 |
| getFile || String| 否 | 是否需要获取人脸识别的视频和文件，值为1则返回视频和照片、值为2则返回照片、值为3则返回视频；其他则不返回 |


| 返回参数  || | 类型 | 是否必返 | 说明 |
| --- | --- | --- |--- | --- | --- |
| errcode ||| Num| 是 | 0交易成功<br>其它为异常情况 |
| errmsg ||| String | 否 | errcode不为0时有值 | 
| data| || - | - | 包含数据见下 |
| |status || String | 是 | “success”为业务成功 |
| |traceNo || String | 是 | 当前业务的唯一id |
| |result|| String | 是 | 业务结果 |
| ||tencentCode | String | 否 | 腾讯返回错误码 |
| ||tencentMsg | String | 否 | 腾讯返回错误信息|
| ||bizSeqNo | String | 否 | 业务流水号|
| ||transactionTime | String | 否 | 请求接口的时间|
| ||orderNo | String | 否 | 订单编号|
| ||liveRate | String | 否 | 活体检测得分|
| ||similarity | String | 否 | 人脸比对得分|
| ||occurredTime | String | 否 | 进行刷脸的时间|
| ||photo | String | 否 | 人脸核身时的照片，base64 位编码|
| ||video | String | 否 | 人脸核身时的视频，base64 位编码|
| ||sdkVersion | String | 否 | 人脸核身时的 sdk 版本号|
| ||trtcFlag | String | 否 | Trtc 渠道刷脸则标识"Y"|
| ||appId | String | 否 | 腾讯云控制台申请的 appid|

请求示例

```
{
     "async":false,
     "orderNo":"订单编号",
     "getFile":"2"
}
```

返回示例

```
{
    "errcode":0,
    "data":{
        "status":"SUCCESS",
        "traceNo":"45646513218465123",
        "result":{
            "tencentCode":"0",
            "tencentMsg":"请求成功",
            "bizSeqNo":"22041520001184442415491408594474",
            "orderNo":"testReflect1650008613761",
            "occurredTime":"20220415154341",
            "liveRate":"99",
            "similarity":"97.0",
            "photo":"*",
            "video":"*"
        }, 
        

    },
    "errmsg":"SUCCESS"
}
```
### 创建OCR识别订单
> 人脸识别增强版SDK的银行卡、身份证识别签名及订单信息获取<br>
> 请求方式  ` POST http://172.20.109.105:7007/tech/ai/ocr/createOrder` <br> 


| 请求参数  || 类型 | 是否必填 | 说明 |
| --- | --- |--- | --- | --- | 
| async || boolean| 否 | 是否开启异步反馈模式，默认为false |
| extData  || | 否 | 附加参数登记，详见[接口调用附加信息登记](./接口调用附加信息登记.md) |
| userId || String| 是 | 用户ID ，用户的唯一标识（不能带有特殊字符)。<br/>同一个用户的 userId 请保持一致，不同用户请不要使用同一个userId  | 
| ocrType || String| 否 | 识别类型 IDCard-身份证 BankCard-银行卡 |

| 返回参数  || | 类型 | 是否必返 | 说明 |
| --- | --- | --- |--- | --- | --- |
| errcode ||| Num| 是 | 0交易成功<br>其它为异常情况 |
| errmsg ||| String | 否 | errcode不为0时有值 | 
| data| || - | - | 包含数据见下 |
| |status || String | 是 | “success”为业务成功 |
| |traceNo || String | 是 | 当前业务的唯一id |
| |result|| String | 是 | 业务结果 |
| ||bizSeqNo | String | 否 | 业务流水号 |
| ||orderNo | String | 否 | 订单编号 |
| ||sign | String | 否 | 签名 |
| ||nonce | String | 否 | 随机数 |
| ||appId | String | 否 | 业务流程唯一标识，即 WBappid |

请求示例

```
{
     "async":false,
     "userId":"user123",
}
```

返回示例

```
{
    "errcode":0,
    "data":{
        "status":"SUCCESS",
        "traceNo":"45646513218465123",
        "result":{
            "bizSeqNo":"业务流水号",
            "orderNo":"合作方订单号", 
            "sign":"签名", 
            "nonce" :"随机数", 
            "appId":"WBappid"
        }, 
    },
    "errmsg":"SUCCESS"
}
```

### OCR结果查询
> 查询人脸核身结果<br>
> 请求方式  ` POST http://172.20.109.105:7007/tech/ai/ocr/ocrResult`

| 请求参数  || 类型 | 是否必填 | 说明 |
| --- | ---| --- | --- | --- | 
| async || boolean| 否 | 是否开启异步反馈模式，默认为false |
| extData  || | 否 | 附加参数登记，详见[接口调用附加信息登记](./接口调用附加信息登记.md) |
| orderNo || String| 是 | 订单编号 |
| ocrType || String| 否 | 识别类型 IDCard-身份证 BankCard-银行卡 |
| getNative || String| 否 | 是否需要映射身份证号籍贯信息，值为1则返回映射信息(ocrType为IDCard时可选,其他类型无效) |
| getFile || String| 否 | 是否需要获取 OCR 图片文件。1-返回文件；其他则不返回 |



| 返回参数（身份证）| | | 类型 | 是否必返 | 说明 |
| --- | --- | --- |--- | --- | --- |
| errcode ||| Num| 是 | 0交易成功<br>其它为异常情况 |
| errmsg ||| String | 否 | errcode不为0时有值 | 
| data| || - | - | 包含数据见下 |
| |status || String | 是 | “success”为业务成功 |
| |traceNo || String | 是 | 当前业务的唯一id |
| |result|| String | 是 | 业务结果 |
| ||tencentCode | String | 否 | 腾讯返回错误码 |
| ||tencentMsg | String | 否 | 腾讯返回错误信息|
| ||bizSeqNo | String | 否 | 业务流水号|
| ||transactionTime | String | 否 | 请求接口的时间|
| ||orderNo | String | 否 | 订单编号|
| ||appId | String | 否 | 腾讯云控制台申请的 appid|
| ||frontCode | String| 否 |	“0” 说明人像面识别成功|
| ||backCode | String| 否 |	“0” 说明国徽面识别成功|
| ||name | String| 否 |	frontCode为 0 返回：证件姓名|
| ||sex | String| 否 |	frontCode为 0 返回：性别|
| ||nation | String| 否 |	frontCode为 0 返回：民族|
| ||birth | String| 否 |	frontCode为 0 返回：出生日期（例：19920320）|
| ||address | String| 否 |	frontCode为 0 返回：地址|
| ||idcard | String| 否 |	frontCode为 0 返回：身份证号|
| ||validDate | String| 否 |	backCode为 0 返回：证件的有效期（例：20160725-20260725）|
| ||authority | String| 否 |	backCode为 0 返回：发证机关|
| ||frontPhoto | Base64String| 否 |	人像面照片，转换后为 JPG 格式|
| ||backPhoto | Base64String| 否 |	国徽面照片，转换后为 JPG 格式	|
| ||frontCrop | Base64String| 否 |	人像面切边照片，切边图在识别原图少边或者存在遮挡的情况有小概率可能会导致切图失败，该字段会返回空；如切边图为空时建议可使用原图替代	|
| ||backCrop | Base64String| 否 |	国徽面切边照片，切边图在识别原图少边或者存在遮挡的情况有小概率可能会导致切图失败，该字段会返回空；如切边图为空时建议可使用原图替代	|
| ||headPhoto | Base64String| 否 |	身份证头像照片	|
| ||frontWarnCode | String| 否 |	人像面告警码，在身份证有遮挡、缺失、信息不全时会返回告警码；当 frontCode 为0时才会出现告警码，告警码的含义请参考 身份证 OCR 错误码|
| ||backWarnCode | String| 否 |	国徽面告警码，在身份证有遮挡、缺失、信息不全时会返回告警码；当 backCode 为0时才会出现告警码，告警码的含义请参考 身份证 OCR 错误码|
| ||operateTime | String| 否 |	做 OCR 的操作时间（例：2020-02-27 17:08:03）|
| ||frontMultiWarning | String| 否 |	正面多重告警码，含义请参考 身份证 OCR 错误码|
| ||backMultiWarning | String| 否 |	反面多重告警码，含义请参考 身份证 OCR 错误码|
| ||frontClarity | String| 否 |	正面图片清晰度|
| ||backClarity | String| 否 |	反面图片清晰度|
| ||nativePlace | String| 否 |	籍贯信息|

| 返回参数（银行卡）  || | 类型 | 是否必返 | 说明 |
| --- | --- | --- |--- | --- | --- |
| errcode ||| Num| 是 | 0交易成功<br>其它为异常情况 |
| errmsg ||| String | 否 | errcode不为0时有值 | 
| data| || - | - | 包含数据见下 |
| |status || String | 是 | “success”为业务成功 |
| |traceNo || String | 是 | 当前业务的唯一id |
| |result|| String | 是 | 业务结果 |
| ||tencentCode | String | 否 | 腾讯返回错误码 |
| ||tencentMsg | String | 否 | 腾讯返回错误信息|
| ||bizSeqNo | String | 否 | 业务流水号|
| ||transactionTime | String | 否 | 请求接口的时间|
| ||orderNo | String | 否 | 订单编号|
| ||appId | String | 否 | 腾讯云控制台申请的 appid|
| ||code | String | 否 | 0：银行卡识别成功|
| ||msg | String | 否 | 返回结果描述|
| ||bankCardNo | String | 否 | resultCode 为0返回：银行卡号|
| ||bankCardValidDate | String | 否 | resultCode 为0返回：银行卡有效期|
| ||bankcardCropPhoto | Base64 | 否 | String	银行卡切边图片|
| ||bankcardNoPhoto | Base64 | 否 | String	银行卡卡号切边图片|
| ||originBankcardPhoto | Base64 | 否 | String	识别原始图片|
| ||warnCode | String | 否 | 银行卡告警码，在银行卡日期失效或者过期会提示；当 frontCode 为0时才会出现告警码，告警码的含义请参考通用响应码列表的 银行卡 OCR 错误码|
| ||operateTime | String | 否 | 做 OCR 的操作时间|
| ||multiWarnCode | String | 否 | 多重告警码，含义请参考 银行卡 OCR 错误码|
| ||clarity | String | 否 | 图片清晰度|



请求示例

```
{
     "async":false,
     "orderNo":"订单编号",
     "getFile":"2",
     "ocrType":"IDCard"
}
```

返回示例

```
{
    "errcode":0,
    "data":{
        "status":"success",
        "traceNo":"45646513218465123",
        "result":{
            "tencentCode":"0",
            "tencentMsg":"请求成功",
            "bizSeqNo":"21062120001184438417355807876765",
            "transactionTime":"20210621173558",
            "backCode":"0",
            "orderNo":"h1jw98k72ffe3de249qmf1723673v31v",
            "name":"xxx",
            "sex":"男",
            "nation":"汉",
            "birth":"19881001",
            "address":"xxxxxxxxxx",
            "idcard":"xxxxxxxxxxxxxxxxxx",
            "validDate":"20190128-20390128",
            "authority":"xxxxxx",
            "operateTime":"2021-06-21 17:35:27",
            "frontWarnCode":"00000000",
            "backWarnCode":"00000000",
            "frontMultiWarning":"00000000",
            "backMultiWarning":"00000000",
            "frontClarity":"64",
            "backClarity":"72",
            "nativePlace":"xxxxxxxxxx",
            "success":false,
            "frontCode":"0"
        }, 
    },
    "errmsg":"SUCCESS"
}
```