시작하기

이 가이드에서는 환경을 설정하고 DocMap API로 첫 번째 추출 요청을 보내는 과정을 안내합니다.

사전 준비 사항

시작하기 전에 다음 사항을 확인하세요:

1. DocMap 계정 -- 아직 계정이 없다면 docmap.io에서 가입하세요.
2. 하나 이상의 추출 템플릿 -- 문서에서 추출할 필드를 정의하는 템플릿을 대시보드에서 생성하세요.

TIP

템플릿은 추출하려는 데이터의 구조를 정의합니다. 예를 들어, 송장 템플릿에는 vendor_name, invoice_number, total_amount, line_items 배열 등의 필드가 포함될 수 있습니다. API 호출을 하기 전에 대시보드에서 템플릿을 생성하고 관리할 수 있습니다.

기본 URL

모든 API 요청은 다음 주소로 전송됩니다:

https://api.docmap.io

모든 엔드포인트는 /v1/ 접두사가 붙습니다. 예를 들어, 추출 엔드포인트는 다음과 같습니다:

https://api.docmap.io/v1/extractions/run

API 키 생성

1. 대시보드 > 설정 > API 키로 이동합니다.
2. API 키 생성을 클릭합니다.
3. 키에 설명적인 이름을 지정합니다 (예: "프로덕션 서버" 또는 "로컬 개발").
4. 만료 기간을 선택합니다.
5. 키를 즉시 복사합니다 -- 키는 한 번만 표시되며 이후에는 조회할 수 없습니다.

WARNING

API 키를 안전하게 보관하세요. 생성 시 한 번만 표시됩니다. 키를 분실한 경우 새 키를 생성해야 합니다.

API 키는 dm_live_... 형식이며 모든 요청의 Authorization 헤더에 사용됩니다.

첫 번째 요청

API 상태 확인 엔드포인트로 설정을 검증합니다:

curl

curl https://api.docmap.io/health

TypeScript

const res = await fetch('https://api.docmap.io/health')
const data = await res.json()
console.log(data) // { status: "ok" }

Python

import requests
res = requests.get('https://api.docmap.io/health')
print(res.json())  # {"status": "ok"}

모든 것이 정상적으로 작동하면 다음 응답을 받게 됩니다:

{ "status": "ok" }

첫 번째 추출 실행

API 키와 템플릿이 준비되면 PDF에서 구조화된 데이터를 추출할 수 있습니다. PDF 파일을 base64 문자열로 인코딩하여 /v1/extractions/run 엔드포인트로 전송합니다.

curl

curl -X POST https://api.docmap.io/v1/extractions/run \
  -H "Authorization: Bearer dm_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "your-template-id",
    "fileName": "invoice.pdf",
    "pdfBase64": "JVBERi0xLjQ...",
    "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: 'your-template-id',
    fileName: 'invoice.pdf',
    pdfBase64: 'JVBERi0xLjQ...', // base64-encoded PDF
    mimeType: 'application/pdf',
  }),
})

const data = await response.json()
console.log(data)

Python

import requests
import base64

api_key = "dm_live_your_api_key"

# Read and encode the PDF
with open("invoice.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": "your-template-id",
        "fileName": "invoice.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

print(response.json())

응답 예시

성공적인 추출은 템플릿 필드와 일치하는 추출된 데이터를 반환합니다:

{
  "id": "ext_abc123",
  "templateId": "your-template-id",
  "fileName": "invoice.pdf",
  "status": "completed",
  "data": {
    "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
      }
    ]
  },
  "createdAt": "2024-11-20T14:30:00.000Z"
}

사용량 확인

플랜 한도 내에서 유지하기 위해 API 사용량을 모니터링하세요:

curl

curl https://api.docmap.io/v1/usage \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const res = await fetch('https://api.docmap.io/v1/usage', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
})
const usage = await res.json()
console.log(usage)

Python

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

다음 단계

첫 번째 추출을 완료했으니, 나머지 문서를 살펴보세요:

• 인증 -- API 키 및 보안 모범 사례에 대해 알아보세요.
• API 레퍼런스 -- 사용 가능한 모든 엔드포인트의 전체 레퍼런스입니다.