發票 OCR API／送貨單 OCR 轉 CSV ── 發票資料擷取 API 實作指南

curl -X POST https://api.space-ocr.com/ocr/fields \
  -H "Authorization: Bearer spocr_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/docs/delivery-0831.jpg",
    "imageType": "url",
    "fields": [
      { "name": "customer", "type": "string",
        "description": "客戶（收貨方）公司名稱",
        "near": ["御中", "様"],
        "not_near": ["登録番号", "TEL", "〒"] },
      { "name": "delivery_no", "type": "string", "required": true,
        "pattern": "^[A-Z]{2}-[0-9]{4,8}$",
        "description": "單據號" },
      { "name": "delivery_date", "type": "date",
        "label": "納品日", "description": "送貨日期" },
      { "name": "items", "type": "array",
        "description": "明細每一列對應一個元素",
        "children": [
          { "name": "name",       "type": "string" },
          { "name": "qty",        "type": "integer" },
          { "name": "unit_price", "type": "number" },
          { "name": "amount",     "type": "number" }
        ] },
      { "name": "total", "type": "number", "required": true,
        "label": "合計", "description": "合計金額" }
    ]
  }'

{
  "status": "success",
  "data": {
    "values": {
      "customer": "株式会社サンプル商事",
      "delivery_no": "DN-100482",
      "delivery_date": "令和8年8月31日",
      "items": [
        { "name": "A4 影印紙", "qty": "5", "unit_price": "480", "amount": "2,400" }
      ],
      "total": "2,400"
    },
    "cells": {
      "customer":      { "box": { "xmin": 62, "ymin": 118, "xmax": 384, "ymax": 152 },
                         "quad": [{"x":62,"y":118},{"x":384,"y":118},{"x":384,"y":152},{"x":62,"y":152}],
                         "verified": false,
                         "review": { "reasons": ["near_conflict"] },
                         "evidence": { "text_match": true, "source": "vision_symbol_match",
                                       "match_ratio": 1.0,
                                       "not_near": { "matched": "登録番号", "distance": 0.4 } } },
      "delivery_date": { "box": { "xmin": 612, "ymin": 96, "xmax": 812, "ymax": 124 },
                         "quad": [{"x":612,"y":96},{"x":812,"y":96},{"x":812,"y":124},{"x":612,"y":124}],
                         "verified": true, "review": null,
                         "evidence": { "text_match": true, "source": "vision_symbol_match", "match_ratio": 1.0 },
                         "normalized": { "value": "2026-08-31", "type": "date", "method": "deterministic" } },
      "items[0].qty":  { "box": { "xmin": 512, "ymin": 470, "xmax": 536, "ymax": 496 },
                         "quad": [{"x":512,"y":470},{"x":536,"y":470},{"x":536,"y":496},{"x":512,"y":496}],
                         "verified": true, "review": null,
                         "evidence": { "text_match": true, "source": "token_id", "match_ratio": 1.0 },
                         "normalized": { "value": 5, "type": "integer", "method": "deterministic" } },
      "total":         { "box": { "xmin": 595, "ymin": 974, "xmax": 781, "ymax": 1000 },
                         "quad": [{"x":594,"y":975},{"x":781,"y":972},{"x":781,"y":998},{"x":595,"y":1000}],
                         "verified": true, "review": null,
                         "evidence": { "text_match": true, "source": "vision_symbol_match", "match_ratio": 0.93 },
                         "normalized": { "value": 2400, "type": "number", "method": "deterministic" } }
    },
    "review": {
      "unit": "field",
      "declared": 8,
      "returned": 8,
      "boxed": 8,
      "verified": 7,
      "flagged": [
        { "path": "customer", "reasons": ["near_conflict"] }
      ],
      "by_reason": { "near_conflict": 1 }
    },
    "normalized": {
      "delivery_date": "2026-08-31",
      "items": [ { "qty": 5, "unit_price": 480, "amount": 2400 } ],
      "total": 2400
    },
    "image": { "width": 1654, "height": 2339 }
  }
}

import requests, base64, csv

with open("delivery.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.space-ocr.com/ocr/fields",
    headers={"Authorization": "Bearer spocr_xxxxxxxxxxxxxxxx"},
    json={
        "image": b64,
        "imageType": "base64",
        "fields": [
            {"name": "customer", "type": "string",
             "description": "客戶（收貨方）公司名稱",
             "near": ["御中", "様"],
             "not_near": ["登録番号", "TEL", "〒"]},
            {"name": "delivery_no", "type": "string", "required": True,
             "pattern": "^[A-Z]{2}-[0-9]{4,8}$",
             "description": "單據號"},
            {"name": "delivery_date", "type": "date",
             "label": "納品日", "description": "送貨日期"},
            {"name": "items", "type": "array",
             "description": "明細每一列對應一個元素",
             "children": [
                 {"name": "name", "type": "string", "description": "品名"},
                 {"name": "qty", "type": "integer", "description": "數量"},
                 {"name": "unit_price", "type": "number", "description": "單價"},
                 {"name": "amount", "type": "number", "description": "金額"},
             ]},
            {"name": "total", "type": "number", "required": True,
             "label": "合計", "description": "合計金額"},
        ],
    },
    timeout=200,  # 同步處理上限為 180 秒
)

data = resp.json()["data"]
values = data["values"]
norm_items = data.get("normalized", {}).get("items", [])

# 先取需要複查的欄位。件數就是 flagged 的長度
for flag in data["review"]["flagged"]:
    cell = data["cells"].get(flag["path"])
    print(flag["path"], flag["reasons"], cell["box"] if cell else None)

# 明細寫進 CSV：顯示的欄位用 values，計算的欄位用 normalized
with open("delivery.csv", "w", encoding="utf-8-sig", newline="") as out:
    w = csv.writer(out)
    w.writerow(["品名", "數量", "單價", "金額", "金額（數值）"])
    for i, row in enumerate(values.get("items", [])):
        n = norm_items[i] if i < len(norm_items) else {}
        w.writerow([row["name"], row["qty"], row["unit_price"],
                    row["amount"], n.get("amount")])

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "requestId": "req_8fa2c1"
  }
}