API 文件 · v2.0
ScanBills 發票辨識 API
透過 AI 自動辨識收據、發票中的關鍵資訊。支援直接上傳圖片或 PDF、或串接 Google Drive 資料夾與 Google Sheet,批次處理多份文件並回傳結構化 JSON 資料。
開始使用
快速開始
購買點數後即可開始使用。直接上傳圖片是最快的整合方式,無需設定 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 陣列、creditsUsed 及 creditsRemaining。
請求標頭
| 標頭 | 類型 | 說明 |
|---|---|---|
| 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 自動辨識每份文件中的發票資訊。適合大量批次處理需求。
支援的檔案格式:JPEG、PNG、PDF、HEIC 及其他常見圖片格式。每份文件若包含多張發票,皆會一併辨識並以陣列回傳。
請求標頭
| 標頭 | 類型 | 說明 |
|---|---|---|
| Authorization | string | 格式為 Bearer <token>,Token 由購買點數方案後取得 |
| Content-Type | string | application/json |
請求本體
folderId 與 sheetId 擇一提供即可。
| 參數 | 類型 | 說明 |
|---|---|---|
| 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
缺少必要參數,
folderId 與 sheetId 至少需提供其中一個。
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 連結
})