Documents AI by Veryfi

实时 OCR 与数据提取 API —— 从收据、发票、银行对账单、W-9 表格、采购订单等文档中提取结构化数据，支持文档分类、欺诈检测以及原始 OCR 文本输出。

获取 API 密钥： https://app.veryfi.com/api/settings/keys/

了解更多： https://veryfi.com

快速开始

处理收据和发票：

curl -X POST "https://api.veryfi.com/api/v8/partner/documents/" \
  -H "Content-Type: multipart/form-data" \
  -H "Client-Id: $VERYFI_CLIENT_ID" \
  -H "Authorization: apikey $VERYFI_USERNAME:$VERYFI_API_KEY" \
  -F "file=@invoice.pdf"

响应示例：

{
  "id": 62047612,
  "created_date": "2026-02-19",
  "currency_code": "USD",
  "date": "2026-02-18 14:22:00",
  "document_type": "receipt",
  "category": "餐饮与娱乐",
  "is_duplicate": false,
  "vendor": {
    "name": "Starbucks",
    "address": "123 Main St, San Francisco, CA 94105"
  },
  "line_items": [
    {
      "id": 1,
      "order": 0,
      "description": "Caffe Latte Grande",
      "quantity": 1,
      "price": 5.95,
      "total": 5.95,
      "type": "food"
    }
  ],
  "subtotal": 5.95,
  "tax": 0.52,
  "total": 6.47,
  "payment": {
    "type": "visa",
    "card_number": "1234"
  },
  "ocr_text": "STARBUCKS\n123 Main St...",
  "img_url": "https://scdn.veryfi.com/documents/...",
  "pdf_url": "https://scdn.veryfi.com/documents/..."
}

处理银行对账单：

curl -X POST "https://api.veryfi.com/api/v8/partner/bank-statements/" \
  -H "Content-Type: multipart/form-data" \
  -H "Client-Id: $VERYFI_CLIENT_ID" \
  -H "Authorization: apikey $VERYFI_USERNAME:$VERYFI_API_KEY" \
  -F "file=@bank-statement.pdf"

响应示例：

{
  "id": 4820193,
  "created_date": "2026-02-19T12:45:00.000000Z",
  "bank_name": "Chase",
  "bank_address": "270 Park Avenue, New York, NY 10017",
  "account_holder_name": "Jane Doe",
  "account_holder_address": "456 Oak Ave, San Francisco, CA 94110",
  "account_number": "****7890",
  "account_type": "支票账户",
  "routing_number": "021000021",
  "currency_code": "USD",
  "statement_date": "2026-01-31",
  "period_start_date": "2026-01-01",
  "period_end_date": "2026-01-31",
  "beginning_balance": 12500.00,
  "ending_balance": 11835.47,
  "accounts": [
    {
      "number": "****7890",
      "beginning_balance": 12500.00,
      "ending_balance": 11835.47,
      "summaries": [
        { "name": "总存款", "total": 3200.00 },
        { "name": "总取款", "total": 3864.53 }
      ],
      "transactions": [
        {
          "order": 0,
          "date": "2026-01-05",
          "description": "直接存款 - ACME Corp 薪资",
          "credit_amount": 3200.00,
          "debit_amount": null,
          "balance": 15700.00,
          "category": "收入"
        },
        {
          "order": 1,
          "date": "2026-01-12",
          "description": "房租支付 - 456 Oak Ave",
          "credit_amount": null,
          "debit_amount": 2800.00,
          "balance": 12900.00,
          "category": "住房"
        },
        {
          "order": 2,
          "date": "2026-01-20",
          "description": "PG&E 电费账单",
          "credit_amount": null,
          "debit_amount": 1064.53,
          "balance": 11835.47,
          "category": "公用事业"
        }
      ]
    }
  ],
  "pdf_url": "https://scdn.veryfi.com/bank-statements/...",
  "img_url": "https://scdn.veryfi.com/bank-statements/..."
}

设置步骤

1. 获取 API 密钥

# 访问 API 认证凭据页面
https://app.veryfi.com/api/settings/keys/

保存您的 API 密钥：

export VERYFI_CLIENT_ID="your_client_id_here"
export VERYFI_USERNAME="your_username_here"
export VERYFI_API_KEY="your_api_key_here"

2. OpenClaw 配置（可选）

推荐做法：使用环境变量（最安全）：

{
  skills: {
    entries: {
      "veryfi-documents-ai": {
        enabled: true,
        // 密钥从环境变量加载：
        // VERYFI_CLIENT_ID, VERYFI_USERNAME, VERYFI_API_KEY
      },
    },
  },
}

