# 增值税发票文字识别OCR · 增值税发票识别

> 本文档为机器可读 Markdown，便于 AI / SDK 自动对接。页面原文：https://www.wapi.cn/api_detail/185/359.html
> 纯文本地址：`https://www.wapi.cn/api_detail/185/359.html?format=md`

## 概览

- **接口名称**：增值税发票识别
- **子接口**：增值税发票文字识别OCR（ID `359`）
- **接口简介**：支持对增值税普票、专票、全电发票（新版全国统一电子发票，专票/普票）、卷票、区块链发票的所有字段进行结构化识别，包括发票基本信息、销售方及购买方信息、商品信息、价税信息等，其中五要素字段的识别准确率超过 99.9%； 同时，支持对增值税卷票的 21 个关键字段进行识别，包括发票类型、发票代码、发票号码、机打号码、机器编号、收款人、销售方名称、销售方纳税人识别号、开票日期、购买方名称、购买方纳税人识别号、项目、单价、数量、金额、税额、合计金额(小写)、合计金额(大写)、校验码、省、市，四要素字段的识别准确率可达95%。
- **计费说明**：按次
- **请求地址**：`https://uaqy.api.storeapi.net/pyi/185/359`（支持 http/https）
- **请求方式**：`GET,POST`
- **返回格式**：`json,xml`
- **Content-Type（POST）**：`application/x-www-form-urlencoded;charset=utf-8`

## 请求参数

| 名称 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `appid` | 是 | String | 应用ID，在后台我的应用查看或者添加 | 1 |
| `format` | 否 | String | 返回数据格式类型，每个接口已经说明支持返回格式:json,xml, jsonp调用方法说明 | json |
| `sign` | 是 | String | 1.使用Md5方式验证，参数按一定规则md5后返回的字符串，详情点击这里阅读 2.使用Hash验证方式，直接跟上密钥即可。如何设置hash验证 通过我的应用里面修改验证方式 | 52a9dbe274a5c537bbf7a53e2d66c09f |
| `time` | 否 | String | 请求时传递的当前服务器时间戳 | 1545829466 |
| `url_image` | 否 | String | 行驶证图片URL(同driving_license_url) |  |

## 签名（MD5）

按参数名排序后拼接「键名+值」，空值不参与；末尾直接追加 32 位密钥（密钥不写键名）：

```
sign = MD5(appid1formatjsontime1545829466{secret})
```

说明：示例中 `appid` 默认为 `1`，请替换为「我的应用」中的 appid；密钥为应用 Secret。

## 返回参数

