异步检测-阿里云帮助中心

结构化票据OCR目前支持识别以下票据类型：增值税发票、定额发票、火车票、出租车票。

（图片异步检测）使用说明

业务接口：/green/image/asyncscan，表示图片异步检测。

您可以调用该接口创建图片异步检测任务。关于如何构造HTTP请求，请参见请求结构；您也可以直接选用已构造好的HTTP请求，更多信息，请参见SDK概览。

计费信息：
该接口为收费接口。关于计费方式，请参见内容安全产品定价。
检测超时：
同步检测允许的最长检测时间是6秒，如果检测在该时间限制内没有完成，系统会强制返回超时错误码。如果您对实时性要求不高，可以选择异步检测，其他情况下请选择同步检测，同步检测接口的调用相对简单些。对于同步检测接口的调用，建议您将超时时间设置为6秒。
返回结果：
异步检测任务不会实时返回检测结果，您需要通过callback或者轮询的方式获取检测结果。检测结果最长保留一小时。
- callback获取检测结果：提交异步检测任务时，在请求参数中传入callback参数，用来自动接收检测结果，具体请参见（异步检测）请求参数。
- 轮询获取检测结果：提交异步检测任务时，无需传入callback参数；提交异步检测任务后，调用结果查询接口获取检测结果，具体请参见（图片异步检测结果查询）使用说明。
图片要求：
- 图片链接支持以下协议：HTTP和HTTPS。
- 图片支持以下格式：PNG、JPG、JPEG、BMP、GIF、WEBP。
- 图片大小限制为20 MB以内（适用于同步和异步调用），高度或者宽度不能超过30,000像素（px），且图像总像素不超过2.5亿（px）。
- 图片下载时间限制为3秒内，如果下载时间超过3秒，返回下载超时。
- 图片像素建议不低于256*256（px），像素过低可能会影响识别效果。
- 图片检测接口的响应时间依赖图片的下载时间。请保证被检测图片所在的存储服务稳定可靠，建议您使用阿里云OSS存储或者CDN缓存等。

QPS限制

本接口的单用户QPS限制为10次/秒。超过限制，API调用会被限流，这可能会影响您的业务，请合理调用。

（异步检测）请求参数


名称	类型	是否必须	示例值	描述
bizType	String	否	default	该字段用于标识您的业务场景。您可以通过内容安全控制台创建业务场景（具体操作，请参见自定义机审标准）。
scenes	StringArray	是	["ocr"]	指定检测场景，取值：ocr。
callback	String	否	http://www.aliyundoc.com/xx.json	检测结果回调通知您的URL，支持使用HTTP和HTTPS协议的地址。该字段为空时，您必须定时轮询检测结果。 callback接口必须支持POST方法、UTF-8编码的传输数据，以及表单参数checksum和content。内容安全按照以下规则和格式设置checksum和content，调用您的callback接口返回检测结果。 checksum：字符串格式，由`用户uid + seed + content`拼成字符串，通过SHA256算法生成。用户UID即阿里云账号ID，可以在阿里云控制台查询。为防篡改，您可以在获取到推送结果时，按上述算法生成字符串，与checksum做一次校验。说明用户UID必须是阿里云账号的UID，而不是RAM用户的UID。 content：JSON字符串格式，请自行解析反转成JSON对象。关于content结果的示例，请参见查询检测结果的返回示例。说明您的服务端callback接口收到内容安全推送的结果后，如果返回的HTTP状态码为200，则表示接收成功，其他的HTTP状态码均视为接收失败。接收失败时，内容安全将最多重复推送16次检测结果，直到接收成功。重复推送16次后仍未接收成功，则不再推送，建议您检查callback接口的状态。
seed	String	否	aabbcc123	随机字符串，该值用于回调通知请求中的签名。由英文字母、数字、下划线（_）组成，不超过64个字符。由您自定义，用于在接收到内容安全的回调通知时校验请求由阿里云内容安全服务发起。说明当使用callback时，该字段必须提供。
cryptType	String	否	SHA256	使用回调通知时（callback），设置对回调通知内容进行加密的算法。内容安全会将返回结果（由`用户uid + seed + content`拼接的字符串）按照您设置的加密算法加密后，再发送到您的回调通知地址。取值： SHA256（默认）：使用SHA256加密算法。 SM3：使用国密HMAC-SM3加密算法，返回十六进制的字符串，且字符串由小写字母和数字组成。例如，abc经国密SM3加密后返回66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0。
tasks	JSONArray	是		指定检测对象，JSON数组中的每个元素是一个检测任务结构体。最多支持100个元素，即每次提交100条内容进行检测，支持100个元素的前提是需要将并发任务调整到100个以上。关于每个元素的具体结构描述，请参见task。
extras	JSONObject	是	{"card":"invoice"}	指定要识别的票据类型，格式为`{"card":"${CardType}"}`。`CardType`表示票据类型，取值： invoice：增值税发票 quota-account-permit：定额发票 train-ticket：火车票 taxi-ticket：出租车票

