ifly-ocr-invoice

OCR-based invoice and receipt recognition using the iFlytek (科大讯飞) API. Extracts structured fields from photos or scans of Chinese invoices and bills.

When to Use

• User provides an invoice/receipt image and wants structured data extracted
• Need to digitize paper invoices (增值税发票、出租车票、火车票、医疗票据 etc.)
• Expense report automation — extract amounts, dates, vendor info from receipts

Prerequisites

• Python 3 (standard library only, no pip install needed)
• Environment variables (get from 讯飞控制台):
  • XFYUN_APP_ID — Application ID
  • XFYUN_API_KEY — API Key
  • XFYUN_API_SECRET — API Secret

Supported Image Formats

png, jpg/jpeg, bmp, gif, tif/tiff, pdf

Usage

The script is at scripts/invoice.py relative to this skill directory.

Basic Recognition

python3 scripts/invoice.py /path/to/invoice.png

Options

Examples

# Recognize a VAT invoice
python3 scripts/invoice.py ./vat_invoice.jpg

# Recognize a medical receipt with raw output
python3 scripts/invoice.py ./medical_bill.png --raw

# Recognize a taxi receipt
python3 scripts/invoice.py ./taxi_receipt.jpg

Output Format (default)

Human-readable structured fields:

票据类型: 增值税普通发票

发票代码: 012345678901
发票号码: 12345678
开票日期: 2026年03月06日
金额: ¥1,234.56
...

Output Format (--raw)

Full API JSON response including all metadata and encoded payload.

Authentication

Uses HMAC-SHA256 signature-based auth (讯飞鉴权). The script handles all signing automatically — just set the three environment variables.

API Details

• Endpoint: POST https://api.xf-yun.com/v1/private/sc45f0684
• Auth: HMAC-SHA256 signature in URL query parameters
• Image limit: Check your service tier on 讯飞控制台

哎呀，出错了怎么办？(´；ω；`)

别慌别慌～ 对照下面的表格看看，大部分问题都能自己解决哦！如果试了还是不行，随时来问我，我们一起解决～ ✧٩(ˊᗜˋ*)و✧

🌟 常见错误快速排查表

📋 完整错误码列表（超详细版）

💬 常见问题 Q&A

Q: 一直提示 "10105 Unauthorized" 怎么破？(╥﹏╥)

别急别急，十有八九是环境变量的问题！按这个顺序检查：

1. 三个环境变量都设好了吗？（XFYUN_APP_ID, XFYUN_API_KEY, XFYUN_API_SECRET）
2. 值是直接从讯飞控制台复制的吗？手打的话很容易漏掉字符哦！

✨ 快速确认环境变量（复制粘贴运行）：

# macOS / Linux 用户复制这行：
echo "XFYUN_APP_ID: $XFYUN_APP_ID | XFYUN_API_KEY: $XFYUN_API_KEY | XFYUN_API_SECRET: $XFYUN_API_SECRET"

# Windows 用户在 cmd 里运行这行：
echo XFYUN_APP_ID: %XFYUN_APP_ID% ^|^| XFYUN_API_KEY: %XFYUN_API_KEY% ^|^| XFYUN_API_SECRET: %XFYUN_API_SECRET%

如果显示为空或者显示错误，那就是还没设好哦！设置方法：

• macOS/Linux: 在终端运行 export XFYUN_APP_ID=你的值，然后 echo 'export XFYUN_APP_ID=你的值' >> ~/.zshrc 永久保存
• Windows: 按 Win+R → 输入 sysdm.cpl → 高级 → 环境变量 → 新建

Q: 提示 "10200 read data timeout" 怎么办呀？(;´Д`)

一般是这几个原因：

• 路径写错啦（注意相对路径和绝对路径的区别）
• 图片文件坏掉了（用系统预览打开看看？）
• 文件名有中文或特殊符号（试试改成英文名？）

✨ 快速确认文件是否存在（复制粘贴运行）：

# 检查文件是否存在（替换成你的文件路径）
ls -la /path/to/your/invoice.png

# 或者用这个命令查看当前目录下的图片文件
ls -la *.png *.jpg *.jpeg *.bmp *.pdf 2>/dev/null

如果显示 "No such file or directory"，那就是路径不对哦！

Q: 提示 "11201 auth no enough license" 是啥意思呀？

哈哈，免费额度用光光啦！讯飞免费版每天有限制次数～

• 方案1：休息一下，第二天再战！(额度会刷新)
• 方案2：豪气地购买付费套餐 🚀

💰 需要更多次数？点击这里直接购买：https://www.xfyun.cn/services/Invoice_recognition?target=price

Q: 图片太大识别好慢怎么破？(´；ω；`)

来来来，试试这些小技巧：

• 压缩图片到 1-2MB
• 裁剪掉多余的背景部分
• 分辨率保持在 2000x2000 以内

✨ 温馨小贴士

遇到问题先别慌！环境变量和文件路径 是最容易出错的环节，检查一遍往往就能搞定～

如果还有问题，把错误信息里的 sid 字段保存下来哦，这个可以帮讯飞技术定位问题！

记住：你一定可以的！ (๑•̀ㅂ•́)و✧ 有问题随时来问我呀～

Tips

• Ensure the image is clear and well-lit for best accuracy
• Crop to just the invoice area if possible (reduces noise)
• PDF support means you can pass scanned documents directly