| 名称 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `amount_in_figuers` | 否 | String | 价税合计(小写) | 7.99 |
| `amount_in_words` | 否 | String | 价税合计(大写) | 柒圆玖角玖分 |
| `check_code` | 否 | String | 校验码。增值税专票无此参数 | 61084601970281760289 |
| `checker` | 否 | String | 复核 | 张三 |
| `city` | 否 | String | 所属城市 | 厦门市 |
| `codeid` | 否 | Integer | 状态码，返回10000状态都会进行计费。具体说明可查看状态码说明 | 10000 |
| `commodity_amount` | 否 | Array | 金额 |  |
| `commodity_end_date` | 否 | Array | 通行日期止。仅通行费增值税电子普通发票含有此参数 |  |
| `commodity_name` | 否 | Array | 货物名称 |  |
| `commodity_num` | 否 | Array | 数量 |  |
| `commodity_plate_num` | 否 | Array | 车牌号。仅通行费增值税电子普通发票含有此参数 |  |
| `commodity_price` | 否 | Array | 单价 |  |
| `commodity_start_date` | 否 | Array | 通行日期起。仅通行费增值税电子普通发票含有此参数 |  |
| `commodity_tax` | 否 | Array | 税额 |  |
| `commodity_tax_rate` | 否 | Array | 税率 |  |
| `commodity_type` | 否 | Array | 规格型号 |  |
| `commodity_unit` | 否 | Array | 单位 |  |
| `commodity_vehicle_type` | 否 | Array | 类型。仅通行费增值税电子普通发票含有此参数 |  |
| `invoice_code` | 否 | String | 发票代码 | 035022200111 |
| `invoice_code_confirm` | 否 | String | 发票代码的辅助校验码，一般业务情景可忽略 | 035021100111 |
| `invoice_date` | 否 | String | 开票日期 | 2022年12月13日 |
| `invoice_num` | 否 | String | 发票号码 | 17230518 |
| `invoice_num_confirm` | 否 | String | 发票号码的辅助校验码，一般业务情景可忽略 | 17230518 |
| `invoice_tag` | 否 | String | 增值税发票左上角标志。 包含：通行费、销项负数、代开、收购、成品油、其他 | 其他 |
| `invoice_type` | 否 | String | 发票种类。不同类型发票输出：普通发票、专用发票、电子普通发票、电子专用发票、通行费电子普票、区块链发票、通用机打电子发票、电子发票(专用发票)、电子发票(普通发票) | 电子普通发票 |
| `invoice_type_org` | 否 | String | 发票名称 | 厦门增值税电子普通发票 |
| `is_agent` | 否 | String | 是否代开 | 否 |
| `machine_code` | 否 | String | 机器编号。仅增值税卷票含有此参数 | 661927300875 |
| `message` | 否 | String | 请求状态说明 | 返回成功 |
| `note_drawer` | 否 | String | 开票人 | 李四 |
| `online_pay` | 否 | String | 电子支付标识。仅区块链发票含有此参数 |  |
| `password` | 否 | String | 密码区 | 29>9*44450/036+*4>05/6/6908+*2309>54>1 |
| `payee` | 否 | String | 收款人 | 李四 |
| `province` | 否 | String | 所属省份 | 福建省 |
| `purchaser_address` | 否 | String | 购方地址及电话 |  |
| `purchaser_bank` | 否 | String | 购方开户行及账号 |  |
| `purchaser_name` | 否 | String | 购方名称 | 天津****机电科技有限公司 |
| `purchaser_register_num` | 否 | String | 购方纳税人识别号 | 911201****05M9C29R |
| `remarks` | 否 | String | 备注 |  |
| `retdata` | 否 | Array | 回数据集合,可能是数据、对象或者字符串 |  |
| `row` | 否 | String | 行号 | 1 |
| `seller_address` | 否 | String | 销售方地址及电话 | 厦门市湖里区观日西二里32号801室 |
| `seller_bank` | 否 | String | 销售方开户行及账号 | 中国工商银行厦门江头支行4100022909200254537 |
| `seller_name` | 否 | String | 销售方名称 | 厦门挖码信息技术有限公司 |
| `seller_register_num` | 否 | String | 销售方纳税人识别号 | 91350206MA32JUL977 |
| `service_type` | 否 | String | 发票消费类型。不同消费类型输出：餐饮、电器设备、通讯、服务、日用品食品、医疗、交通、其他 | 服务 |
| `sheet_num` | 否 | String | 联次信息。专票第一联到第三联分别输出：第一联：记账联、第二联：抵扣联、第三联：发票联；普通发票第一联到第二联分别输出：第一联：记账联、第二联：发票联 |  |
| `time` | 否 | String | 请求时传递的当前服务器时间戳 | 1675049940 |
| `total_amount` | 否 | String | 合计金额 | 7.99 |
| `total_tax` | 否 | String | 合计税额 | *** |
| `word` | 否 | String | 内容 | 7.99 |

## JSON 返回示例