表 1. task
名称	类型	是否必须	示例值	描述
dataId	String	否	test_data_xxxx	数据ID。需要保证在一次请求中所有的ID不重复。
url	String	是	https://www.aliyundoc.com/test_image_xxxx.png	待检测图像的URL。

（异步检测）返回数据


名称	类型	示例值	描述
code	Integer	200	错误码，和HTTP状态码一致。更多信息，请参见公共错误码。
msg	String	OK	请求信息的响应消息。
dataId	String	test_data_xxxx	检测对象对应的数据ID。说明如果在检测请求参数中传入了dataId，则此处返回对应的dataId。
taskId	String	img1CVBf$Vgrno7wF75H5LaRm-1p****	检测任务的ID。
url	String	https://www.aliyundoc.com/test_image_xxxx.png	检测对象的URL。
extras	JSONObject	{"card":"invoice"}	额外调用参数，对应检测请求参数中的extras。说明该参数可能会被调整，目前请勿依赖该参数的返回值。

（异步检测）示例

请求示例

说明以增值税发票识别为例（extras传入{"card": "invoice"}）。如果需要识别其他类型的票据，传入对应的票据类型即可，具体请参见（异步检测）请求参数。

http(s)://[Endpoint]/green/image/asyncscan
&<公共请求参数>
{
    "scenes": [
        "ocr"
    ],
    "extras": {
        "card": "invoice"
    },
    "tasks": [
        {
            "dataId": "test_data_xxxx",
            "url": "https://www.aliyundoc.com/test_image_xxxx.png"
        }
    ]
}

正常返回示例

{
    "code": 200,
    "msg": "OK",
    "requestId": "92AD868A-F5D2-4AEA-96D4-E1273B8E074C",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "test_data_xxxx",
            "taskId": "img1CVBf$Vgrno7wF75H5LaRm-1p****",
            "url": "https://www.aliyundoc.com/test_image_xxxx.png"
        }
    ]
}

（图片异步检测结果查询）使用说明

业务接口：/green/image/results，表示查询图片异步检测结果。

您可以调用该接口查询图片异步检测任务的结果。关于如何构造HTTP请求，请参见请求结构；您也可以直接选用已构造好的HTTP请求，更多信息，请参见SDK概览。

计费信息：
该接口不计费。
查询超时：
建议您将查询间隔设置为30秒（即在提交异步检测任务30秒后查询结果），最长不能超出4个小时，否则结果将会丢失。

QPS限制

本接口的单用户QPS限制为10次/秒。超过限制，API调用会被限流，这可能会影响您的业务，请合理调用。

（结果查询）请求参数


名称	类型	是否必须	示例值	描述
body	JSONArray	是	["img5A@k7a@B4q@6K@d9nfKgOs-1sWeLu"]	要查询的检测任务的taskId列表。数组中的元素个数不超过100个。您在提交检测任务后，可以从返回数据中获取检测任务的taskId。

（结果查询）返回数据


