추출 조회

GET /v1/extractions/{id}

ID로 단일 추출 기록을 조회합니다. 이 엔드포인트는 주로 비동기 추출의 결과를 폴링하는 데 사용됩니다.

사용해 보기

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

인증 필요

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

요청

헤더

헤더	값	필수
Authorization	Bearer <token>	예

경로 파라미터

파라미터	타입	필수	설명
id	string	예	추출 실행 엔드포인트에서 반환된 추출 ID.

코드 예제

curl

curl https://api.docmap.io/v1/extractions/extract_9k2m4n6p8q0r1s3t \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345"

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch(
  'https://api.docmap.io/v1/extractions/extract_9k2m4n6p8q0r1s3t',
  { headers: { 'Authorization': `Bearer ${apiKey}` } },
)

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

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

response = requests.get(
    "https://api.docmap.io/v1/extractions/extract_9k2m4n6p8q0r1s3t",
    headers={"Authorization": f"Bearer {api_key}"},
)

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

응답

상태: 200 OK

응답 본문은 단일 추출 기록을 포함하는 data 객체로 감싸져 있습니다.

필드

각 필드는 추출 실행 응답과 동일합니다.

필드	타입	설명
id	string	고유 추출 ID.
userId	string	이 추출을 소유한 사용자의 ID.
templateId	string	추출에 사용된 템플릿의 ID.
templateName	string	사용된 템플릿의 표시 이름.
fileName	string	업로드된 문서의 원본 파일명.
status	"processing" | "completed" | "failed"	현재 추출 상태.
extractedData	object | null	템플릿 필드에 맞는 추출된 데이터. 처리 중이거나 실패한 경우 null.
error	string | null	실패 시 오류 메시지. 그 외에는 null.
variables	Variable[]	추출 중 사용된 템플릿 변수 정의 배열.
source	"dashboard" | "api"	추출이 트리거된 방식.
runId	string | null	배치 실행 ID (제공된 경우).
processingTimeMs	number | null	총 처리 시간(밀리초). 아직 처리 중인 경우 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",
      "total_amount": 1250.00
    },
    "error": null,
    "variables": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": 3842,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

예시 (처리 중)

{
  "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": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": null,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

폴링 패턴

비동기 추출을 사용할 때, 상태가 더 이상 "processing"이 아닐 때까지 이 엔드포인트를 폴링합니다:

TypeScript

async function pollExtraction(extractionId: string, apiKey: string) {
  const maxAttempts = 30
  const intervalMs = 2000

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.docmap.io/v1/extractions/${extractionId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } },
    )

    const { data } = await response.json()

    if (data.status !== 'processing') {
      return data
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs))
  }

  throw new Error('Extraction timed out')
}

Python

import time
import requests

def poll_extraction(extraction_id: str, api_key: str):
    max_attempts = 30
    interval_s = 2

    for _ in range(max_attempts):
        response = requests.get(
            f"https://api.docmap.io/v1/extractions/{extraction_id}",
            headers={"Authorization": f"Bearer {api_key}"},
        )

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

        if data["status"] != "processing":
            return data

        time.sleep(interval_s)

    raise TimeoutError("Extraction timed out")

TIP

2초 간격의 폴링을 권장합니다. 대부분의 추출은 5--30초 이내에 완료됩니다.

오류

상태	코드	설명
401	UNAUTHORIZED	누락, 유효하지 않거나 만료된 API 키 / 토큰.
403	FORBIDDEN	추출이 다른 사용자에게 속해 있습니다.
404	NOT_FOUND	지정된 ID의 추출이 존재하지 않습니다.