替代方案：将密钥存入配置文件（需谨慎使用）：

{
  skills: {
    entries: {
      "veryfi-documents-ai": {
        enabled: true,
        env: {
          VERYFI_CLIENT_ID: "your_client_id_here",
          VERYFI_USERNAME: "your_username_here",
          VERYFI_API_KEY: "your_api_key_here",
        },
      },
    },
  },
}

安全提示： 若将 API 密钥存储在 ~/.openclaw/openclaw.json 中：

• 设置文件权限：chmod 600 ~/.openclaw/openclaw.json
• 永远不要将此文件提交到版本控制系统
• 尽可能优先使用环境变量或代理的密钥存储
• 定期更换密钥，并在支持的情况下限制 API 密钥的权限

curl -X POST "https://api.veryfi.com/api/v8/partner/documents/" \
  -H "Content-Type: application/json" \
  -H "Client-Id: $VERYFI_CLIENT_ID" \
  -H "Authorization: apikey $VERYFI_USERNAME:$VERYFI_API_KEY" \
  -d '{
    "file_url": "https://example.com/invoice.pdf"
  }'

从护照中提取数据

curl -X POST "https://api.veryfi.com/api/v8/partner/any-documents/" \
  -H "Content-Type: multipart/form-data" \
  -H "Client-Id: $VERYFI_CLIENT_ID" \
  -H "Authorization: apikey $VERYFI_USERNAME:$VERYFI_API_KEY" \
  -F "file=@passport.jpg" \
  -F "blueprint_name=passport"

从支票中提取数据

curl -X POST "https://api.veryfi.com/api/v8/partner/checks/" \
  -H "Content-Type: multipart/form-data" \
  -H "Client-Id: $VERYFI_CLIENT_ID" \
  -H "Authorization: apikey $VERYFI_USERNAME:$VERYFI_API_KEY" \
  -F "file=@check.jpg"

从 W-9 表单中提取数据

curl -X POST "https://api.veryfi.com/api/v8/partner/w9s/" \
  -H "Content-Type: multipart/form-data" \
  -H "Client-Id: $VERYFI_CLIENT_ID" \
  -H "Authorization: apikey $VERYFI_USERNAME:$VERYFI_API_KEY" \
  -F "file=@w9.pdf"

从 W-2 和 W-8 表单中提取数据

W-2 和 W-8 表单没有专用的端点。请使用 any-documents 端点，并指定相应的蓝图名称：

# W-2
curl -X POST "https://api.veryfi.com/api/v8/partner/any-documents/" \
  -H "Content-Type: multipart/form-data" \
  -H "Client-Id: $VERYFI_CLIENT_ID" \
  -H "Authorization: apikey $VERYFI_USERNAME:$VERYFI_API_KEY" \
  -F "file=@w2.pdf" \
  -F "blueprint_name=w2"

# W-8
curl -X POST "https://api.veryfi.com/api/v8/partner/any-documents/" \
  -H "Content-Type: multipart/form-data" \
  -H "Client-Id: $VERYFI_CLIENT_ID" \
  -H "Authorization: apikey $VERYFI_USERNAME:$VERYFI_API_KEY" \
  -F "file=@w8.pdf" \
  -F "blueprint_name=w8"

注意： W-2 和 W-8 在 /classify/ 接口中显示为分类类型，但其数据提取通过 Any Document 端点完成。请勿向 /api/v8/partner/w2s/ 或 /api/v8/partner/w8s/ 发送请求——这些端点不存在。

从文档中获取原始 OCR 文本

所有提取端点的响应中都包含一个 ocr_text 字段，其中包含文档的原始纯文本内容。此功能适用于您希望自行处理文本或将其传递给大语言模型（LLM）的场景。

# 提取并使用 jq 获取 ocr_text
curl -X POST "https://api.veryfi.com/api/v8/partner/documents/" \
  -H "Content-Type: multipart/form-data" \
  -H "Client-Id: $VERYFI_CLIENT_ID" \
  -H "Authorization: apikey $VERYFI_USERNAME:$VERYFI_API_KEY" \
  -F "file=@document.pdf" \
  | jq '.ocr_text'

注意： ocr_text 是纯文本，不是 Markdown 格式。如需 Markdown 格式的输出，请在提取后将 ocr_text 传入 LLM 进行重格式化。

对文档进行分类

在不进行完整数据提取的情况下识别文档类型。适用于文档路由、上传前过滤或批量分类。

