TrustDecision
API Reference
English

OCR API V2.0

Base URL

调用方法

URL请求方式Content Type输出格式字符集
api-base-url?partner_code=xxx&partner_key=xxxPOSTapplication/jsonJSONUTF-8

认证入参

字段名字段类型含义建议备注
partner_codeString合作方标识必须由TD分配
partner_keyString合作方秘钥必须由TD分配

请求参数

字段类型含义建议备注
imageString证件图片必须JPG、JPEG、PNG的base64编码图⽚字符串，图⽚不能超过2M
countryString国家必须国家，必填。两位国家码(大写)，符合 ISO 3166 标准。如墨西哥：MX
scenarioString场景必须枚举值：Ocr
optionsString其他额外返回值可选枚举值：
1. images：返回证件照片、人脸、签名等截取图片
2. image_quality：返回证件图像质量相关的参数
3. document_forgery：返回证件伪造检测相关的参数
参数可多选，用逗号间隔，例如images, image_quality, document_forgery

OCR图片规范和要求

要求类别具体规范和要求
证件放置要求- 确保证件位于图片中央，确保所有四周边缘清晰可见，避免遮挡或裁切。
- 维持证件原始的长宽比例，避免任何变形。
- 避免使用非真实的在线样本（例如从网络下载的图片）、模糊不清的照片、边角缺失的证件以及严重扭曲的图像。
图片质量要求- 在光线充足但均匀的环境下拍摄，避免强烈的直射光或阴影。
- 使用单一且最好是浅色的背景，避免复杂的图案或纹理。
- 确保图片清晰可辨，没有模糊或过度曝光的现象。
图片规格要求- 图片文件大小建议在 100KB 至 500KB 之间，以保持较快的上传速度及良好的处理效率，同时避免因过度压缩而影响识别质量。

标准图片参考样例：

RUNOOB 图标

非标准图片参考样例：

响应参数

字段类型含义备注
codeIntegerAPI 状态码
messageString状态信息在 API 异常状态下会输出具体的异常原因
sequence_idString响应唯一码用于跟踪每次请求记录的唯一标识
resultString证件校验结果枚举值：
1. success：如果证件类型可以被识别正确，证件未过期，MRZ正确，证件上的字段格式符合要求，则返回success
2. error：如果上述证件类型校验、证件过期校验、MRZ校验、证件字段格式校验任何一个未通过，则返回error。
该情况下只代表校验失败，不代表OCR解析失败，在card_info字段中仍然可能会返回OCR的解析信息。
3. not performed：未执行检查（几乎不可能遇到）
status_infoObject证件校验详情上述result结果的详细信息，包括对证件类型、有效期、MRZ和文本字段格式的校验结果。
请参考StatusInfo数据对象
document_type_infoObject证件类型信息默认出参。
请参考DocumentTypeInfo数据对象
card_infoObject证件信息证件OCR结果会在这个模块返回，可通过该字段是否有返回结果来判断OCR结果。
即使result字段的返回值为error，该字段仍可能返回OCR的解析信息
请参考CardInfo数据对象
image_infoObject图片信息入参选择时则返回。
请参考ImageInfo数据对象
image_quality_infoObject图片质量信息入参选择时则返回。
请参考ImageQualityInfo数据对象
document_forgeryObject证件伪造检测入参选择时则返回。
请参考DocumentForgeryInfo数据对象

