ScanBills
API 文件 · v2.0

ScanBills 發票辨識 API

透過 AI 自動辨識收據、發票中的關鍵資訊。支援直接上傳圖片或 PDF、或串接 Google Drive 資料夾與 Google Sheet,批次處理多份文件並回傳結構化 JSON 資料。

回應格式 application/json
認證方式 Bearer Token

快速開始

購買點數後即可開始使用。直接上傳圖片是最快的整合方式,無需設定 Google Drive。

1
購買點數方案,取得 API Token
前往 scanbills.com 選擇點數方案完成付款,專屬 API Token 將顯示在確認頁面,請妥善保存。
2
上傳發票圖片
以 Bearer Token 呼叫 /api/upload,透過 multipart/form-data 上傳圖片,每個檔案消耗 1 點。
3
接收結構化發票資料
API 即時回傳辨識結果,含發票號碼、日期、金額等欄位與剩餘點數。若有大量批次需求,可改用 /api/scan-folder 串接 Google Drive。

直接上傳檔案

POST /api/upload 直接上傳圖片進行辨識
Bearer Token 需在 Authorization 標頭帶入 Token,每個檔案消耗 1 點

直接上傳圖片進行 AI 辨識,無需設定 Google Drive。回傳 invoices 陣列、creditsUsedcreditsRemaining

請求標頭

標頭類型說明
Authorization string 格式為 Bearer <token>,Token 由購買點數方案後取得
Content-Type string multipart/form-data

請求本體

參數類型說明
files File[] 欄位名稱固定為 files,支援 JPEG、PNG、HEIC 等圖片格式,每個檔案上限 4.8 MB
上傳數量自動受剩餘點數限制,超出點數的檔案不會被處理。點數用盡時回傳 402
cURL 範例
curl -X POST https://scanbills.com/api/upload \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "files=@receipt1.jpg" \
  -F "files=@receipt2.jpg"

回應

回應 · 200 OK
{
  "results": [
    {
      "url": "https://static.scanbills.com/20260325/abc123.jpg",
      "fileName": "receipt1.jpg",
      "invoices": [
        {
          "發票號碼": "AB-12345678",
          "日期": "2026/03/25",
          "總計": "1500",
          "買方統編": null,
          "賣方統編": "87654321",
          "稅金": "71",
          "店家": "某某餐廳",
          "Misc": {}
        }
      ],
      "data": { "...": "同 invoices[0]" }
    }
  ],
  "processedFiles": 1,
  "creditsUsed": 1,
  "creditsRemaining": 99
}

掃描 Google Drive 資料夾

POST /api/scan-folder 批次 AI 辨識發票
Bearer Token 需在 Authorization 標頭帶入 Token

掃描指定 Google Drive 資料夾中的所有圖片與 PDF 檔案,或從 Google Sheet 讀取檔案清單,並以 AI 自動辨識每份文件中的發票資訊。適合大量批次處理需求。

支援的檔案格式:JPEGPNGPDFHEIC 及其他常見圖片格式。每份文件若包含多張發票,皆會一併辨識並以陣列回傳。

請求標頭

標頭 類型 說明
Authorization string 格式為 Bearer <token>,Token 由購買點數方案後取得
Content-Type string application/json

請求本體

folderIdsheetId 擇一提供即可。

參數 類型 說明
folderId string Google Drive 資料夾 ID(從資料夾網址取得)擇一
sheetId string Google Sheet ID(從試算表網址取得)擇一
sheetRange string 試算表讀取範圍,預設為 A:A(第一欄)選填
請求本體 · 資料夾模式
{
  "folderId": "1a2B3c4D5e6F7g8H9i0J"
}
請求本體 · Google Sheet 模式
{
  "sheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
  "sheetRange": "A:A"
}

回應

回應 · 200 OK
{
  "results": [
    {
      "url": "https://static.scanbills.com/20260325/abc123.processed",
      "fileURL": "https://drive.google.com/file/d/FILE_ID/view",
      "fileName": "receipt.jpg",
      "sourceFile": "receipt.jpg",
      "page": 1,
      "invoices": [
        {
          "發票號碼": "AB-12345678",
          "日期": "2026/03/25",
          "總計": "1500",
          "買方統編": "12345678",
          "賣方統編": "87654321",
          "稅金": "71",
          "店家": "某某餐廳",
          "Misc": { "備註": "值" }
        }
      ],
      "data": { "...": "同 invoices[0],保留向下相容" }
    },
    {
      "fileURL": "https://drive.google.com/file/d/FAILED_ID/view",
      "fileName": "blurry.jpg",
      "error": "Failed to process file"
    }
  ],
  "totalFiles": 10,
  "processedFiles": 9,
  "source": "drive_folder",
  "creditsUsed": 9,
  "creditsRemaining": 491
}

