xfyun-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 讯飞控制台

Error Codes

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