提交身份证件中的个人信息

/aivpersonidtfy

Method : POST
URL : https://xxx.finexusgroup.com/AIV/rest/v1/aivpersonidtfy

信息

这个方法允许提交一个请求，根据提交的图像检查身份证件的真实性，并从身份证件中提取个人信息。

响应将包括：

• 评估身份证件图像是否是真实文件的各种标志检查，并确定该文件是否被视为真实。
• 将返回可以从文件中提取的所有信息。

请求

请求参数

字段名	必需	类型	描述	示例
sourceInfo	是	对象	来源信息。	参阅下文说明
interactionMode	是	对象	交互模式。	参阅下文说明
language	可选	字符串	语言。	"en"
device	可选	对象	设备信息。	参阅下文说明
idType	是	字符串	ID 类型。	"mykad"
idNo	是	字符串	ID 号码。	"97XXXXXXXXXX"
nationality	是	字符串	国籍。	"MY"
fullName	是	字符串	全名。	"Wong XXX XXX"
idImage	是	对象	ID 图片。	参阅下文说明

对象: sourceInfo

字段名	必需	类型	描述	示例
source	是	字符串	来源。	"FNXCRDS"
partnerId	是	字符串	合作伙伴 ID。	"BSSS"
productType	可选	字符串	合作伙伴类型。	"appTest"
reference	是	字符串	参考。	"2003160192931"
apiVersion	是	字符串	API 版本。	"1.6"
apiKey	有条件	字符串	API 密钥。	"123-KEJRU-001"
userId	可选	字符串	用户 ID。	"mkchan"
userToken	可选	字符串	用户令牌。	"APPOKJSID8J1234"

对象: interactionMode

字段名	必需	类型	描述	示例
mode	是	字符串	模式。	"SYNC"
callbackUrl	可选	字符串	回调 URL。

对象: device

字段名	必需	类型	描述	示例
brand	是	字符串	设备品牌。	"Vivo"
model	是	字符串	设备型号。	"vivo 2005"
imei	可选	数字	国际移动设备识别码（IMEI）号码。	"890077890908976"
mac	可选	字符串	媒体访问控制地址（MAC 地址）。	"00:11:22:33:44:55"

对象: idImage

字段名	必需	类型	描述	示例
imageFront	是	对象	身份证正面图像内容。	参阅下文说明
imageBack	有条件	对象	身份证背面图像内容（条件性）。	参阅下文说明

对象: imageFront

字段名	必需	类型	描述	示例
contentEncoding	是	字符串	图像的编码格式。	"base64"
contentMediaType	是	字符串	图像数据的媒体类型。	"jpeg"
image	是	字符串	完整的图像数据。	"/9j/4AAQSkZJRgABAQ"

对象: imageBack

字段名	必需	类型	描述	示例
contentEncoding	是	字符串	图像的编码格式。	"base64"
contentMediaType	是	字符串	图像数据的媒体类型。	"jpeg"
image	是	字符串	完整的图像数据。	"/9j/4AAQSkZJRgABAQ"

响应

响应代码

响应代码	描述	响应架构
200	服务能够验证并允许调用者使用该服务和方法。	AIVPersonIdtfyPostResponse
400	服务无法找到预期的消息布局，因此出现错误的请求。	N/A
401	未经授权的访问 - 无法验证源系统。	N/A
405	禁止访问 - 源系统未经授权执行操作。	N/A

响应参数

字段名称	必填	类型	描述	示例
status	是	对象	状态。	参阅下文说明。
payload	可选	对象	真实性检查信息。	参阅下文说明。

对象：status

字段名称	必填	类型	描述	示例
sourceInfo	是	对象	源信息。	参阅下文说明。
status	是	字符串	状态。	"SUCCESS"
errorList	是	对象	错误列表。	参阅下文说明。

对象：sourceInfo

字段名称	必填	类型	描述	示例
source	是	字符串	源。	"FNXCRDS"
partnerId	是	字符串	合作伙伴 ID。	"BSSS"
productType	可选	字符串	合作伙伴类型。	"appTest"
reference	是	字符串	参考。	"2003160192931"
apiVersion	是	字符串	API 版本。	"1.6"
apiKey	条件性	字符串	API 密钥。	"123-KEJRU-001"
userId	可选	字符串	用户 ID。	"mkchan"
userToken	可选	字符串	用户令牌。	"APPOKJSID8J1234"

对象：errorList

字段名称	必填	类型	描述	示例
msgCode	是	字符串	消息代码。	"000"
msgText	是	字符串	消息文本。

对象：payload

字段名称	必填	类型	描述	示例
landmark	是	对象	地标。	参阅下文说明。
aivRefId	是	字符串	AIV 参考 ID。	"205"
idType	可选	字符串	ID 类型。	"mykad"
extractedData	可选	对象	从 MyKad 或护照图像中提取的信息。	参阅下文说明。
possibleFraud	是	字符串	可能的欺诈。	"t"
qualityOfIdImage	是	字符串	ID 图像的质量。	"t"
insufficientLandmarkDetection	是	字符串	不足的地标检测。	"t"
recommendation	是	对象	建议。	参阅下文说明。

