为什么使用国内通用票据识别API ?

在国内企业财务报销、税务申报、费用核算等通用票据处理场景中,人工录入增值税发票、火车票、全电票、航空运输电子客票行程单等票据信息时,常面临票据类型繁杂(覆盖 24 大类、36 小类)、格式标准不统一、关键信息分散、重复录入工作量大、人工核验易出错等痛点。而使用国内通用票据识别 API,可借助智能自动化识别技术,对 24 大类、36 小类主流通用票据实现全覆盖识别,精准提取发票号码、金额、税额、购票人信息、行程日期等关键信息,核心数据以符合企业财务与税务规范的 Key/Value 形式融入 JSON 格式返回。

如何使用国内通用票据识别API ?

您可以参考以下示例文件和步骤,快速验证并将医疗票据API接入到您的系统和应用流程中。

先决条件:获取API Key

使用文档解析API处理文档时,您需要先获取API Key。请先登录后前往 TextIn工作台 - 账号与开发者信息 获取您的 x-ti-app-id 和 x-ti-secret-code 。

前置准备

您可以参考以下示例代码完成文档解析API请求的前置准备工作,替换您自己的 x-ti-app-id 和 x-ti-secret-code ,后续步骤可根据实际使用场景在main函数中插入代码。
import requests
import json

def get_file_content(filePath):
    with open(filePath, 'rb') as fp:
        return fp.read()

class CommonOcr(object):
    def __init__(self, img_path=None, is_url=False):
        # 国内通用票据识别
        self._url = 'https://api.textin.com/ai/service/v1/bill_recognize_v2'
        # 请登录后前往 “工作台-账号设置-开发者信息” 查看 x-ti-app-id
        # 示例代码中 x-ti-app-id 非真实数据
        self._app_id = 'c81f*************************e9ff'
        # 请登录后前往 “工作台-账号设置-开发者信息” 查看 x-ti-secret-code
        # 示例代码中 x-ti-secret-code 非真实数据
        self._secret_code = '5508***********************1c17'
        self._img_path = img_path
        self._is_url = is_url

    def recognize(self, options: dict = dict()):
        head = {}
        params = {}
        
        try:
            for key, value in options.items():
                params[key] = str(value)
                
            head['x-ti-app-id'] = self._app_id
            head['x-ti-secret-code'] = self._secret_code
            if self._is_url:
                head['Content-Type'] = 'text/plain'
                body = self._img_path
            else:
                image = get_file_content(self._img_path)
                head['Content-Type'] = 'application/octet-stream'
                body = image
            result = requests.post(self._url, data=body, headers=head)
            return result.text
        except Exception as e:
            return e

if __name__ == "__main__":
    # 示例 1:传输文件
    response = CommonOcr(img_path=r'example.jpg')
    print(response.recognize())
    # 示例 2:传输 URL
    response = CommonOcr(img_path='http://example.com/example.jpg', is_url=True)
    print(response.recognize())

请求体说明

支持以下两种请求格式
  1. Content-Type: application/octet-stream 要上传的图片,目前支持jpg、png、bmp、pdf、tiff、ofd、单帧gif等大部分格式,pdf和ofd文件支持多页​请注意,请求体的数据格式为本地文件的二进制流,非 FormData 或其他格式。文件大小不超过 50M,图像宽高须介于 20 和 10000(像素)之间。
  2. Content-Type: text/plain 请求体的数据格式为文本,内容为在线文件的URL链接(支持http以及https协议)。在线文件大小不超过 50M,图像宽高须介于 20 和 10000(像素)之间。

URL参数说明

以下是国内通用票据识别API的URL参数,URL参数指以 参数名=参数值 形式拼接到 URL 上的键值对。它以?开头,不同参数之间使用&连接,形如?p1=v1&p2=v2。URL参数会影响文档的解析结果和JSON输出内容,您可按需进行设置。
  • coord_restore:选择你各字段的返回坐标逻辑,是以原图为基准,还是以票据切图为基准,默认为0,以票据切图为基准
    • 0 以票据切图为基准
    • 1 以原图为基准
  • specific_pages:
    • 0 不输出图片base64
    • 1 输出图片base64
  • crop_complete_image:选择是否需要输出各票据图片base64编码,默认为0,不输出图片base64编码。
    • 0 不输出
    • 1 输出
  • crop_value_image:选择是否返回关键字段切图的base64编码,默认为0,不返回关键字段切图base64编码。
    • 0 不返回
    • 1 返回
  • merge_digital_elec_invoice:选择是否将多页全电票的结果合并为一页,默认为0,不合并。当且仅当一份多页样本的每一页都是全电票,且每张发票的发票号码都一致时才可合并。
    • 0 不合并
    • 1 合并
  • return_ppi:选择是否返回pdf解码ppi信息,默认为0,不返回。
    • 0 不返回
    • 1 返回
  • verify_vat:选择是否开启验真,开启后将返回验真五要素,默认为0, 不开启验真。
    • 0 不开启
    • 1 开启

