> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速启动

> 参考示例，快速将国内通用票据识别API接入到您的系统和应用流程中。

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

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

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

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

<iframe src="https://dllf.intsig.net/download/2025/Solution/textin_web/17c9fe6ace284ea1b99912b58bd674ed.pdf" width="100%" height="600px" />

### 先决条件：获取API Key

使用通用票据识别API处理文档时，您需要先获取API Key。请先登录后前往 [TextIn工作台 - 账号与开发者信息](https://www.textin.com/console/dashboard/setting) 获取您的 x-ti-app-id 和 x-ti-secret-code 。

### 前置准备

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

```python theme={null}
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、xml、单帧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：指定多页样本中需要识别的样本，可以使用"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结构说明](/bill/bill-getjson)中查看，也可以在[API](/api-reference/endpoint/bill)中查看和调试。

```json theme={null}
{
    "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     | 服务器内部错误                                    |   |