数据对象

  • StatusInfo
    字段类型含义备注
    doc_typeInteger检验证件类型可否被识别参考CheckResult 数据字典
    expiryInteger校验证件是否过期参考CheckResult 数据字典
    mrzInteger校验MRZ是否识别正确参考CheckResult 数据字典
    textInteger校验证件上的字段格式是否符合要求参考CheckResult 数据字典
    {
        "doc_type":1,
        "expiry":0,
        "mrz":1,
        "text":1
}
  • DocumentTypeInfo
    字段类型含义备注
    document_nameString证件名称
    document_descriptionStrin证件类型Identity Card, Passport, Driving License等等。
    {
        "document_name":"Philippines - ePassport (2016)",
        "document_description":"Passport"
}
  • CardInfo
    字段类型含义备注
    field_listArray/Object文本字段名称列表
    field_list.field_nameString文本字段名称
    fieldList.lcidIntegerLCID 类型参考LCID数据字典
    field_list.validity_statusInteger文本字段有效状态校验文本字段格式是否符合要求。
    参考CheckResult 数据字典
    field_list.value_listArray文本字段值列表
    field_list.value_list.original_valueString文本字段原始值证件上的字段原始值
    field_list.value_list.valueString文本字段解析后的值根据字段原始值解析后的值。例如，对于日期格式的字段，解析后的值统一为YYYY-MM-DD格式
  • {
    "field_list":[
        {
            "field_name":"Date of Expiry",
            "lcid":0,
            "validity_status": 1,
            "value_list":[
                {
                    "original_value":"23/08/2024",
                    "value":"2024-08-23"
                }
            ]
        },
        {
            "field_name":"Date of Birth",
            "lcid":0,
            "validity_status": 1,
            "value_list":[
                {
                    "original_value":"01/01/1979",
                    "value":"1979-01-01"
                }
            ]
        }
    ]
}
  • ImageInfo
    字段类型含义备注
    field_listObject图像字段名称列表
    field_list.field_nameString图像字段名称
    field_list.value_listObject图像字段值列表
    field_list.value_list.valueString图像字段值图像，Base64 格式。
    {
    "field_list":[
        {
            "field_name":"Portrait",
            "value_list":[
                {
                    "value":"/4AAQSkZJRgABAQEBHwEfAADxxxxxx"
                }
            ]
        },
        {
            "field_name":"Signature",
            "value_list":[
                {
                    "value":"/9j/4AAQSkZJRgABAQE***” "
                }
            ]
        }
    ]
}
  • ImageQualityInfo
    字段类型含义备注
    resultInteger总体结果
    listObject检查结果列表
    list.feature_typeInteger检查的区域预留字段，默认为0
    list.resultInteger单项检查结果请参考CheckResult 数据字典
    list.typeInteger单项检查类型检查结果类型，请参考ImageQualityCheckType 数据字典
    {
  "list": [
    {
      "feature_type":0,
      "result": 1,
      "type": 1
    },
    {
      "feature_type":0,
      "result": 1,
      "type": 0
    },
    {
      "feature_type":0,
      "result": 1,
      "type": 7
    },
    {
      "feature_type":0,
      "result": 1,
      "type": 5
    },
    {
      "feature_type":0,
      "result": 1,
      "type": 4
    },
    {
      "feature_type":0,
      "result": 1,
      "type": 2
    }
  ],
  "result": 1
}

  • DocumentForgeryInfo
    字段类型含义备注
    resultString证件伪造检测总体结果枚举值：

    1. pass：验证通过，证件未伪造
    2. fail：验证失败，证件为伪造证件
    detailObject证件伪造检测结果列表如果结果为通过，则不返回该字段；如果结果为失败，显示具体原因，包括黑白打印（black_white_print）、屏幕翻拍（screen_capture）
    {
    "result":"fail",
    "detail":[
     "black_white_print"
     ]
}

