服务端 智利v1协议文档
# v1协议文档 - 基于 multipart/form-data
## 文档修改说明
| 修改日志 | 改动人 | 改动时间 |
| -------- | ------ | ---------- |
| 1.0 初版 | aitime | 2022/11/15 |
| 补充智利1-2代卡示例 | aitime | 2022/12/05 |
### 1.使用须知
1.最新api版本v1版本
2.接⼝⽀持协议类型https
3.请求均为 POST请求
| 环境 | 后台管理地址 | 请求地址 |
| ---- | ----------------------------------------- | ----------------------------------------- |
| pord | https://chile-min-shield.aitime.credit | https://chile-api-shield.aitime.credit |
### 2.通用返回
所有接⼝的返回类型，⽤来封装错误码或返回数据。所有接⼝的结果都是下⾯的结构。
**返回参数**
| 参数名称 | 说明 | 类型 |
| :------- | :--------- | :----- |
| code | 业务码 | string |
| message | 业务码说明 | string |
| data | 业务数据 | object |
**返回码**
| code | Msg | 备注 |
| :------ | :---- | :--- |
| SUCCESS | OK | 成功 |
| FAIL | ERROR | 异常 |
### 3.通用请求头
| 参数 | 参考值 | 备注 |
| ----------- | ------------------------------------ | --------------- |
| X-ADVAI-KEY | 84b71eaf-72ec-4619-975b-b06fbd5786ed | aitime平台api调用唯一凭证 |
## 1. ocr认证
**接口地址**:`/api/shield-open/v1/ocr`
**请求方式**:`POST`
**请求数据类型**:`multipart/form-data`
**响应数据类型**:`*/*`
**接口描述**:
**请求头参数**:
| 参数名称 | 参数说明 | 数据类型 | 是否必须 |
| ----------- | ------------------- | -------- | -------- |
| X-ADVAI-KEY | 服务端openAccessKey | string | true |
**请求参数**:
| 参数名称 | 参数说明 | in | 数据类型 | 是否必须 |
| -------- | --------------------------------------- | -------- | -------- | -------- |
| cardType | Issue authority of the card(FRONT) | formData | string | true |
| country | country(CHILE) | formData | string | true |
| image | image of the card | formData | file | true |
**响应参数**
| 参数名称 | 说明 | 类型 | schema |
| --------------- | ------------------------------------------------------------ | ------ | ------ |
| code | ID Card OCR Status Code | string | |
| data | | T | Json |
| extra | Extra response info (Exception Message) | string | |
| message | Status Code Explanation | string | |
| pricingStrategy | whether the request will be charged, enum type: `FREE`, `PAY` | string | |
| transactionId | the request id, the max length is 64 | string | |
**schema属性说明**
**Data-Json**
| 属性名称 | 说明 | 数据类型 | schema |
| ---------- | ------------- | -------- | ------ |
| cardSide | FRONT or BACK | string | |
| frontValue | positive data | T | |
| backValue | back data | T | |
**frontValue**
| 属性名称 | 说明 | 类型 | schema |
| -------- | ----------------------- | ---- | ------ |
| surname | 姓氏 | array of strings | |
| sex | 性别 | string | |
| number | 身份证号 | string | |
| issue_date | 发行日置信度 | string | |
| expiry_date | 有效期置信度 | string | |
| document_number | 文档编号置信度 | string | |
| birth | 出生日 | string | |
**响应示例**:
第一代卡
<img src="https://chile-api-shield.aitime.credit/img/figure/chile-1.jpg" style="zoom:50%;" />
```json
{
"code": "SUCCESS",
"data": {
"backValue": null,
"cardSide": "FRONT",
"frontValue": {
"birth": "05 MAYO 1983",
"expiry_date": "05 MAYO 2023",
"given_name": "CLAUDIO CESAR ANTONIO",
"isface": 1,
"issue_date": "25 OCT 2012",
"nationality": "CHILE",
"number": "15.768.798-0",
"number_flag": 0,
"sex": "M",
"surname": [
"CUELLO",
"VALDIVIA"
]
}
},
"extra": "FRONT",
"message": "OK",
"pricingStrategy": "FREE",
"transactionId": "360827122166917"
}
```
第二代卡
<img src="https://chile-api-shield.aitime.credit/img/figure/chile-2.jpg" style="zoom:50%;" />
```json
{
"code": "SUCCESS",
"data": {
"backValue": null,
"cardSide": "FRONT",
"frontValue": {
"birth": "26 ENE 1999",
"document_number": "515.174.305",
"expiry_date": "26 ENE 2023",
"given_name": "YASNAANDREA",
"isface": 1,
"issue_date": "20 ABR 2018",
"nationality": "CHILENA",
"number": "20.145.088-8",
"number_flag": 1,
"sex": "F",
"surname": [
"RAMIREZ",
"OPAZO"
]
}
},
"extra": "FRONT",
"message": "OK",
"pricingStrategy": "FREE",
"transactionId": "360827223243845"
}
```
## 2. 人脸比对-基于AiTime sdk
**接口地址**:`/api/shield-open/v1/face/living/check`
**请求方式**:`POST`
**请求数据类型**:`multipart/form-data`
**响应数据类型**:`*/*`
**接口描述**:
**请求头参数**:
| 参数名称 | 参数说明 | 数据类型 | 是否必须 |
| ----------- | ----------------------------- | -------- | -------- |
| X-ADVAI-KEY | 服务端openAccessKey(后台获取) | string | true |
**请求参数**:
| 参数名称 | 参数说明 | in | 是否必须 | 数据类型 | schema |
| -------- | ----------------- | -------- | -------- | -------- | ------ |
| country | country(CHILE) | formData | true | string | |
| image | image | formData | true | file | |
| resource | Authentication resource id | formData | true | string | |
**响应参数**
| 参数名称 | 说明 | 类型 | schema |
| --------------- | ------------------------------------------------------------ | ------ | ------ |
| code | ID Card OCR Status Code | string | |
| data | | T | Json |
| extra | Extra response info (Exception Message) | string | |
| message | Status Code Explanation | string | |
| pricingStrategy | whether the request will be charged, enum type: `FREE`, `PAY` | string | |
| transactionId | the request id, the max length is 64 | string | |
**schema属性说明**
**data**
| 属性名称 | 说明 | 类型 | schema |
| ---------- | ------------------------------------------------------------ | ------ | ------ |
| similarity | Face similarity score, the recommended threshold is 80 points, such as 100, which means completely similar, and the value is between 0-100 | double | |
**响应示例**:
```json
{
"code": "SUCCESS",
"data": {
"firstFace": {
"bottom": 690.0,
"id": "1",
"left": 173.0,
"right": 339.0,
"top": 492.0
},
"secondFace": {
"bottom": 468.0,
"id": "2",
"left": 133.0,
"right": 335.0,
"top": 211.0
},
"similarity": 0.3
},
"extra": null,
"message": "OK",
"pricingStrategy": "FREE",
"transactionId": "350961988834309"
}
```
## 3. 人脸比对
**接口地址**:`/api/shield-open/v1/face-comparison`
**请求方式**:`POST`
**请求数据类型**:`multipart/form-data`
**响应数据类型**:`*/*`
**接口描述**:
**请求头参数**:
| 参数名称 | 参数说明 | 数据类型 | 是否必须 |
| ----------- | ------------------- | -------- | -------- |
| X-ADVAI-KEY | 服务端openAccessKey | string | true |
**请求参数**:
| 参数名称 | 参数说明 | in | 是否必须 | 数据类型 | schema |
| ----------- | ----------------- | -------- | -------- | -------- | ------ |
| country | country(CHILE) | formData | true | string | |
| firstImage | Living photo | formData | true | file | |
| secondImage | Certificate photo | formData | true | file | |
**响应参数**
| 参数名称 | 说明 | 类型 | schema |
| --------------- | ------------------------------------------------------------ | ------ | ------ |
| code | ID Card OCR Status Code | string | |
| data | | T | Json |
| extra | Extra response info (Exception Message) | string | |
| message | Status Code Explanation | string | |
| pricingStrategy | whether the request will be charged, enum type: `FREE`, `PAY` | string | |
| transactionId | the request id, the max length is 64 | string | |
**schema属性说明**
| 属性名称 | 说明 | 类型 | schema |
| ---------- | ------------------------------------------------------------ | ------ | ------ |
| similarity | Face similarity score, the recommended threshold is 80 points, such as 100, which means completely similar, and the value is between 0-100 | double | |
**响应示例**:
```json
{
"code": "SUCCESS",
"data": {
"firstFace": {
"bottom": 690.0,
"id": "1",
"left": 173.0,
"right": 339.0,
"top": 492.0
},
"secondFace": {
"bottom": 468.0,
"id": "2",
"left": 133.0,
"right": 335.0,
"top": 211.0
},
"similarity": 0.3
},
"extra": null,
"message": "OK",
"pricingStrategy": "FREE",
"transactionId": "350961988834309"
}
```
## 4. 活体检验图片下载
**接口地址**:`/api/shield-open/v1/face/download`
**请求方式**:`POST`
**请求数据类型**:`multipart/form-data`
**响应数据类型**:`*/*`
**接口描述**:
**请求头参数**:
| 参数名称 | 参数说明 | 数据类型 | 是否必须 |
| ----------- | ------------------- | -------- | -------- |
| X-ADVAI-KEY | 服务端openAccessKey | string | true |
**请求参数**:
| 参数名称 | 参数说明 | in | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
| resource | Authentication resource id | formData | true | string | |
**响应参数**:
文件流
**响应示例**:
```json
```
## 5. 查询活体人脸图片-base64
**接口地址**:`/api/shield-open/v1/face/img`
**请求方式**:`POST`
**请求数据类型**:`multipart/form-data`
**响应数据类型**:`*/*`
**接口描述**:
**请求头参数**:
| 参数名称 | 参数说明 | 数据类型 | 是否必须 |
| ----------- | ------------------- | -------- | -------- |
| X-ADVAI-KEY | 服务端openAccessKey | string | true |
**请求参数**:
| 参数名称 | 参数说明 | in | 是否必须 | 数据类型 | schema |
| -------- | -------- | -------- | -------- | -------- | ------ |
| resource | Authentication resource id | formData | true | string | |
**响应参数**
| 参数名称 | 说明 | 类型 | schema |
| -------- | ---- | ------ | ----------------- |
| data | | T | QueryFaceImagesVo |
| message | | string | |
| code | | string | |
**schema属性说明**
**QueryFaceImagesVo**
| 属性名称 | 说明 | 类型 | schema |
| --------- | ------------ | ------ | ------ |
| image | image | string | |
| imageType | Image type(BASE64) | string | |
**响应示例**:
```json
{
"code": "SUCCESS",
"data": {
"image":"data:image/jpeg;base64,xxxxxxx",
"imageType":"BASE64"
},
"message": "OK"
}
```