名称	类型	示例值	描述
code	Integer	200	错误码，和HTTP状态码一致。更多信息，请参见公共错误码。
msg	String	OK	请求信息的响应消息。
dataId	String	test_data_xxxx	检测对象对应的数据ID。说明如果在检测请求参数中传入了dataId，则此处返回对应的dataId。
taskId	String	img5A@k7a@B4q@6K@d9nfKgOs-1s****	检测任务的ID。
url	String	https://www.aliyundoc.com/test_image_xxxx.png	检测对象的URL。
extras	JSONObject	{"md5":"303f7159179153a94033724ffd28ea44"}	额外调用参数，对应检测请求参数中的extras。说明该参数可能会被调整，目前请勿依赖该参数的返回值。
results	Array		返回结果。调用成功时（code=200），返回结果中包含一个或多个元素。每个元素是个结构体，具体结构描述请参见result。

表 2. result
名称	类型	示例值	描述
scene	String	ocr	检测场景，取值：ocr。
label	String	ocr	检测结果的分类。取值： normal：图片中未识别出文字信息。 ocr：图片中包含文字信息。
suggestion	String	review	建议用户执行的操作，取值： pass：无需关注返回结果。 review：关注识别出的文字信息。
rate	Float	99.91	在OCR图文识别场景中，可以不用关注该返回值。
invoiceInfo	Object		识别出来的增值税发票信息。关于具体结构描述，请参见invoiceInfo。说明只有在异步检测任务的请求参数extras中指定了`{"card":"invoice"}`才会返回该结果。
ocrCardInfo	Object		识别出来的其他票据的OCR信息。关于具体结构描述，请参见ocrCardInfo。说明只有在异步检测任务的请求参数extras中指定了以下内容，才会返回相应结果： `{"card":"quota-account-permit"}`：返回定额发票信息。 `{"card":"train-ticket"}`：返回火车票信息。 `{"card":"taxi-ticket"}`：返回出租车票信息。

表 3. 增值税发票信息（invoiceInfo）
名称	类型	示例值	描述
invoice_name	String	**增值税专用发票	发票名称。
invoice_id	Integer	110015****	发票代码。
invoice_number	Integer	5795****	发票号码。
invoice_date	Integer	20170422	开票日期。
invoice_bcompany	String	****软件有限公司	购买方名称。
invoice_bcode	String	91330000000000****	购买方纳税人识别号。
invoice_baddress	String	****	购买方地址、电话。
invoice_baccount	String	银行某支行**	购买方开户行及账号。
invoice_password	String	1<000+0000-0000>7927<>7295<-123020-8>07+63683-80+>314-9+0+/<0-<-/1++359586>98709/+9323858+8745<72461****	发票密码。
invoice_detail	Array		增值税发票明细。关于具体结构描述，请参见invoice_detail。
invoice_totalamount	Float	4222.22	合计金额。
invoice_totaltax	Float	717.78	合计税额。
invoice_totalamountupper	String	肆仟玖佰肆拾圆整	价税合计（大写）。
invoice_totalamountlower	String	4940.00	价税合计（小写）。
invoice_scompany	String	****有限责任公司	销售方名称。
invoice_scode	String	91110000000000****	销售方纳税人识别号。
invoice_saddress	String	****	销售方地址、电话。
invoice_saccount	String	**支行1105011012340000**	销售方开户行及账号。
invoice_remark	String	KP12****	备注。
invoice_payee	String	xxx	收款人。
invoice_reviewer	String	xxx	复核。
invoice_drawer	String	张某某	开票人。

表 4. 增值税发票明细（invoice_detail）
名称	类型	示例值	描述
detail_name	String	荣莉龙芽花茶	货物或应税劳务、服务名称。
detail_type	String	xxx	规格型号。
detail_unit	String	xxx	单位。
detail_count	Float	20	数量。
detail_unitprice	Float	44.4444444	单价。
detail_amount	Float	888.89	金额。
detail_rate	String	17%	税率。
detail_tax	Float	151.11	税额。

ocrCardInfo

