OCR API와 웹훅으로 AP 자동화 파이프라인 구축하기
안정적인 미지급금 자동화 파이프라인 구축 방법을 알아보세요. 비동기 OCR API로 인보이스를 업로드하고, 보안 웹훅을 통해 구조화된 데이터를 받아보세요.
인보이스 처리는 대표적인 병목 구간입니다. 수동 데이터 입력은 느리고 오류가 발생하기 쉽습니다. OCR API를 사용하더라도 작업 완료 여부를 계속 확인하는 폴링(polling) 방식은 비효율적입니다. 시스템 복잡도와 지연 시간을 높이고 불필요한 트래픽만 유발할 뿐입니다. 진정한 미지급금 자동화 워크플로우는 '아직 안 끝났나?'라고 계속 물어보며 기다리는 방식이어서는 안 됩니다. 데이터가 준비되는 즉시 반응하는 이벤트 기반(event-driven) 방식이어야 합니다.

이것이 바로 space-ocr 비동기 처리 방식의 핵심 원리입니다. 요청을 보내고 연결을 계속 유지하는 대신, 여러 인보이스를 한 번에 업로드하고 바로 다른 작업을 시작할 수 있습니다. API는 파일이 정상적으로 수신되었음을 확인하는 작업 식별자 목록을 즉시 반환합니다. 그 후 저희 엔진이 각 이미지를 처리합니다. 인보이스 인식이 성공적으로 완료되면, 애플리케이션의 엔드포인트로 알림이 직접 전송됩니다. 이 알림은 구조화된 데이터를 포함한 간단하고 신뢰성 높은 HTTP POST 요청, 즉 웹훅(webhook)을 통해 이루어집니다.
작업 흐름은 간단합니다. 인보이스 이미지를 첨부하여 POST /upload를 한 번 호출하면, 응답으로 대기 중인 작업 배열을 받게 됩니다. 잠시 후, 서버는 웹훅을 통해 ocr.completed 이벤트를 수신합니다. 이 이벤트의 페이로드에는 "弥生サンブル"과 같은 공급업체 이름부터 각 라인 아이템과 페이지 내 좌표 정보까지, 추출된 모든 결과가 포함되어 있습니다. 안정성을 높이기 위해 모든 업로드 요청에 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는 어떻게 페이지에서 데이터 위치를 찾아낼까요? 기반 언어 모델이 추출된 텍스트와 함께 예상 위치를 가리키는 토큰 힌트를 반환합니다. 그러면 저희 엔진은 핵심적인 검증 단계를 수행합니다. 바로 추출된 값을 페이지에서 실제로 감지된 OCR 기호들과 글자 단위로 하나씩 대조하는 것입니다. 이 과정을 통해 0.0에서 1.0 사이의 match_ratio 점수가 생성됩니다. 0.85 이상의 점수는 신뢰도 높은 일치를 의미합니다. 최종 좌표는 원본 이미지의 픽셀 크기와 무관하게 0-1000으로 정규화된 경계 상자(bounding box)로 반환됩니다.
이러한 자동화 시스템은 누구나 쉽게 이용할 수 있어야 합니다. API를 통해 처리되는 이미지 한 장당 가격은 100원입니다. 모든 계정에는 매월 100건의 무료 스캔이 제공됩니다. 중요한 점은, 이미지를 읽을 수 없어 OCR 작업이 실패하는 경우에는 비용이 청구되지 않는다는 것입니다. 성공적으로 데이터를 추출한 경우에만 비용을 지불하므로, 부담 없이 미지급금 처리 자동화를 시작할 수 있습니다.
- 공개 엔드포인트 노출하기서버는 공개 URL이 필요합니다. 로컬 개발 환경에서는 ngrok과 같은 서비스를 사용하여 로컬 서버를 인터넷에 노출할 수 있습니다.
- 웹훅 URL 등록하기space-ocr 대시보드 설정에서 공개 엔드포인트 URL을 추가하세요. 생성된 웹훅 시크릿은 안전하게 복사해 두어야 합니다.
- 시그니처 검증 구현하기제공된 코드 샘플을 사용하여 모든 수신 요청의 `X-Spaceocr-Signature` 헤더를 검증하고 요청이 신뢰할 수 있는지 확인하세요.
- 'ocr.completed' 이벤트 처리하기유효한 이벤트가 도착하면 `data.result` 객체를 파싱하여 구조화된 인보이스 데이터를 회계 시스템이나 데이터베이스로 전달하세요.
- 비동기식으로 인보이스 업로드하기파일과 함께 `POST /upload` 요청을 보내세요. API는 OCR 작업이 끝날 때까지 기다리지 않고 즉시 작업 세부 정보를 반환합니다.
- 이벤트 수신 확인 및 모니터링엔드포인트는 수신 확인을 위해 신속하게 2xx 상태 코드를 반환해야 합니다. 대시보드에서 전송 로그를 모니터링하며 문제가 없는지 확인하세요.