对象：landmark

字段名称	必填	类型	描述	示例
landmarkResult	是	对象	ID 证件地标检查结果。	参阅下文说明。
landmarkDetails	是	对象	MyKad 或护照 ID 证件地标检查结果。	参阅下文说明。

对象：landmarkResult

字段名称	必填	类型	描述	示例
totalNo	是	数字	定义的地标总数。	"10"
matchedNo	是	数字	匹配的地标数。	"0"
threshold	是	数字	被视为真实 ID 证件图像的匹配阈值数。	"4"
authenticityFlg	是	字符串	真实性标志。	"F"

对象：landmarkDetails（适用于 MyKad）

字段名称	必填	类型	描述	示例
citizenFlg	是	字符串	公民标志。	"t"
icPlateMatch	是	字符串	身份证号码匹配。	"t"
myKadLogoMatch	是	字符串	MyKad 徽标匹配。	"t"
myFlagMatch	是	字符串	马来西亚国旗匹配。	"t"
ghostMatch	是	字符串	肖像图匹配。	"t"
coatOfArmsMatch	是	字符串	国徽徽标匹配。	"t"
TnGLogoMatch	是	字符串	TnG 徽标匹配。	"t"
chipLogoMatch	是	字符串	芯片徽标匹配。	"t"
ketuaPengarahTextFound	是	字符串	发现 Ketua Pengarah 文本。	"t"
genderMatch	是	字符串	性别匹配。	"t"
validBirthYear	是	字符串	有效出生年份。	"t"

对象：landmarkDetails（适用于护照）

字段名称	必填	类型	描述	示例
documentTypeMatch	是	字符串	文档类型匹配。	"t"
issuingStateCodeMatch	是	字符串	签发国家代码匹配。	"t"
passportNoMatch	是	字符串	护照号码匹配。	"t"
expiredDocument	是	字符串	过期文档。	"t"
validMrz	是	字符串	有效的机读区。	"t"
primaryNameMatch	可选	字符串	主要名称匹配。	"t"
secondaryNameMatch	可选	字符串	次要名称匹配。	"t"
dateOfBirthMatch	可选	字符串	出生日期匹配。	"t"
dateOfExpiryMatch	可选	字符串	到期日期匹配。	"t"

对象：extractedData（适用于 MyKad）

字段名称	必填	类型	描述	示例
myKadNo	是	字符串	MyKad 号码。	"890221-58-9666"
fullName	是	字符串	全名。	"John Smith"
address	是	对象	地址。	参阅下文说明。
gender	是	字符串	性别。	"M"
placeOfBirth	是	字符串	出生地。	"Kuala Lumpur"
holderImage	是	对象	MyKad 持有者的脸部图像。	参阅下文说明。
muslimFlg	是	字符串	穆斯林标志。	"t"

对象：address

字段名称	必填	类型	描述	示例
addrLine1	是	字符串	地址行 1。	"5, Jalan 3"
addrLine2	可选	字符串	地址行 2。	"Sea Park"
addrLine3	可选	字符串	地址行 3。
city	是	字符串	城市。	"Petaling Jaya"
state	是	字符串	州。	"Selangor"
country	条件必填	字符串	国家代码。	"MY"
postcode	是	数字	邮政编码。	"46300"

对象：holderImage

字段名称	必填	类型	描述	示例
contentEncoding	是	字符串	图像的编码格式。	"base64"
contentMediaType	是	字符串	图像数据的媒体类型。	"jpeg"
image	是	字符串	整个图像数据。	"/9j/4AAQSkZJRgABAQ"

对象：extractedData（适用于护照）

字段名称	必填	类型	描述	示例
issuingStateName	是	字符串	签发国家名称。	"Malaysia"
documentName	是	字符串	文档名称。	"Test"
documentType	是	字符串	文档类型。	"P"
issuingStateCode	是	字符串	签发国家代码。	"MY"
passportNo	是	字符串	护照号码。	"A123456"
primaryName	可选	字符串	姓氏。	"Smith"
secondaryName	可选	字符串	名字。	"John"
fullName	可选	字符串	全名。	"John Smith"
nationality	是	字符串	国籍。	"Malaysia"
dateOfBirth	是	字符串	出生日期。	"01 MAY 2000"
holderIdNo	是	字符串	持有者的国家 ID 号码。	"1234567890"
gender	是	字符串	性别。	"M"
placeOfBirth	是	字符串	出生地。	"Kuala Lumpur"
dateOfIssue	是	字符串	发行日期。	"01 NOV 2010"
issuingAuthority	是	字符串	签发机构。	"Test"
dateOfExpiry	是	字符串	到期日期。	"01 NOV 2015"
holderPortrait	是	对象	持有者的面部图像。	参阅下文说明。
holderMark	可选	对象	持有者的指纹或签名图像。	参阅下文说明。

对象：holderPortrait

