如何利用 OCR API 和 Webhook 构建应付账款自动化流程
了解如何构建一个可靠的应付账款自动化流程。通过异步 OCR API 上传发票，并使用安全的 Webhook 接收结构化数据。
处理发票是典型的业务瓶颈。手动录入数据不仅慢，还容易出错。即使使用了 OCR API，采用轮询方式检查任务是否完成也效率低下，这会增加系统的复杂性、延迟和不必要的网络流量。一个真正自动化的应付账款工作流不应该需要反复查询“好了吗？”，而应是事件驱动的，在数据就绪时立即响应。
这就是 space-ocr 异步处理背后的核心理念。您无需发起请求后一直保持连接等待，而是可以上传一批发票后立即处理其他任务。API 会立刻返回一个任务标识符列表，确认文件已收到。我们的引擎随后会处理每张图片。当一张发票成功读取后，一个通知会通过 Webhook 直接发送到您应用程序的端点——这是一个简单可靠的 HTTP POST 请求，其中包含了所有结构化数据。
整个流程非常直接：您只需调用一次 POST /upload 并附上您的发票图片。作为响应，您会得到一个待处理任务的数组。稍后，您的服务器会通过 Webhook 收到一个 ocr.completed 事件。该事件的有效载荷 (payload) 中包含了完整的提取结果，从供应商名称（如“弥生サンブル”）到每个明细项目及其在页面上的对应坐标。为了保证可靠性，每次上传都可以在请求头中包含一个 Idempotency-Key。当您需要重试网络请求时，发送相同的 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 范围内的归一化边界框形式返回，与原始图像的像素尺寸无关。
我们致力于让这种自动化技术普及化。通过 API 处理的每张图片统一定价为 $0.05。每个账户每月还享有 100 次免费扫描额度。重要的是，如果 OCR 任务因图像无法识别而失败，我们不会收取任何费用。成本与成功提取数据直接挂钩，这让您能以低风险的方式开始您的应付账款自动化。
- 暴露一个公共端点您的服务器需要一个公共 URL。在本地开发时，可以使用 ngrok 等服务将您的本地服务器暴露到互联网上。
- 注册您的 Webhook URL在 space-ocr 控制面板的设置中，添加您的公共端点 URL。安全地复制生成的 Webhook 密钥。
- 实现签名验证使用我们提供的代码示例，对每个传入请求的 `X-Spaceocr-Signature` 请求头进行验证，以确保其真实性。
- 处理 'ocr.completed' 事件当一个有效的事件到达时，解析 `data.result` 对象，并将结构化的发票数据传递给您的会计系统或数据库。
- 异步上传发票向 `POST /upload` 发起一个包含文件的请求。API 将立即返回任务详情，而无需等待 OCR 完成。
- 确认事件并监控您的端点应快速返回一个 2xx 状态码以确认收到事件。在控制面板中监控投递日志，以便排查任何问题。