返回结果示例

票据信息结构化后的结果数据将按照以下JSON格式返回,下面为您提供了一段节选的返回示例。如果您想了解最全面的返回结果说明,可以在返回JSON结构说明中查看,也可以在API中查看和调试。
{
    "code": 200,            // 响应状态码,200表示成功
    "message": "success",   // 响应消息
    "pageNum": 1,           // 样本总页数
    "pages": [              
        {
            "result": {     // 单页识别结果
                "object_list": [       
                    {                                       // 单张图片识别结果
                        "image_angle": 0,                   // 单张图片角度
                        "type": "parking_invoice",          // 票据类型
                        "type_description": "停车费发票",    // 票据类型,中文描述
                        "kind": "other",                    // 票据使用类型
                        "kind_description": "其他",         // 票据使用类型,中文描述
                        "stamp_list": [                    // 印章识别结果
                            [
                                {
                                    "description": "印章内容",       // key中文描述
                                    "position": [                   // 印章在转正图上的坐标位置
                                        187,
                                        29,
                                        414,
                                        22,
                                        422,
                                        256,
                                        195,
                                        264
                                    ],
                                    "key": "stamp_info",            // key
                                    "value": "财    "               // key识别结果
                                },
                                {
                                    "key": "stamp_type",            // 印章类型
                                    "value": "其他",
                                    "description": "印章类型",
                                    "position": [
                                        187,
                                        29,
                                        414,
                                        22,
                                        422,
                                        256,
                                        195,
                                        264
                                    ]
                                },
                                {
                                    "key": "stamp_invoice_seller_id", // 印章销售方纳税人识别号
                                    "value": "",
                                    "description": "印章销售方纳税人识别号",
                                    "position": [
                                        187,
                                        29,
                                        414,
                                        22,
                                        422,
                                        256,
                                        195,
                                        264
                                    ]
                                }
                            ]
                        ],
                        "position": [                                    // 子图在原图上的坐标位置
                            5,
                            36,
                            502,
                            44,
                            512,
                            316,
                            4,
                            329
                        ],
                        "qr_code_list": [
                            [                                            // 单个二维码识别结果                  
                                {       
                                    "key": "qr_code_info",               // key
                                    "value": "01,32, ,23****",           // 二维码识别内容
                                    "description": "二维码内容",          // key中文描述
                                    "position": [                        // 二维码在转正图中的坐标位置
                                        62,
                                        32,
                                        157,
                                        31,
                                        158,
                                        126,
                                        63,
                                        127
                                    ]
                                }
                            ]
                        ],
                        "rotated_image_width": 546,                     // 图片转正后的宽度
                        "rotated_image_height": 313,                    // 图片转正后的高度               
                        "item_list": [                                  // 票据key抽取结果
                            {
                                "key": "invoice_number",                // key
                                "value": "11111111111111*",             // key识别结果
                                "position": [                           // key在转正图中的坐标
                                    0,
                                    0,
                                    0,
                                    0,
                                    0,
                                    0,
                                    0,
                                    0
                                ],
                                "description": "发票号码"                // key中文描述
                            },
                            // [更多key识别结果...]
                        ]
                    }
                ],
                "width": 550,    // 图片原始宽度
                "height": 367    // 图片原始高度
            },
            "duration": 159,     // 引擎耗时(毫秒)
            "page_number": 0     // 当前识别图片所在页
        }
    ]
}

错误码说明

错误码描述
40101x-ti-app-id 或 x-ti-secret-code 为空
40102x-ti-app-id 或 x-ti-secret-code 无效,验证失败
40103客户端IP不在白名单
40003余额不足,请充值后再使用
40004参数错误,请查看技术文档,检查传参
40007机器人不存在或未发布
40008机器人未开通,请至市场开通后重试
40301文件类型不支持,接口会返回实际检测到的文件类型,如“当前文件类型为.gif”
40302上传文件大小不符,文件大小不超过 50M
40303文件类型不支持
40304图片尺寸不符,图像宽高须介于 20 和 10000(像素)之间
40305识别文件未上传
40306QPS超过限制,收到此状态码时请勿重试,持续请求可能触发IP流控,如需扩容请联系商务
40400无效的请求链接,请检查链接是否正确
30203基础服务故障,请稍后重试
500服务器内部错误