추출 실행

POST /v1/extractions/run

PDF 문서에서 추출을 실행합니다. 지정된 템플릿을 사용하여 문서를 처리하고, 템플릿의 필드 정의에 맞는 구조화된 JSON으로 추출된 데이터를 반환합니다.

사용해 보기

이 엔드포인트를 Swagger UI에서 대화형으로 테스트할 수 있습니다.

인증 필요

Authorization 헤더에 API 키를 포함하세요.

요청

헤더

헤더	값	필수
Authorization	Bearer <token>	예
Content-Type	application/json	예

쿼리 파라미터

파라미터	타입	필수	설명
async	string	아니오	"true"로 설정하면 완료를 기다리지 않고 processing 상태로 즉시 반환합니다. 기본 동작(생략 또는 "false")은 동기 방식입니다.

본문

필드	타입	필수	설명
templateId	string	예	사용할 추출 템플릿의 ID.
fileName	string	예	문서의 원본 파일명.
pdfBase64	string	예	PDF 파일의 Base64 인코딩된 내용.
mimeType	string	예	파일의 MIME 타입. 허용 값: application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document.
runId	string	아니오	관련 추출을 배치 실행으로 그룹화하기 위한 선택적 식별자.

코드 예제

curl

curl -X POST https://api.docmap.io/v1/extractions/run \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "fileName": "invoice-2024-001.pdf",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YW...",
    "mimeType": "application/pdf"
  }'

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/extractions/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 'tmpl_8f3a2b1c4d5e6f7g',
    fileName: 'invoice-2024-001.pdf',
    pdfBase64: pdfBuffer.toString('base64'),
    mimeType: 'application/pdf',
  }),
})

const { data } = await response.json()
console.log(data.extractedData)

Python

import requests
import base64

api_key = "dm_live_abc123def456ghi789jkl012mno345"

with open("invoice-2024-001.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api.docmap.io/v1/extractions/run",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "templateId": "tmpl_8f3a2b1c4d5e6f7g",
        "fileName": "invoice-2024-001.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

data = response.json()["data"]
print(data["extractedData"])

응답

상태: 200 OK

응답 본문은 data 객체로 감싸져 있습니다.

필드

필드	타입	설명
id	string	고유 추출 ID (extract_ 접두사).
userId	string	이 추출을 소유한 사용자의 ID.
templateId	string	추출에 사용된 템플릿의 ID.
templateName	string	사용된 템플릿의 표시 이름.
fileName	string	업로드된 문서의 원본 파일명.
status	"processing" | "completed" | "failed"	현재 추출 상태. 비동기 모드 사용 시 "processing", 성공 시 "completed", 오류 시 "failed".
extractedData	object | null	템플릿 필드에 맞는 추출된 데이터. 추출 실패 시 null.
error	string | null	실패를 설명하는 오류 메시지. 추출 성공 시 null.
variables	Variable[]	추출 중 사용된 템플릿 변수 정의 배열.
source	"dashboard" | "api"	추출이 트리거된 방식.
runId	string | null	배치 실행 ID (요청에서 제공된 경우).
processingTimeMs	number | null	총 처리 시간(밀리초).
createdAt	string	추출이 생성된 ISO 8601 타임스탬프.

예시

{
  "data": {
    "id": "extract_9k2m4n6p8q0r1s3t",
    "userId": "uid_a1b2c3d4e5f6",
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "templateName": "Invoice Template",
    "fileName": "invoice-2024-001.pdf",
    "status": "completed",
    "extractedData": {
      "vendor_name": "Acme Corp",
      "invoice_number": "INV-2024-001",
      "invoice_date": "2024-11-15",
      "total_amount": 1250.00,
      "currency": "USD",
      "line_items": [
        {
          "description": "Widget A",
          "quantity": 10,
          "unit_price": 125.00
        }
      ]
    },
    "error": null,
    "variables": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      },
      {
        "name": "total_amount",
        "type": "number",
        "description": "Total invoice amount"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": 3842,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

비동기 모드

기본적으로 API는 추출이 완료될 때까지 대기한 후 응답합니다 (동기 방식). 장시간 실행되는 추출의 경우 비동기 모드를 사용하여 즉시 응답을 받고 결과를 폴링할 수 있습니다.

URL에 ?async=true를 추가하여 비동기 모드를 활성화합니다:

curl -X POST "https://api.docmap.io/v1/extractions/run?async=true" \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "fileName": "invoice-2024-001.pdf",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YW...",
    "mimeType": "application/pdf"
  }'

응답: 202 Accepted

응답은 동기 응답과 동일한 형태이지만, status가 "processing", extractedData가 null, processingTimeMs가 null입니다:

{
  "data": {
    "id": "extract_9k2m4n6p8q0r1s3t",
    "userId": "uid_a1b2c3d4e5f6",
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "templateName": "Invoice Template",
    "fileName": "invoice-2024-001.pdf",
    "status": "processing",
    "extractedData": null,
    "error": null,
    "variables": [...],
    "source": "api",
    "runId": null,
    "processingTimeMs": null,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

반환된 id를 사용하여 status가 "completed" 또는 "failed"로 변경될 때까지 추출 조회 엔드포인트를 폴링하세요.

WARNING

추출이 "processing" 상태로 2분 이상 유지되면 실패로 간주하세요. 자동 타임아웃은 없으며 -- 드문 경우(예: 서버 재시작)에 레코드가 "processing" 상태로 무기한 유지될 수 있습니다.

오류

상태	코드	설명
401	UNAUTHORIZED	누락, 유효하지 않거나 만료된 API 키 / 토큰.
404	NOT_FOUND	지정된 템플릿을 찾을 수 없거나 계정에 속하지 않습니다.
429	USAGE_LIMIT_EXCEEDED	플랜의 월간 추출 한도에 도달했습니다.
500	INTERNAL_ERROR	추출 처리 중 예기치 않은 오류가 발생했습니다.