服务端 墨西哥v2协议文档
# v2协议文档 - 基于 application/json
## 文档修改说明
| 修改日志 | 改动人 | 改动时间 |
| -------- | ------ | ---------- |
| 1.0 初版 | aitime | 2022/12/06 |
### 1.使用须知
1.最新api版本v1版本
2.接⼝⽀持协议类型https
3.请求均为 POST请求
| 环境 | 后台管理地址 | 请求地址 |
| ---- | --------------------------------------- | --------------------------------------- |
| pord | https://mexico-min-shield.aitime.credit | https://mexico-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/v2/ocr`
**请求方式**:`POST`
**请求数据类型**:`application/json`
**响应数据类型**:`*/*`
**接口描述**:
**请求头参数**:
| 参数名称 | 参数说明 | 数据类型 | 是否必须 |
| ----------- | ------------------- | -------- | -------- |
| X-ADVAI-KEY | 服务端openAccessKey | string | true |
**请求示例**:
```json
{
"cardType": "FRONT",
"country": "MEXICO",
"imageType": "BASE64",
"image": "data:image/jpeg;base64,xxxxxx"
}
```
**请求参数**:
| 参数名称 | 参数说明 | 数据类型 | 是否必须 |
| --------- | ---------------------------------- | -------- | -------- |
| cardType | Issue authority of the card(FRONT) | string | true |
| country | country(MEXICO) | string | true |
| imageType | Image type(BASE64) | string | true |
| image | image of the card | string | 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 |
| ---------- | ------------------------------ | ------ | ------ |
| name | Name of the person | string | |
| birthday | Date of birth of the person | string | |
| idNumber | ID number of the person (CURP) | string | |
| gender | Gender of the person | string | |
| addressAll | Address detail information | string | |
| postalCode | Pin code in the address | string | |
**响应示例**:
<img src="https://chile-api-shield.aitime.credit/img/figure/mexico-2.png" style="zoom:50%;" />
```json
{
"code": "SUCCESS",
"data": {
"backValue": null,
"cardSide": "FRONT",
"frontValue": {
"addressAll": "C TAMAULIPAS 553 A FRACCSAN MIGUEL28985 VILLA DE ALVAREZ,COL",
"birthday": "16/07/1987",
"gender": "H",
"idNumber": "PERM870716HCMRJR00",
"name": "PEREZ ROJAS MARTIN OSWALDO",
"postalCode": "28985"
}
},
"extra": null,
"message": "OK",
"pricingStrategy": "PAY",
"transactionId": "361820183350981"
}
{
"code": "SUCCESS",
"data": {
"backValue": null,
"cardSide": "FRONT",
"frontValue": {
"addressAll": "C SINNOMBRE S/N PBLO LOSALGODONES21970 MEXICALI.B.C",
"birthday": "29/06/1982",
"gender": "M",
"idNumber": "RABL820629MBCNRR04",
"name": "RANGEL BERMUDEZ LAURA PAULA",
"postalCode": "21970"
}
},
"extra": null,
"message": "OK",
"pricingStrategy": "PAY",
"transactionId": "361819742748357"
}
```
## 2. 人脸比对-基于AiTime sdk
**接口地址**:`/api/shield-open/v2/face/living/check`
**请求方式**:`POST`
**请求数据类型**:`application/json`
**响应数据类型**:`*/*`
**接口描述**:
**请求头参数**:
| 参数名称 | 参数说明 | 数据类型 | 是否必须 |
| ----------- | ----------------------------- | -------- | -------- |
| X-ADVAI-KEY | 服务端openAccessKey(后台获取) | string | true |
**请求示例**:
```json
{
"country": "MEXICO",
"resource": "353669007072773",
"imageType": "BASE64",
"image": "data:image/jpeg;base64,xxxxxx"
}
```
**请求参数**:
| 参数名称 | 参数说明 | 是否必须 | 数据类型 |
| --------- | -------------------------- | -------- | -------- |
| country | country(MEXICO) | true | string |
| resource | Authentication resource id | true | string |
| imageType | Image type(BASE64) | true | string |
| image | image | 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属性说明**
**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/v2/face-comparison`
**请求方式**:`POST`
**请求数据类型**:`application/json`
**响应数据类型**:`*/*`
**接口描述**:
**请求头参数**:
| 参数名称 | 参数说明 | 数据类型 | 是否必须 |
| ----------- | ------------------- | -------- | -------- |
| X-ADVAI-KEY | 服务端openAccessKey | string | true |
**请求示例**:
```javascript
{
"country": "MEXICO",
"imageType": "BASE64",
"firstImage": "data:image/jpeg;base64,xxxxxx",
"secondImage": "data:image/jpeg;base64,xxxxxx"
}
```
**请求参数**:
| 参数名称 | 参数说明 | 是否必须 | 数据类型 |
| ----------- | ------------------ | -------- | -------- |
| country | country(MEXICO) | true | string |
| imageType | Image type(BASE64) | true | string |
| firstImage | Living photo | true | string |
| secondImage | Certificate photo | 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属性说明**
| 属性名称 | 说明 | 类型 | 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/v2/face/download`
**请求方式**:`POST`
**请求数据类型**:`application/json`
**响应数据类型**:`*/*`
**接口描述**:
**请求头参数**:
| 参数名称 | 参数说明 | 数据类型 | 是否必须 |
| ----------- | ------------------- | -------- | -------- |
| X-ADVAI-KEY | 服务端openAccessKey | string | true |
**请求示例**:
```json
{
"resource": "353669007072773"
}
```
**请求参数**:
| 参数名称 | 参数说明 | 是否必须 | 数据类型 |
| -------- | -------------------------- | -------- | -------- |
| resource | Authentication resource id | true | string |
**响应参数**:
文件流
**响应示例**:
```json
```
## 5. 查询活体人脸图片-base64
**接口地址**:`/api/shield-open/v2/face/img`
**请求方式**:`POST`
**请求数据类型**:`application/json`
**响应数据类型**:`*/*`
**接口描述**:
**请求头参数**:
| 参数名称 | 参数说明 | 数据类型 | 是否必须 |
| ----------- | ------------------- | -------- | -------- |
| X-ADVAI-KEY | 服务端openAccessKey | string | true |
**请求示例**:
```json
{
"resource": "353669007072773"
}
```
**请求参数**:
| 参数名称 | 参数说明 | 是否必须 | 数据类型 |
| -------- | -------------------------- | -------- | -------- |
| resource | Authentication resource id | 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"
}
```