如何利用 OCR API 與 Webhook 打造應付帳款自動化管道
了解如何建立一個可靠的應付帳款自動化管道。使用非同步 OCR API 上傳發票，並透過安全的 Webhook 接收結構化資料。
處理發票是應付帳款作業中的典型瓶頸。人工輸入資料不僅耗時，還容易出錯。即使導入了 OCR API，若採用輪詢（polling）方式來檢查任務是否完成，效率依然不彰。這種做法會增加系統的複雜度、延遲和不必要的網路流量。一個真正自動化的應付帳款流程，不該是反覆詢問「好了沒？」的等待，而應該是事件驅動（event-driven）的，在資料準備好的那一刻立即回應。
這正是 space-ocr 非同步處理的核心理念。您不必在發出請求後，還得佔用連線空等回應。您可以一次上傳整批發票，然後立即回頭處理其他工作。API 會回傳一組任務識別碼，確認檔案已收到。接著，我們的引擎會處理每一張圖片。當一張發票成功讀取後，系統會直接向您應用程式的端點發送通知。這個通知是透過 Webhook——一個簡單、可靠的 HTTP POST 請求——來完成，請求中就包含了結構化的資料。
整個流程非常直接：您只需發起一次 POST /upload 呼叫，附上您的發票圖片。API 會立即回傳一個包含待處理任務的陣列。稍後，您的伺服器會透過 Webhook 收到一個 ocr.completed 事件。該事件的酬載（payload）包含完整的擷取結果，從供應商名稱（如「弥生サンブル」）到每一筆品項及其在頁面上的對應座標，無一不包。為了確保可靠性，每次上傳都可以在請求標頭中加入 Idempotency-Key。若您因網路問題需要重試請求，發送相同的金鑰能保證您不會重複建立處理任務。
const express = require('express');
const crypto = require('crypto');
// Middleware to get the raw body for signature verification
const rawBodySaver = (req, res, buf, encoding) => {
if (buf && buf.length) {
req.rawBody = buf.toString(encoding || 'utf8');
}
};
const app = express({ verify: rawBodySaver });
const webhookSecret = process.env.SPACE_OCR_WEBHOOK_SECRET;
app.post('/webhook', (req, res) => {
const signature = req.get('X-Spaceocr-Signature');
if (!signature) {
return res.status(400).send('Missing signature');
}
const hmac = crypto.createHmac('sha256', webhookSecret);
const digest = Buffer.from(hmac.update(req.rawBody).digest('hex'), 'hex');
const receivedSignature = Buffer.from(signature, 'hex');
if (!crypto.timingSafeEqual(digest, receivedSignature)) {
return res.status(400).send('Invalid signature');
}
// Signature is valid, now process the event
const event = JSON.parse(req.rawBody);
switch (event.event) {
case 'ocr.completed':
const { result } = event.data;
console.log(`OCR successful for ${result.name}:`, result.values);
// TODO: Add structured data to your accounting system
break;
case 'ocr.failed':
const { error } = event.data;
console.error(`OCR failed for ${event.data.name}:`, error.message);
break;
case 'webhook.test':
console.log('Webhook test successful!');
break;
default:
console.log(`Unhandled event type: ${event.event}`);
}
res.status(200).send({ received: true });
});
app.listen(3000, () => console.log('Webhook receiver listening on port 3000'));space-ocr 是如何在頁面上定位資料的？底層的語言模型會回傳擷取出的文字，並附上其可能位置的 token 提示。接著，我們的引擎會執行一個關鍵的驗證步驟：將擷取出的值，逐一字元地與頁面上實際偵測到的 OCR 符號進行比對。這個過程會產生一個介于 0.0 到 1.0 之間的 match_ratio 分數。分數若達到 0.85 或更高，即表示為高信度的匹配。最終的座標會以 0-1000 的標準化邊界框（bounding box）形式回傳，與原始圖片的像素尺寸無關。
我們認為，建立這類自動化流程的門檻不應過高。透過 API 處理的每張圖片，費用固定為 $0.05。每個帳戶每月還享有 100 次的免費掃描額度。更重要的是，如果 OCR 任務因圖片無法辨識而失敗，您完全不需付費。費用只與成功的資料擷取掛鉤，讓您能以低風險的方式開始自動化您的應付帳款作業。
- 公開一個公共端點您的伺服器需要一個公開的網址。在本地開發時，可以使用 ngrok 這類服務將您的本機伺服器暴露到網際網路上。
- 註冊您的 Webhook 網址在 space-ocr 的儀表板設定中，新增您的公開端點網址。請安全地複製產生的 Webhook 密鑰。
- 實作簽章驗證使用我們提供的程式碼範例，對每個傳入的請求驗證其 `X-Spaceocr-Signature` 標頭，以確保請求的真實性。
- 處理「ocr.completed」事件當一個有效的事件送達時，解析 `data.result` 物件，並將結構化的發票資料傳遞給您的會計系統或資料庫。
- 非同步上傳發票向 `POST /upload` 發起一個包含您檔案的請求。API 會立即回傳任務詳情，而不會等待 OCR 完成。
- 確認事件並進行監控您的端點應快速回傳一個 2xx 狀態碼以確認收到事件。您可以在儀表板中監控傳送日誌，以了解是否有任何問題。