curl -X POST "https://api.veryfi.com/api/v8/partner/classify/" \
  -H "Content-Type: multipart/form-data" \
  -H "Client-Id: $VERYFI_CLIENT_ID" \
  -H "Authorization: apikey $VERYFI_USERNAME:$VERYFI_API_KEY" \
  -F "file=@document.pdf"

注意： 默认情况下，API 会针对 15 种内置类型进行分类。您也可以通过传递 document_types 数组来自定义分类类别（见下方示例）。

响应示例：

{
  "id": 81023456,
  "document_type": {
    "score": 0.97,
    "value": "invoice"
  }
}

默认文档类型：receipt（收据）、invoice（发票）、purchase_order（采购订单）、bank_statement（银行对账单）、check（支票）、w2（W-2）、w8（W-8）、w9（W-9）、statement（声明）、contract（合同）、credit_note（贷项通知单）、remittance_advice（汇款通知）、business_card（名片）、packing_slip（装箱单）、other（其他）。

若要对自定义类型进行分类，请传递 document_types 数组：

curl -X POST "https://api.veryfi.com/api/v8/partner/classify/" \
  -H "Content-Type: multipart/form-data" \
  -H "Client-Id: $VERYFI_CLIENT_ID" \
  -H "Authorization: apikey $VERYFI_USERNAME:$VERYFI_API_KEY" \
  -F "file=@document.pdf" \
  -F 'document_types=["lease_agreement", "utility_bill", "pay_stub"]'

高级功能

获取收据、发票、支票和银行对账单 API 的边界框信息

用于布局分析，可获取元素坐标：

-F "bounding_boxes=true"
-F "confidence_details=true"

使用场景

建议使用 Veryfi Documents AI 的情况：

• 发票和收据的数据提取
• 处理银行对账单
• 提取支票中的数据
• 文档分类与路由
• 提取任意其他文档的数据
• 获取文档的原始 OCR 文本

不建议使用的情况：

• 视频或音频转录
• 网络搜索或实时数据查询
• 图像生成或编辑
• 非文档类二进制文件（如电子表格、代码、可执行文件）
• 未经确认可安全交由第三方处理的文档（详见安全部分）

最佳实践

技能：Veryfi Documents AI

版本：1.0.1

分块：3/5

可用蓝图列表：

缺少所需文档类型？

如果需要提取数据的文档类型（蓝图）未在列表中，请在此创建：

https://app.veryfi.com/inboxes/anydocs?tab=blueprints

边界框与置信度：

• 添加 -F "bounding_boxes=true" 以获取元素坐标
• 添加 -F "confidence_details=true" 以获取字段级别的置信度分数

支持的输入方式：

• file — 多部分文件上传
• file_url — 可公开访问的 URL
• file_data — base64 编码内容（需以 JSON 身体形式发送，包含 file_name 和 file_data 字段）

响应结构

收据 / 发票（/api/v8/partner/documents/）

{
  "id": 62047612,
  "created_date": "2026-02-19T00:00:00.000000Z",
  "updated_date": "2026-02-19T00:00:05.000000Z",
  "currency_code": "USD",
  "date": "2026-02-18 14:22:00",
  "due_date": "2026-03-18",
  "document_type": "receipt",
  "category": "餐饮与娱乐",
  "is_duplicate": false,
  "is_document": true,
  "invoice_number": "INV-2026-001",
  "account_number": "ACCT-12345",
  "order_date": "2026-02-18",
  "delivery_date": null,
  "vendor": {
    "name": "星巴克",
    "address": "123 主街，旧金山，加利福尼亚州 94105",
    "phone_number": "+1 415-555-0100",
    "email": null,
    "vat_number": null,
    "reg_number": null
  },
  "bill_to": {
    "name": "简·多",
    "address": "456 橡树大道，旧金山，加利福尼亚州 94110"
  },
  "ship_to": {
    "name": null,
    "address": null
  },
  "line_items": [
    {
      "id": 1,
      "order": 0,
      "description": "大杯拿铁",
      "quantity": 1,
      "price": 5.95,
      "total": 5.95,
      "tax": 0.52,
      "tax_rate": 8.75,
      "discount": null,
      "type": "food",
      "sku": null,
      "upc": null,
      "category": "餐饮与娱乐",
      "section": null,
      "date": null,
      "start_date": null,
      "end_date": null
    }
  ],
  "tax_lines": [
    {
      "order": 0,
      "name": "销售税",
      "rate": 8.75,
      "total": 0.52,
      "base": 5.95
    }
  ],
  "subtotal": 5.95,
  "tax": 0.52,
  "tip": 0.00,
  "discount": 0.00,
  "total": 6.47,
  "payment": {
    "type": "visa",
    "card_number": "1234"
  },
  "reference_number": null,
  "notes": null,
  "img_url": "https://scdn.veryfi.com/documents/...",
  "pdf_url": "https://scdn.veryfi.com/documents/...",
  "ocr_text": "STARBUCKS\n123 Main St...",
  "meta": {
    "total_pages": 1,
    "processed_pages": 1,
    "fraud": {
      "score": 0.01,
      "color": "green",
      "decision": "非欺诈",
      "types": []
    }
  }
}

