快速启动 - Textin 智能文档解析

为什么使用国内通用票据识别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())

请求体说明

支持以下两种请求格式

Content-Type: application/octet-stream 要上传的图片，目前支持jpg、png、bmp、pdf、tiff、ofd、单帧gif等大部分格式，pdf和ofd文件支持多页请注意，请求体的数据格式为本地文件的二进制流，非 FormData 或其他格式。文件大小不超过 50M，图像宽高须介于 20 和 10000（像素）之间。
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：指定多页样本中需要识别的样本，可以使用”1,3,2”形式来逐页选择，或”2-4”形式来连续选择，返回结果会重新排序以遵照源文件顺序，默认为空，识别所有页面。
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     // 当前识别图片所在页
        }
    ]
}

错误码说明

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

Documentation Index

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

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

​先决条件：获取API Key

​前置准备

​请求体说明

​URL参数说明

​返回结果示例

​错误码说明