# 接口名称：身份证OCR(含头像)

#### 描述：传入身份证照片，扫描识别身份证信息并返回，如果传的是正面照片只返回正面信息，如果传的是反面只返回反面信息

>图片要求：格式为 jpg或png，宽和⾼大于 8px，⼩于等于4000px，大小不能超过1MB

请求地址 url：https://api.shuliancloud.com/v2/idcard/ocr
请求方式 method：post
参数：

|  名称 |  类型 |是否必填   | 说明  |
| ------------ | ------------ | ------------ | ------------ |
| appid  |  varchar |  是 | 服务商分配的唯一标识  |
| timestamp |  number | 是  | 当前时间的毫秒数  |
| sign  | varchar  | 是  | 签名，<a href='#sign'>签名算法说明</a>  |
| image| varchar| 否| 图片base64字符串，image、url二选一|
| url | varchar | 否 | 图片url，image、url二选一|



<a name="sign">

#### 签名算法说明：
######  服务商分配的appid、当前时间毫秒数timestamp、商户分配的app_security、 三者通过&符号拼接成字符串进行md5加密得到。
     如：appid=xyzxyzxyz，timestamp=1555378976238，app_security=efcefcefcefcefc ;
     拼接后的字符串：str=xyzxyzxyz&1555378976238&efcefcefcefcefc ;
     加密后得到sign = md5(str) = 4e7e1974b79f3656aeaf03f1158f5d5d ;
</a>

#### 正面返回：
```
{
    "msg": "成功",
    "success": true,
    "code": 200,
    "data": {
        "order_no": "634416423342575616",
        "result": 0,
        "side": "front",
        "info": {
            "number": "320382198912014010",
            "address": "江苏省苏州市岔河镇东沙庄村黄庄150号",
            "month": "12",
            "nation": "汉",
            "year": "1989",
            "sex": "男",
            "name": "赵宁宁",
            "day": "1"
        },
        "validity": {
            "birthday": true,
            "number": true,
            "address": true,
            "sex": true,
            "name": true
        },
        "image_url": "https://img.../16974...jpg"
    }
}
```
#### 反面返回

```
{
    "msg": "成功",
    "success": true,
    "code": 200,
    "data": {
        "order_no": "634436714873622528",
        "result": 0,
        "side": "back",
        "info": {
            "authority": "杭州市公安局余杭分局",
            "timelimit": "20180806-20380806"
        },
        "validity": {
            "authority": true,
            "timelimit": true
        },
        "image_url": null
    }
}
```

#### 错误返回：
```
{
    "msg": "参数错误",
    "success": false, 
    "code": 400, 
    "data": { }
}
```

#### 返回字段说明：

|  字段名 | 说明  |  
| ------------ | ------------ |
| success  | 接口请求成功标识，true为成功，false为失败，失败情况下，会有对应描述和状态码  |   
| code  |成功为200，其它为失败状态码   | 
| msg  | code对应的说明描述   | 
| data  | 验证结果详细信息|  
| order_no  | 订单号|
| result | 扫描成功 0 收费；扫描失败 1 不收费
|side | 身份证⽅方向信息。front 代表身份证正面(⼈像面)， back 代表身份证反面(国徽⾯)
|info|身份证信息，分正面和反面，见详情
|validity|扫描成功结果，分正面和反面，见详情
|image_url| 身份证头像照片URL

#### info返回字段
| 字段名 | 说明
|----------|----------|
|name| 姓名
| sex   |性别
| nation | 民族
|year | 出⽣年
|month | 出⽣月
| day | 出⽣日
|address | 地址
|number | 身份证号
| authority | 签发机关
| timelimit |身份证有效期

上传身份证正面照片时返回字段 name , sex , nation , year , mouth , day , address ，number ，上传身份证背面照⽚时返回字段 authority 和 timelimit 
       
#### validity返回字段
| 字段名 | 说明
|----------|----------|
|birthday|生日
|number|身份证号
|address|地址
|sex  |性别
|name |姓名
|authority|签发机关
|timelimit|身份证有效期

上传身份证正面照片时返回字段 name , sex , birthday , address，number ， 上传身份证背⾯照片时返回字段 authority 和 timelimit

当上传的图⽚是⾮身份证图⽚片时，系统不会报错，但这种情况下就需要关注 validity 中的信息，如有false，说明对应识别结果不可信

#### code错误码说明
|  code |  说明 |
| ------------ | ------------ |
| 200  | 成功  |
| 400  | 参数错误   |
| 404  | 请求资源不存在   |
| 500  | 系统内部错误，请联系服务商   |
| 501  |第三方服务异常
| 601  | 服务商未开通接口权限 |
| 602  | 账号停用 |
| 603  | 次数不足，请购买套餐 |
| 604  | 接口停用 |
|606|调用超限，请联系服务商|
|1001|其他，以实际返回为准