字段名称	必填	类型	描述	示例
contentEncoding	是	字符串	图像的编码格式。	"base64"
contentMediaType	是	字符串	图像数据的媒体类型。	"jpeg"
image	是	字符串	整个图像数据。	"/9j/4AAQSkZJRgABAQ"

对象：holderMark

字段名称	必填	类型	描述	示例
contentEncoding	是	字符串	图像的编码格式。	"base64"
contentMediaType	是	字符串	图像数据的媒体类型。	"jpeg"
image	是	字符串	整个图像数据。	"/9j/4AAQSkZJRgABAQ"

对象：recommendation

字段名称	必填	类型	描述	示例
result	是	字符串	结果。	"T"
score	是	字符串	分数。	"100"
identificationCheck	是	对象	身份验证检查。	参阅下文说明。
threshold	是	字符串	阈值。	"80"

对象：identificationCheck

字段名称	必填	类型	描述	示例
result	是	字符串	结果。	"T"
score	是	字符串	分数。	"20"
threshold	是	字符串	阈值。	"10"
type	是	字符串	类型。	"Landmark"
maxScore	是	字符串	最大分数。	"20"

示例消息

请求

/aivpersonidtfy POST 请求

curl -X POST "https://xxx.finexusgroup.com/AIV/rest/clientauth/aivpersonidtfy" \
 -H "Accept: application/json" \
 -H "Content-Type: application/json" \ 
 -d '{
          "sourceInfo": {
          "source": "test",
          "partnerId": "test",
          "productType": "appTest",
          "reference": " AIVref220610181940",
          "apiVersion": "1.6",
          "apiKey": "",
          "userId": "",
          "userToken": ""
          },
          "interactionMode": {
          "callbackUrl": "",
          "mode": "SYNC"
          },
          "idType": "mykad",
          "language":"en",
          "fullName": "Wong XXX XXX",
          "nationality": "MY",
          "idNo": "97XXXXXXXXXX",
          "idImage": {
               "imageFront": {
                    "image": "iVBORw0KGgoAAAANSUhEUgAAAtsAAAH",
                    "contentMediaType": "image/jpeg",
                    "contentEncoding": "base64"
               },
               "imageBack": {
                    "image": "iVBORw0KGgoAAAANSUhEUgAAApkAAAG",
                    "contentMediaType": "image/jpeg",
                    "contentEncoding": "base64"
               }
          },
          "device": {
               "imei": "",
               "model": "",
               "brand": "",
               "mac": ""
          }
     }'

响应

/aivpersonidtfy POST 响应

{
    "status": {
        "sourceInfo": {
            "reference": "2003160192931",
            "apiVersion": "1.6",
            "apiKey": "ABC1234567",
            "source": "FNXCARDS",
            "partnerId": "BSSS",
            "productType": "Card Application",
            "userId": "mkchan",
            "userToken": "APPOKJSID8J1234"
        },
        "errorList": [
            {
                "msgText": "",
                "msgCode": ""
            }
        ],
        "status": "SUCCESS"
    },
    "payload": {
        "possibleFraud": "t",
        "qualityOfIdImage": "t",
        "idType": "mykad",
        "extractedData": {
            "placeOfBirth": "Kuala Lumpur",
            "myKadNo": "000000000000",
            "address": {
                "addrLine1": "No.1, Jalan Pangkor",
                "addrLine2": "Titiwangsa Sentral",
                "addrLine3": "",
                "city": "Kuala Lumpur",
                "postcode": "50000",
                "state": "W.P. Kuala Lumpur",
                "country": "MY"
            },
            "muslimFlag": "f",
            "gender": "M",
            "holderImage": {
                "image": "/9j/4AAQSkZJRgABAQ",
                "contentMediaType": "jpeg",
                "contentEncoding": "base64"
            },
            "fullName": "John Smith"
        },
        "recommendation": {
            "result": "F",
            "score": 70,
            "identificationCheck": [
                {
                    "result": "T",
                    "score": 25,
                    "threshold": 20,
                    "type": "Landmarks",
                    "maxScore": 25
                },
                {
                    "result": "T",
                    "score": 25,
                    "threshold": 20,
                    "type": "Name",
                    "maxScore": 25
                },
                {
                    "result": "T",
                    "score": 25,
                    "threshold": 20,
                    "type": "MyKadNo",
                    "maxScore": 25
                },
                {
                    "result": "T",
                    "score": 25,
                    "threshold": 20,
                    "type": "address",
                    "maxScore": 25
                }
            ],
            "threshold": 85
        },
        "insufficientLandmarkDetection": "f",
        "landmark": {
            "landmarkDetails": {
                "icPlateMatch": "f",
                "chipLogoMatch": "f",
                "myKadLogoMatch": "f",
                "coatOfArmsMatch": "f",
                "portraitMatch": "f",
                "citizenFlg": "f",
                "TnGLogoMatch": "f",
                "myFlagMatch": "f",
                "ketuaPengarahTextFound": "f"
            },
            "landmarkResult": {
                "authenticityFlg": "F",
                "matchedNo": 0,
                "totalNo": 10,
                "threshold": 4
            }
        },
        "aivRefId": "205"
    }
}