数据字典

  • CheckResult

    返回值名称描述
    0ERROR已进行检查，结果为NEGATIVE
    1OK已进行检查，结果为POSITIVE
    2WAS_NOT_DONE未执行检查

  • ImageQualityCheckType

    返回值名称描述
    0ImageGlares图像上存在眩光
    1ImageFocus图像对焦正常
    2ImageResolution图像分辨率低于阈值
    3ImageColorness图像是无色的
    4Perspective图像中文档的旋转角度高于阈值
    5Bounds文档未完全呈现在图像中
    6ScreenCapture图像是从屏幕翻拍的
    7Portrait肖像清晰可见

  • LCID

    返回值名称描述
    0LATINLatin
    1078AFRIKAANSAfrikaans
    1052ALBANIANAlbanian
    5121ARABIC_ALGERIAArabic (Algeria)
    15361ARABIC_BAHRAINArabic (Bahrain)
    3073ARABIC_EGYPTArabic (Egypt)
    2049ARABIC_IRAQArabic (Iraq)
    11265ARABIC_JORDANArabic (Jordan)
    13313ARABIC_KUWAITArabic (Kuwait)
    12289ARABIC_LEBANONArabic (Lebanon)
    4097ARABIC_LIBYAArabic (Libya)
    6145ARABIC_MOROCCOArabic (Morocco)
    8193ARABIC_OMANArabic (Oman)
    16385ARABIC_QATARArabic (Qatar)
    1025ARABIC_SAUDI_ARABIAArabic (Saudi Arabia)
    10241ARABIC_SYRIAArabic (Syria)
    7169ARABIC_TUNISIAArabic (Tunisia)
    14337ARABIC_UAEArabic (U.A.E.)
    9217ARABIC_YEMENArabic (Yemen)
    1067ARABIC_ARMENIANArmenian
    2092AZERI_CYRILICAzeri (Cyrillic)
    1068AZERI_LATINAzeri (Latin)
    1069BASQUEBasque
    1059BELARUSIANBelarusian
    1026BULGARIANBulgarian
    1027CATALANCatalan
    3076CHINESE_HONGKONG_SARChinese (HongKong S.A.R.)
    5124CHINESE_MACAO_SARChinese (Macao S.A.R.)
    2052CHINESEChinese
    4100CHINESE_SINGAPOREChinese (Singapore)
    1028CHINESE_TAIWANChinese (Taiwan)
    1050CROATIANCroatian
    1029CZECHCzech
    1030DANISHDanish
    1125DIVEHIDivehi
    2067DUTCH_BELGIUMDutch (Belgium)
    1043DUTCH_NETHERLANDSDutch (Netherlands)
    3081ENGLISH_AUSTRALIAEnglish (Australia)
    10249ENGLISH_BELIZEEnglish (Belize)
    4105ENGLISH_CANADAEnglish (Canada)
    9225ENGLISH_CARRIBEANEnglish (Caribbean)
    6153ENGLISH_IRELANDEnglish (Ireland)
    8201ENGLISH_JAMAICAEnglish (Jamaica)
    5129ENGLISH_NEW_ZEALANDEnglish (New Zealand)
    13321ENGLISH_PHILIPPINESEnglish (Philippines)
    7177ENGLISH_SOUTH_AFRICAEnglish (South Africa)
    11273ENGLISH_TRINIDADEnglish (Trinidad)
    2057ENGLISH_UKEnglish (United Kingdom)
    1033ENGLISH_USEnglish (United States)
    12297ENGLISH_ZIMBABWEEnglish (Zimbabwe)
    1061ESTONIANEstonian
    1080FAEROESEFaeroese
    1065FARSIFarsi
    1035FINNISHFinnish
    2060FRENCH_BELGIUMFrench (Belgium)
    3084FRENCH_CANADAFrench (Canada)
    1036FRENCH_FRANCEFrench (France)
    5132FRENCH_LUXEMBOURGFrench (Luxembourg)
    6156FRENCH_MONACOFrench (Monaco)
    4108FRENCH_SWITZERLANDFrench (Switzerland)
    1071FYRO_MACEDONIANFYRO Macedonian
    1110GALICIANGalician
    1079GEORGIANGeorgian
    3079GERMAN_AUSTRIAGerman (Austria)
    1031GERMAN_GERMANYGerman (Germany)
    5127GERMAN_LIECHTENSTEINGerman (Liechtenstein)
    4103GERMAN_LUXEMBOURGGerman (Luxembourg)
    2055GERMAN_SWITZERLANDGerman (Switzerland)
    1032GREEKGreek
    1095GUJARATIGujarati
    1037HEBREWHebrew
    1081HINDI_INDIAHindi (India)
    1038HUNGARIANHungarian
    1039ICELANDICIcelandic
    1057INDONESIANIndonesian
    1040ITALIAN_ITALYItalian (Italy)
    2064ITALIAN_SWITZERLANDItalian (Switzerland)
    1041JAPANESEJapanese
    1099KANNADAKannada
    1087KAZAKHKazakh
    1111KONKANIKonkani
    1042KOREANKorean
    1088KYRGYZ_CYRILICKKyrgyz (Cyrillic)
    1062LATVIANLatvian
    1063LITHUANIANLithuanian
    1086MALAY_MALAYSIAMalay (Malaysia)
    2110MALAY_BRUNEI_DARUSSALAMMalay (Brunei Darussalam)
    1102MARATHIMarathi
    1104MONGOLIAN_CYRILICMongolian (Cyrillic)
    1044NORWEGIAN_BOKMALNorwegian (Bokmal)
    2068NORWEGIAN_NYORSKNorwegian (Nynorsk)
    1045POLISHPolish
    1046PORTUGUESE_BRAZILPortuguese (Brazil)
    2070PORTUGUESE_PORTUGALPortuguese (Portugal)
    1094PUNJABIPunjabi
    1047RHAETO_ROMANICRhaeto-Romanic
    1048ROMANIANRomanian
    1049RUSSIANRussian
    1103SANSKRITSanskrit
    3098SERBIAN_CYRILICSerbian (Cyrillic)
    2074SERBIAN_LATINSerbian (Latin)
    1051SLOVAKSlovak
    1060SLOVENIANSlovenian
    11274SPANISH_ARGENTINASpanish (Argentina)
    16394SPANISH_BOLIVIASpanish (Bolivia)
    13322SPANISH_CHILESpanish (Chile)
    9226SPANICH_COLOMBIASpanish (Colombia)
    5130SPANISH_COSTA_RICASpanish (Costa Rica)
    7178SPANISH_DOMINICAN_REPUBLICSpanish (Dominican Republic)
    12298SPANISH_ECUADORSpanish (Ecuador)
    17418SPANISH_EL_SALVADORSpanish (El Salvador)
    4106SPANISH_GUATEMALASpanish (Guatemala)
    18442SPANISH_HONDURASSpanish (Honduras)
    2058SPANISH_MEXICOSpanish (Mexico)
    19466SPANISH_NICARAGUASpanish (Nicaragua)
    6154SPANISH_PANAMASpanish (Panama)
    15370SPANISH_PARAGUAYSpanish (Paraguay)
    10250SPANISH_PERUSpanish (Peru)
    20490SPANISH_PUERTO_RICOSpanish (Puerto Rico)
    1034SPANISH_TRADITIONAL_SORTSpanish (Traditional Sort)
    3082SPANISH_INTERNATIONAL_SORTSpanish (International Sort)
    14346SPANISH_URUGUAYSpanish (Uruguay)
    8202SPANISH_VENEZUELASpanish (Venezuela)
    1089SWAHILISwahili
    1053SWEDISHSwedish
    2077SWEDISH_FINLANDSwedish (Finland)
    1114SYRIACSyriac
    1097TAMILTamil
    1092TATARTatar
    1098TELUGUTelugu
    1054THAI_THAILANDThai (Thailand)
    1055TURKISHTurkish
    1064TAJIK_CYRILLICTajik (Cyrillic)
    1090TURKMENTurkmen
    1058UKRAINIANUkrainian
    1056URDUUrdu
    2115UZBEK_CYRILICUzbek (Cyrillic)
    1091UZBEK_LATINUzbek (Latin)
    1066VIETNAMESEVietnamese
    50001CTC_SIMPLIFIEDCTC Simplified
    50002CTC_TRADITIONALCTC Traditional