支票（/api/v8/partner/checks/）

{
  "id": 9301847,
  "created_date": "2026-02-19T00:00:00.000000Z",
  "updated_date": "2026-02-19T00:00:03.000000Z",
  "amount": 1500.00,
  "amount_text": "一千五百整",
  "check_number": "4021",
  "date": "2026-02-15",
  "currency_code": "USD",
  "check_type": "personal_check",
  "payer_name": "约翰·史密斯",
  "payer_address": "789 橡树街，奥斯汀，德克萨斯州 78701",
  "receiver_name": "阿克米管道公司 LLC",
  "receiver_address": null,
  "bank_name": "富国银行",
  "bank_address": "420 蒙哥马利街，旧金山，加利福尼亚州 94104",
  "memo": "发票 #2026-038",
  "is_signed": true,
  "micr": {
    "routing_number": "121000248",
    "account_number": "****5678",
    "serial_number": "4021",
    "raw": "⑆121000248⑆ ****5678⑈ 4021",
    "branch": null,
    "institution": null
  },
  "fractional_routing_number": "12-1/1200",
  "routing_from_fractional": "121000248",
  "endorsement": {
    "is_endorsed": true,
    "is_signed": true,
    "mobile_or_remote_deposit": {
      "checkbox": false,
      "instructions": false
    }
  },
  "handwritten_fields": ["amount", "amount_text", "date", "receiver_name", "memo"],
  "fraud": {
    "score": 0.02,
    "color": "green",
    "types": [],
    "pages": [
      {
        "is_lcd": { "score": 0.98, "value": false },
        "ai_generated": { "score": 0.99, "value": false },
        "four_corners_detected": true
      }
    ]
  },
  "img_thumbnail_url": "https://scdn.veryfi.com/checks/...",
  "pdf_url": "https://scdn.veryfi.com/checks/..."
}

银行对账单（/api/v8/partner/bank-statements/）

markdown

id: 4820193

created_date: "2026-02-19T12:45:00.000000Z"

updated_date: "2026-02-19T12:45:10.000000Z"

bank_name: Chase

bank_address: 270 Park Avenue, New York, NY 10017

account_holder_name: Jane Doe

account_holder_address: 456 Oak Ave, San Francisco, CA 94110

account_number: ****7890

account_type: Checking

routing_number: 021000021

currency_code: USD

statement_date: 2026-01-31

period_start_date: 2026-01-01

period_end_date: 2026-01-31

beginning_balance: 12500.00

ending_balance: 11835.47

minimum_due: null

due_date: null

accounts:

- number: ****7890

beginning_balance: 12500.00

ending_balance: 11835.47

summaries:

- name: Total Deposits

total: 3200.00

- name: Total Withdrawals

total: 3864.53

transactions:

- order: 0

date: 2026-01-05

posted_date: 2026-01-05

description: Direct Deposit - ACME Corp Payroll

credit_amount: 3200.00

debit_amount: null

balance: 15700.00

category: Income

vendor: ACME Corp

- order: 1

date: 2026-01-12

posted_date: 2026-01-12

description: Rent Payment - 456 Oak Ave

credit_amount: null

debit_amount: 2800.00

balance: 12900.00

category: Housing

vendor: null

fraud:

score: 0.01

color: green

types: []

pdf_url: https://scdn.veryfi.com/bank-statements/...

img_thumbnail_url: https://scdn.veryfi.com/bank-statements/...

安全与隐私

数据处理

重要提示： 上传至 Veryfi 的文档将通过 https://api.veryfi.com 传输，并在 AWS 服务器上进行处理。

上传敏感文档前，请注意：

• 查阅 Veryfi 的隐私政策和数据保留策略：https://www.veryfi.com/terms/
• 确认数据删除或保留的时间周期
• 建议先使用非敏感的示例文档进行测试
• 如有疑问，请联系 support@veryfi.com

最佳实践建议：

