space ocr
아티클문서
developer

OCR API와 웹훅으로 AP 자동화 파이프라인 구축하기

안정적인 미지급금 자동화 파이프라인 구축 방법을 알아보세요. 비동기 OCR API로 인보이스를 업로드하고, 보안 웹훅을 통해 구조화된 데이터를 받아보세요.

7 분 분량· 2026-06-29

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

AP 자동화를 통해 처리되는 인보이스
인보이스 입력, 구조화된 데이터와 웹훅 출력.

이것이 바로 space-ocr 비동기 처리 방식의 핵심 원리입니다. 요청을 보내고 연결을 계속 유지하는 대신, 여러 인보이스를 한 번에 업로드하고 바로 다른 작업을 시작할 수 있습니다. API는 파일이 정상적으로 수신되었음을 확인하는 작업 식별자 목록을 즉시 반환합니다. 그 후 저희 엔진이 각 이미지를 처리합니다. 인보이스 인식이 성공적으로 완료되면, 애플리케이션의 엔드포인트로 알림이 직접 전송됩니다. 이 알림은 구조화된 데이터를 포함한 간단하고 신뢰성 높은 HTTP POST 요청, 즉 웹훅(webhook)을 통해 이루어집니다.

작업 흐름은 간단합니다. 인보이스 이미지를 첨부하여 POST /upload를 한 번 호출하면, 응답으로 대기 중인 작업 배열을 받게 됩니다. 잠시 후, 서버는 웹훅을 통해 ocr.completed 이벤트를 수신합니다. 이 이벤트의 페이로드에는 "弥生サンブル"과 같은 공급업체 이름부터 각 라인 아이템과 페이지 내 좌표 정보까지, 추출된 모든 결과가 포함되어 있습니다. 안정성을 높이기 위해 모든 업로드 요청에 Idempotency-Key 헤더를 포함할 수 있습니다. 네트워크 오류로 요청을 재시도할 때 동일한 키를 보내면 중복된 처리 작업이 생성되는 것을 방지할 수 있습니다.

webhook-receiver.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
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'));
✓ Verified

space-ocr는 어떻게 페이지에서 데이터 위치를 찾아낼까요? 기반 언어 모델이 추출된 텍스트와 함께 예상 위치를 가리키는 토큰 힌트를 반환합니다. 그러면 저희 엔진은 핵심적인 검증 단계를 수행합니다. 바로 추출된 값을 페이지에서 실제로 감지된 OCR 기호들과 글자 단위로 하나씩 대조하는 것입니다. 이 과정을 통해 0.0에서 1.0 사이의 match_ratio 점수가 생성됩니다. 0.85 이상의 점수는 신뢰도 높은 일치를 의미합니다. 최종 좌표는 원본 이미지의 픽셀 크기와 무관하게 0-1000으로 정규화된 경계 상자(bounding box)로 반환됩니다.

이러한 자동화 시스템은 누구나 쉽게 이용할 수 있어야 합니다. API를 통해 처리되는 이미지 한 장당 가격은 100원입니다. 모든 계정에는 매월 100건의 무료 스캔이 제공됩니다. 중요한 점은, 이미지를 읽을 수 없어 OCR 작업이 실패하는 경우에는 비용이 청구되지 않는다는 것입니다. 성공적으로 데이터를 추출한 경우에만 비용을 지불하므로, 부담 없이 미지급금 처리 자동화를 시작할 수 있습니다.

  1. 공개 엔드포인트 노출하기
    서버는 공개 URL이 필요합니다. 로컬 개발 환경에서는 ngrok과 같은 서비스를 사용하여 로컬 서버를 인터넷에 노출할 수 있습니다.
  2. 웹훅 URL 등록하기
    space-ocr 대시보드 설정에서 공개 엔드포인트 URL을 추가하세요. 생성된 웹훅 시크릿은 안전하게 복사해 두어야 합니다.
  3. 시그니처 검증 구현하기
    제공된 코드 샘플을 사용하여 모든 수신 요청의 `X-Spaceocr-Signature` 헤더를 검증하고 요청이 신뢰할 수 있는지 확인하세요.
  4. 'ocr.completed' 이벤트 처리하기
    유효한 이벤트가 도착하면 `data.result` 객체를 파싱하여 구조화된 인보이스 데이터를 회계 시스템이나 데이터베이스로 전달하세요.
  5. 비동기식으로 인보이스 업로드하기
    파일과 함께 `POST /upload` 요청을 보내세요. API는 OCR 작업이 끝날 때까지 기다리지 않고 즉시 작업 세부 정보를 반환합니다.
  6. 이벤트 수신 확인 및 모니터링
    엔드포인트는 수신 확인을 위해 신속하게 2xx 상태 코드를 반환해야 합니다. 대시보드에서 전송 로그를 모니터링하며 문제가 없는지 확인하세요.
웹훅 엔드포인트가 다운되면 어떻게 되나요?
space-ocr은 최대 6시간 동안 지수 백오프(exponential backoff) 방식으로 자동으로 재전송을 시도합니다. 5xx 서버 오류, 408, 429 또는 타임아웃 발생 시 재시도하며, 전송 로그는 30일간 보관됩니다.
웹훅 요청이 실제로 space-ocr에서 온 것인지 어떻게 확인하나요?
모든 웹훅 요청에는 `X-Spaceocr-Signature` 헤더가 포함됩니다. 이 헤더에는 고유한 시크릿 키로 서명된 요청 본문의 HMAC-SHA256 시그니처가 담겨 있습니다. 서버에서 이 시그니처를 반드시 검증해야 합니다.
한 번의 API 호출로 여러 인보이스를 업로드할 수 있나요?
네, `POST /upload` 엔드포인트는 multipart/form-data 형식을 지원하므로 단일 요청에 여러 `files` 필드를 포함할 수 있습니다. 각 파일에 대한 작업 정보가 담긴 배열이 반환됩니다.
OCR 작업이 실패해도 비용이 청구되나요?
아니요. OCR 작업이 실패하면 `ocr.failed` 이벤트가 발생하며 스캔 비용은 자동으로 환불됩니다. 성공적으로 추출된 건에 대해서만 비용을 지불하시면 됩니다.
폴링 방식과 웹훅 사용의 차이점은 무엇인가요?
폴링은 작업 완료 여부를 확인하기 위해 `GET /jobs/{jobId}`를 반복적으로 호출해야 합니다. 반면 웹훅은 이벤트 기반 방식으로, 저희 서버가 결과가 준비되는 즉시 사용자의 엔드포인트로 결과를 전송(push)해 줍니다. 따라서 훨씬 효율적이며 실시간 업데이트가 가능합니다.
애플리케이션에서 업로드를 안전하게 재시도하려면 어떻게 해야 하나요?
`/upload` 엔드포인트는 `Idempotency-Key` 헤더를 지원합니다. 24시간 이내에 동일한 키를 보내면 중복된 작업이 생성되는 대신 기존의 캐시된 응답을 받게 되어 이중 처리를 방지할 수 있습니다.

지금 바로 AP 워크플로우 자동화를 시작하세요

API 키를 발급받고 매월 제공되는 100건의 무료 스캔으로 개발을 시작해 보세요.

관련 글