返回码

Code Message描述
200Success调⽤成功
301Service not purchased未购买此服务
302Traffic blocked流量已被禁用
303Traffic insufficient流量不足
304Service expired服务已过期
305Daily maximum volume reached日流量已封顶
11350Internal error系统错误
11301{parameter} empty{参数}为空
11304The country partner located is not open国家不支持
11340{parameter} error{参数}错误

参数样例

  • 入参示例：
{
  "image": "/9j/4AAQSkZJRgABAQAAeAB4AAD/********XLiqqauzsw1J3sf/2Q==",
  "country": "GB",
  "scenario": "Ocr",
  "options": "images,image_quality,document_forgery"
}
  • 业务请求成功
{
    "result":"success",
    "code":200,
    "sequence_id":"2a7515e2bc094********20cf1ca0f72",
    "message":"success",
    "status_info":{
        "doc_type":1,
        "expiry":1,
        "mrz":1,
        "text":1
    },
    "document_type_info":{
        "document_name":"Philippines - ePassport (2016)",
        "document_description":"Passport"
    },    
    "card_info":{
        "field_list":[
            {
                "field_name":"Date of Expiry",
                "validity_status":1,
                "value_list":[
                    {
                        "original_value":"23/08/2024",
                        "value":"2024-08-23"
                    }
                ]
            },
            {
                "field_name":"Date of Birth",
                "validity_status":1,
                "value_list":[
                    {
                        "original_value":"01/01/1979",
                        "value":"1979-01-01"
                    }
                ]
            }
        ]
    },
    "image_info":{
        "field_list":[
            {
                "field_name":"Portrait",
                "value_list":[
                    {
                        "value":"/4AAQSkZJRgABAQEBHwEfAADxxxxxx"
                    }
                ]
            },
            {
                "field_name":"Signature",
                "value_list":[
                    {
                        "value":"/9j/4AAQSkZJRgABAQE***” "
                    }
                ]
            }
        ]
    },
    "image_quality_info":{
        "list":[
            {
                "feature_type":0,
                "result":1,
                "type":1
            },
            {
                "feature_type":2,
                "result":1,
                "type":0
            },
            {
                "feature_type":3,
                "result":1,
                "type":7
            },
            {
                "feature_type":4,
                "result":1,
                "type":5
            },
            {
                "feature_type":5,
                "result":1,
                "type":4
            },
            {
                "feature_type":6,
                "result":1,
                "type":2
            }
        ],
        "result":1
    },
  "document_forgery_info":{
    "result":"fail",
    "detail":[
     "black_white_print"
     ]
  }
}
  • 业务不请求成功
{
    "code": 302,
    "sequence_id": "69b57131b6fb********61ccba118b60",
    "message": "Traffic blocked"
}