表 5. 定额发票信息
名称	类型	示例值	描述
amountInWords	String	壹佰元	大写金额。
invoiceSerial	String		发票代码解析。
amountInFigures	String	100	小写金额。
invoiceNumber	String	0145****	发票号码。
invoiceCode	String	15113159****	发票代码。
batchNumber	String	01	批次号。
year	String	2015	年份。
taxBureauCode	String	国税	税务局代码。
invoiceIndustryCode	String	None	发票行业代码。
amountVersion	String	电脑版	金额版。
regionalismCode	String	南充市	行政区划代码。
invoiceCategoryCode	String	发票换票证	发票类别代码。
type	String	quota-invoice	票据的类型，取值固定为quota-invoice，表示定额发票。

表 6. 火车票信息
名称	类型	示例值	描述
price	String	0.0	票价。
ticketNumber	String	A000001	票号。
departureTime	String	2019年01月01日00：00开	开车时间。
seatType	String	二等座	座位类型。
trainNumber	String	G0000	车次。
departure	String	始发站	出发站。
departurePhonics	String	Shifa	出发站拼音。
seatNumber	String	01车01F号	座位号。
destination	String	终到站	到达站。
destinationPhonics	String	Zhongdao	到达站拼音。
passengerInfo	String	1234567890****0000姓名	旅客信息。
type	String	train-ticket	票据的类型，取值固定为train-ticket，表示火车票。