• 在确认服务的安全性和合规性之前，不要上传高度敏感的个人身份信息（如社保号、医疗记录、金融账户号码）
• 若可用，使用权限受限的 API 密钥（最小权限原则）
• 监控 API 使用日志以检测未经授权的访问
• 永远不要将 API 密钥记录或提交到代码仓库或示例中

文件大小限制

• 最大文件大小： 每个文档不超过 20 MB
• 页数限制： 默认情况下，收据/发票最多 15 页，银行对账单最多 50 页。如需提高限制，请联系客服

运行保障措施

• 始终使用环境变量或安全的密钥存储来管理 API 密钥
• 永远不要在代码示例或文档中包含真实的 API 密钥
• 在示例中使用占位符值，如 "your_api_key_here"
• 对配置文件设置适当的文件权限（例如 JSON 配置文件设为 600）
• 启用 API 密钥轮换，并通过仪表板监控使用情况

速率限制

Veryfi 对每个账户实施速率限制，具体限制取决于您的计划层级。

一般建议：

• 免费/基础版： 并发请求限制较低；避免集中并发请求
• 企业/商业版： 支持更高吞吐量；具体细节请联系客服
• 若触发速率限制，API 将返回 HTTP 429 Too Many Requests
• 实现指数退避机制：等待 1 秒 → 2 秒 → 4 秒 → 8 秒后重试
• 对于高负载场景，请联系 support@veryfi.com 或访问 https://veryfi.com 了解企业方案

故障排查

400 Bad Request：

• 请确保仅提供一个输入参数：file、file_url 或 file_data（base64 格式）
• 使用 file_data 时，应以 JSON 身体形式发送（非 multipart），并包含 file_name 和 file_data 字段
• 确认用户名、API 密钥和 Client ID 是否有效
• 检查返回的 JSON 响应中的 message 字段以获取具体错误信息

401 Unauthorized：

• Client-Id、VERYFI_USERNAME 或 VERYFI_API_KEY 错误或已过期
• 请在 https://app.veryfi.com/api/settings/keys/ 中核对凭证
• 确保 Authorization 头部格式为 apikey USERNAME:API_KEY（无额外空格）
• 若怀疑密钥泄露，请立即更换

413 Payload Too Large：

• 文件超过 20 MB 限制
• 上传前压缩文件或降低图像分辨率
• 若页面数超出计划限制（发票最多 15 页，银行对账单最多 50 页），可拆分多页 PDF

429 Too Many Requests：

• 已超过当前计划的速率限制
• 实现指数退避并重试
• 如需持续高负载支持，请联系 support@veryfi.com 升级计划

500 / 5xx 服务器错误：

• 临时的服务器端问题 —— 等待短暂延迟后重试
• 若问题持续存在，请检查 Veryfi 状态页面或联系支持团队

缺少置信度分数：

• 在请求中添加 confidence_details=true，以在响应中包含 score 和 ocr_score 字段
• 添加 bounding_boxes=true 可同时获取 bounding_box 和 bounding_region 坐标信息

W-2 / W-8 接口返回 404：

• 不存在 /w2s/ 或 /w8s/ 接口 —— 请使用 /any-documents/ 并设置 blueprint_name=w2 或 blueprint_name=w8

提示

• 将 VERYFI_CLIENT_ID、VERYFI_USERNAME 和 VERYFI_API_KEY 存储在环境变量中，而非硬编码
• 若需获取字段级别的准确度评分或元素坐标，请使用 confidence_details=true 和 bounding_boxes=true
• 处理大量文档时，先通过 /classify/ 接口进行分类，再将文档路由至相应的提取接口
• 保持文件大小低于 20 MB，并遵守页面限制（发票最多 15 页，银行对账单最多 50 页）
• 在生产环境中处理敏感数据前，务必使用样例文档进行测试
• 若缺少所需的模板，可在 [https://app.veryfi.com/inboxes/anydocs?tab=blueprints](https://app.veryfi.com/inboxes/anydocs?tab=blueprints) 创建自定义模板
• 响应中的 ocr_text 字段提供原始提取文本 —— 如需转换为 Markdown 或进一步处理，可将其传递给 LLM
• 使用 base64 输入时，始终包含 file_name，以便 Veryfi 正确推断文件类型

参考资料

• API 文档: https://docs.veryfi.com/
• Veryfi 官网: https://veryfi.com
• Veryfi SDKs: https://github.com/veryfi
• 获取 API Key: https://app.veryfi.com/api/settings/keys/
• 隐私政策: https://www.veryfi.com/terms/
• 技术支持: support@veryfi.com