注意事項

  • 每個 result 物件的 invoices 為陣列格式,即使只辨識到一張發票也是陣列
  • data 欄位保留向下相容性,其值等同於 invoices[0]
  • 辨識失敗的檔案會包含 error 欄位,不會影響其他檔案的辨識結果
  • 若一張圖片中有多張發票(例如一次拍多張收據),invoices 陣列會包含多個元素
  • source 欄位值為 "drive_folder""google_sheet"
  • 每個資料夾最多處理 100 個檔案

發票欄位說明

以下為 invoices 陣列中每個物件的欄位定義。若欄位無法辨識,值為 null

發票號碼
發票號碼,通常為 2 個大寫英文字母加 8 位數字
例:AB-12345678
日期
交易日期,格式為 YYYY/MM/DD
總計
發票總金額(含稅)
稅金
稅額,對應發票上的稅金、稅額或稅
買方統編
買方統一編號(8 位數字),通常出現在發票右側
賣方統編
賣方(店家)統一編號(8 位數字)
店家
商店或廠商名稱
Misc
其他辨識到的欄位,為扁平的 key-value 物件

錯誤代碼

400
缺少必要參數,folderIdsheetId 至少需提供其中一個。
401
Token 無效或點數已用盡。請前往 scanbills.com 購買點數方案取得新 Token。
500
伺服器內部錯誤,請稍後重試或聯絡我們。
個別檔案辨識失敗不會使整個請求回傳錯誤狀態碼。失敗的檔案會在 results 陣列中以 error 欄位標示,其他檔案仍正常回傳。

Google Apps Script 整合

以下為完整的 Google Apps Script 範例,示範如何呼叫 ScanBills API 並將辨識結果寫入 Google Sheet。

1
設定 API Token
購買點數方案後,將取得的 Token 貼入腳本的 API_TOKEN 常數中。
2
掃描資料夾
以 Bearer Token 呼叫 /api/scan-folder,傳入 Google Drive 資料夾 ID。
3
寫入試算表
將每筆發票資料逐列寫入作用中的 Google Sheet。
Google Apps Script
function scanDriveFolder() {
  // ── 設定您的 API Token(購買點數方案後取得)────────────────
  const API_TOKEN = 'YOUR_API_TOKEN_HERE';

  // ── 掃描 Google Drive 資料夾 ──────────────────────────────
  // 從資料夾網址取得 ID,例如:
  // https://drive.google.com/drive/folders/【這段就是 folderId】
  const FOLDER_ID = 'YOUR_FOLDER_ID_HERE';

  const scanRes = UrlFetchApp.fetch('https://scanbills.com/api/scan-folder', {
    method: 'post',
    contentType: 'application/json',
    headers: {
      'Authorization': 'Bearer ' + API_TOKEN
    },
    payload: JSON.stringify({
      folderId: FOLDER_ID
    }),
    muteHttpExceptions: true
  });

  const data = JSON.parse(scanRes.getContentText());
  Logger.log(`共 ${data.totalFiles} 個檔案,成功辨識 ${data.processedFiles} 個,剩餘點數:${data.creditsRemaining}`);

  // ── 將結果寫入作用中的試算表 ──────────────────────────────
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();

  // 寫入標題列(若試算表已有資料可跳過)
  sheet.appendRow([
    '檔案名稱', '發票號碼', '日期', '總計',
    '買方統編', '賣方統編', '稅金', '店家', '頁碼'
  ]);

  data.results.forEach(result => {
    // 辨識失敗的檔案跳過
    if (result.error) {
      Logger.log('辨識失敗:' + result.fileName + ' – ' + result.error);
      return;
    }

    // 每張發票寫入一列
    result.invoices.forEach(invoice => {
      sheet.appendRow([
        result.fileName,
        invoice['發票號碼'] || '',
        invoice['日期']     || '',
        invoice['總計']     || '',
        invoice['買方統編'] || '',
        invoice['賣方統編'] || '',
        invoice['稅金']     || '',
        invoice['店家']     || '',
        result.page || 1
      ]);
    });
  });

  Logger.log('✓ 完成!結果已寫入試算表。');
}

使用 Google Sheet 中的檔案清單

若您的 Google Sheet A 欄已存有 Google Drive 圖片連結,可改用 sheetId 模式:

Google Sheet 模式
// 將 scanRes 的 payload 改為:
payload: JSON.stringify({
  sheetId: 'YOUR_SHEET_ID_HERE',
  sheetRange: 'A:A'  // 預設讀取第一欄的 Google Drive 連結
})