表 7. 出租车票信息
名称	类型	示例值	描述
actualCollection	String	100	实收金额。
carNumber	String	A•T****	车号。
date	String	2008年9月16日	日期。
invoiceCode	String	25000071****	发票代码。
invoiceNumbe	String	5485G0****	发票号码。
mileage	String	42.0km	里程。
amount	String	100	金额。
getOffTime	String	16：58	下车时间。
boardingTime	String	[K068016：50	上车时间。
totalAmount	String	100	合计。
type	String	taxi-ticket	票据的类型，取值固定为taxi-ticket，表示出租车票。

（结果查询）示例

请求示例

http(s)://[Endpoint]/green/image/results
&<公共请求参数>
[
    "img5A@k7a@B4q@6K@d9nfKgOs-1s****"
]

正常返回示例

增值税发票信息

{
    "msg":"OK",
    "code":200,
    "data":[
        {
            "msg":"OK",
            "code":200,
            "dataId":"test_data_xxxx",
            "extras":{
                "md5":"303f7159179153a94033724ffd28ea44"
            },
            "results":[
                {
                    "invoiceInfo":{
                        "invoice_bcompany":"****软件有限公司",
                        "invoice_baccount":"**银行某支行****",
                        "invoice_drawer":"张某某",
                        "invoice_totalamountupper":"肆仟玖佰肆拾圆整",
                        "invoice_name":"**增值税专用发票",
                        "invoice_date":"20170422",
                        "invoice_totaltax":"717.78",
                        "invoice_reviewer":"",
                        "invoice_totalamountlower":"4940.00",
                        "invoice_id":"110015****",
                        "invoice_number":"5795****",
                        "invoice_scompany":"****有限责任公司",
                        "invoice_saccount":"****支行1105011012340000****",
                        "invoice_saddress":"****",
                        "invoice_remark":"KP12****",
                        "invoice_totalamount":"4222.22",
                        "invoice_password":"1<000+0000-0000>79*27<>7295<-123020-8>07+63*683-80+>314-9+0+/<0-<-/1++35*958*6>98709/+9323858+8745<72461****",
                        "invoice_payee":"",
                        "invoice_detail":[
                            {
                                "detail_amount":"888.89",
                                "detail_name":"荣莉龙芽花茶",
                                "detail_rate":"17%",
                                "detail_count":"20",
                                "detail_type":"",
                                "detail_unitprice":"44.4444444",
                                "detail_tax":"151.11",
                                "detail_unit":""
                            },
                            {
                                "detail_amount":"3333.33",
                                "detail_name":"大佛龙井绿茶",
                                "detail_rate":"17%",
                                "detail_count":"50",
                                "detail_type":"",
                                "detail_unitprice":"66.6666667",
                                "detail_tax":"566.67",
                                "detail_unit":""
                            }
                        ],
                        "invoice_baddress":"****",
                        "invoice_bcode":"91330000000000****",
                        "invoice_scode":"91110000000000****"
                    },
                    "rate":99.91,
                    "suggestion":"review",
                    "label":"ocr",
                    "scene":"ocr"
                }
            ],
            "taskId":"img5A@k7a@B4q@6K@d9nfKgOs-1s****",
            "url":"https://www.aliyundoc.com/test_image_xxxx.png"
        }
    ],
    "requestId":"81121B0B-2BFE-44BA-9825-C15CA5E99551"
}

火车票信息

{
    "msg": "OK",
    "code": 200,
    "data": [
        {
            "msg": "OK",
            "code": 200,
            "dataId": "test_data_xxxx",
            "extras": {

            },
            "results": [
                {
                    "rate": 99.91,
                    "suggestion": "review",
                    "label": "ocr",
                    "ocrCardInfo": {
                        "departureTime": "2019年01月01日00：00开",
                        "ticketNumber": "A000001",
                        "seatType": "二等座",
                        "price": "0.0",
                        "destination": "终到站",
                        "passengerInfo": "1234567890****0000姓名",
                        "trainNumber": "G0000",
                        "departure": "始发站",
                        "destinationPhonics": "Zhongdao",
                        "type": "train-ticket",
                        "seatNumber": "01车01F号",
                        "departurePhonics": "Shifa"
                    },
                    "scene": "ocr"
                }
            ],
            "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****",
            "url": "https://www.aliyundoc.com/test_image_xxxx.png"
        }
    ],
    "requestId": "C55D1390-B1D0-4B27-83F3-7335006525E2"
}

定额发票信息

{
    "msg": "OK",
    "code": 200,
    "data": [
        {
            "msg": "OK",
            "code": 200,
            "dataId": "test_data_xxxx",
            "extras": {

            },
            "results": [
                {
                    "rate": 99.91,
                    "suggestion": "review",
                    "label": "ocr",
                    "ocrCardInfo": {
                        "amountInWords": "壹佰元",
                        "amountInFigures": "",
                        "invoiceSerial": {
                            "amountVersion": "电脑版",
                            "year": "2015",
                            "invoiceCategoryCode": "发票换票证",
                            "taxBureauCode": "国税",
                            "invoiceIndustryCode": "None",
                            "regionalismCode": "南充市",
                            "batchNumber": "01"
                        },
                        "invoiceNumber": "0145****",
                        "type": "quota-invoice",
                        "invoiceCode": "15113159****"
                    },
                    "scene": "ocr"
                }
            ],
            "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****",
            "url": "https://www.aliyundoc.com/test_image_xxxx.png"
        }
    ],
    "requestId": "B5E137FF-668F-48D9-90F7-CE55A9FCC89D"
}

出租车票信息

{
    "msg": "OK",
    "code": 200,
    "data": [
        {
            "msg": "OK",
            "code": 200,
            "dataId": "test_data_xxxx",
            "extras": {

            },
            "results": [
                {
                    "rate": 99.91,
                    "suggestion": "review",
                    "label": "ocr",
                    "ocrCardInfo": {
                        "carNumber": "A•T****",
                        "date": "2008109月16日",
                        "totalAmount": "",
                        "getOffTime": "16：58",
                        "amount": "",
                        "invoiceNumber": "5485G0****",
                        "type": "taxi-ticket",
                        "boardingTime": "[K068016：50",
                        "invoiceCode": "25000071****",
                        "actualCollection": "",
                        "mileage": "42.0km"
                    },
                    "scene": "ocr"
                }
            ],
            "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****",
            "url": "https://www.aliyundoc.com/test_image_xxxx.png"
        }
    ],
    "requestId": "D1E56B7A-3876-4284-939A-8004B150D879"
}