```json
{
    "codeid": "10000",
    "message": "返回成功",
    "retdata": {
        "commodity_unit": [],
        "purchaser_address": "",
        "sheet_num": "",
        "commodity_type": [],
        "total_amount": "7.99",
        "checker": "张三",
        "purchaser_bank": "",
        "password": "29>9*4<>4450\/036+*4>05\/6\/6908+*2309><><+>54>1<01<02*<7+565\/1+<\/1-1-45\/*8+09<479681>357+8*--69\/>--*3747\/76106",
        "invoice_type_org": "厦门增值税电子普通发票",
        "invoice_code_confirm": "035021100111",
        "total_tax": "***",
        "service_type": "服务",
        "commodity_tax_rate": [
            {
                "row": "1",
                "word": "免税"
            }
        ],
        "commodity_tax": [
            {
                "row": "1",
                "word": "***"
            }
        ],
        "seller_bank": "中国工商银行厦门江头支行4100022909200254537",
        "remarks": "",
        "seller_address": "厦门市湖里区观日西二里32号801室",
        "note_drawer": "李四",
        "invoice_tag": "其他",
        "invoice_num_confirm": "17230518",
        "online_pay": "",
        "payee": "李四",
        "commodity_name": [
            {
                "row": "1",
                "word": "*信息技术服务*技术服务费"
            }
        ],
        "commodity_vehicle_type": [],
        "invoice_code": "035022200111",
        "amount_in_words": "柒圆玖角玖分",
        "amount_in_figuers": "7.99",
        "city": "厦门市",
        "invoice_type": "电子普通发票",
        "commodity_end_date": [],
        "purchaser_name": "天津****机电科技有限公司",
        "invoice_date": "2022年12月13日",
        "commodity_num": [],
        "purchaser_register_num": "911201****05M9C29R",
        "machine_code": "661927300875",
        "commodity_plate_num": [],
        "check_code": "61084601970281760289",
        "seller_register_num": "91350206MA32JUL977",
        "commodity_price": [],
        "commodity_start_date": [],
        "seller_name": "厦门挖码信息技术有限公司",
        "commodity_amount": [
            {
                "row": "1",
                "word": "7.99"
            }
        ],
        "province": "福建省",
        "invoice_num": "17230518",
        "is_agent": "否"
    },
    "time": 1675049940
}
```

## 状态码说明

| 状态码 | 说明 |
| --- | --- |
| `10000` | 返回成功 |
| `10001` | appid必须指定，可以我的应用里面查看 |
| `10002` | sign值必须指定，加密规则请前往帮助中心查看 |
| `10003` | sign值验证不通过，加密规则请前往帮助中心查看 |
| `10004` | 时差不能超过10分钟，可以不传递这个参数，注意时间戳单位是秒 |
| `10005` | appid错误，请检查appid值,前往会员中心->我的应用查看或添加 |
| `10006` | 当前IP地址未授权，请前往用户中心->我的应用添加ip{@info} |
| `10007` | 应用被禁用，请联系客服处理 |
| `10008` | 应用内没有该接口，请到我的应用里面添加这个接口 |
| `10009` | api接口不存在 |
| `10010` | 您没有添加该api接口 |
| `10011` | api已经到期 |
| `10012` | 没有订购任何api,请前往购买后再操作 |
| `10013` | 该接口已经暂停使用 |
| `10014` | 未知的错误，可以联系客服处理 |
| `10015` | 参数个数错误 |
| `10019` | {@info} |
| `10017` | time必须是整型 |
| `10018` | 次数不足 |
| `10020` | 子接口不存在,可能已经被关闭 |
| `10021` | 服务器发生错误 |
| `10022` | 帐户余额不足，请充值！ |
| `10023` | 订单提交成功，等待回调结果 |
| `10024` | 调试模式数据 |
| `10025` | 查无数据 |

## 对接提示

1. 先在挖数据（wapi.cn）创建应用，获取 `appid` 与密钥。
2. 按上方参数组装请求，计算 `sign` 后调用接口地址。
3. 可用在线测试工具：`https://www.wapi.cn/api_debug/185/359.html`