스키마

이 페이지는 DocMap API에서 반환하는 데이터 모델을 문서화합니다. 모든 응답은 JSON 형식을 사용합니다.

ExtractionRecord

추출 레코드는 단일 문서 추출을 나타냅니다 -- 템플릿을 기반으로 PDF를 처리한 결과입니다.

interface ExtractionRecord {
  id: string              // Unique extraction ID
  userId: string          // Owner user ID
  templateId: string      // Template used for extraction
  templateName: string    // Human-readable template name
  fileName: string        // Original uploaded file name
  status: 'processing' | 'completed' | 'failed'
  extractedData: Record<string, unknown> | null  // Structured data or null if failed
  error: string | null    // Error message if failed, null if successful
  variables: Variable[]   // Template variable definitions used
  source: 'dashboard' | 'api'  // How the extraction was initiated
  runId: string | null    // Batch run ID, null if not part of a batch
  processingTimeMs: number | null  // Processing duration in milliseconds
  createdAt: string       // ISO 8601 timestamp
}

필드 설명

필드	타입	설명
id	string	추출 레코드의 고유 식별자입니다.
userId	string	이 추출을 소유한 사용자의 ID입니다.
templateId	string	추출 스키마를 정의하는 데 사용된 템플릿의 ID입니다.
templateName	string	추출 시점의 템플릿 표시 이름입니다.
fileName	string	업로드된 파일의 원래 이름입니다 (예: "invoice-march.pdf").
status	string	추출이 실행 중일 때 (비동기 모드) "processing", 추출이 성공하면 "completed", 실패하면 "failed"입니다.
extractedData	object | null	문서에서 추출된 구조화된 데이터로, 템플릿의 변수 정의와 일치합니다. 추출이 실패한 경우 null입니다.
error	string | null	무엇이 잘못되었는지에 대한 설명입니다. 추출이 성공한 경우 null입니다.
variables	Variable[]	이 추출에 사용된 템플릿 변수 정의입니다. Variable을 참조하세요.
source	string	웹 UI에서 추출을 실행한 경우 "dashboard", API를 통해 실행한 경우 "api"입니다.
runId	string | null	추출이 일괄 실행의 일부인 경우 공유 실행 ID입니다. 개별 추출의 경우 null입니다.
processingTimeMs	number | null	추출에 소요된 시간(밀리초)입니다. 기록되지 않은 경우 null입니다.
createdAt	string	추출이 생성된 ISO 8601 타임스탬프입니다.

예제

{
  "id": "ext_kp92mf7x",
  "userId": "u_abc123",
  "templateId": "tpl_inv001",
  "templateName": "Standard Invoice",
  "fileName": "acme-invoice-2024-003.pdf",
  "status": "completed",
  "extractedData": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-003",
    "invoice_date": "2024-11-15",
    "due_date": "2024-12-15",
    "total_amount": 4750.00,
    "currency": "USD",
    "line_items": [
      {
        "description": "Cloud Hosting - Pro Plan",
        "quantity": 1,
        "unit_price": 2500.00
      },
      {
        "description": "SSL Certificate (Wildcard)",
        "quantity": 3,
        "unit_price": 750.00
      }
    ]
  },
  "error": null,
  "variables": [
    { "key": "vendor_name", "type": "string", "context": "Name of the vendor or supplier", "required": true },
    { "key": "invoice_number", "type": "string", "context": "Invoice or reference number" },
    { "key": "invoice_date", "type": "date", "context": "Date the invoice was issued" },
    { "key": "due_date", "type": "date", "context": "Payment due date" },
    { "key": "total_amount", "type": "number", "context": "Total amount due" },
    { "key": "currency", "type": "string", "context": "Currency code (e.g. USD, EUR)" },
    {
      "key": "line_items",
      "type": "array",
      "context": "Individual line items on the invoice",
      "arrayType": "object",
      "fields": [
        { "key": "description", "type": "string", "context": "Item description" },
        { "key": "quantity", "type": "number", "context": "Quantity ordered" },
        { "key": "unit_price", "type": "number", "context": "Price per unit" }
      ]
    }
  ],
  "source": "api",
  "runId": null,
  "processingTimeMs": 3842,
  "createdAt": "2024-11-20T14:30:00.000Z"
}

ApiKeyPublic

API 키의 공개 프로젝션입니다. 실제 키 값과 해시는 생성 후 반환되지 않습니다.

interface ApiKeyPublic {
  id: string              // Key ID
  userId: string          // Owner user ID
  name: string            // Label for the key
  prefix: string          // First 16 characters of the key (e.g., "dm_live_a1b2c3d4")
  expiresAt: string | null  // ISO 8601 expiration, null if never expires
  lastUsedAt: string | null // ISO 8601 last usage, null if never used
  createdAt: string       // ISO 8601 timestamp
  revoked: boolean        // Whether the key has been revoked
}

필드 설명

필드	타입	설명
id	string	API 키의 고유 식별자입니다.
userId	string	이 키를 소유한 사용자의 ID입니다.
name	string	키에 대한 사람이 읽을 수 있는 레이블입니다 (예: "Production Server").
prefix	string	키의 처음 16자로, 전체 값을 노출하지 않고 어떤 키가 사용 중인지 식별하는 데 유용합니다.
expiresAt	string | null	키가 만료되는 ISO 8601 타임스탬프입니다. 만료 없이 생성된 키의 경우 null입니다.
lastUsedAt	string | null	키가 마지막으로 요청 인증에 사용된 ISO 8601 타임스탬프입니다. 사용된 적이 없는 경우 null입니다.
createdAt	string	키가 생성된 ISO 8601 타임스탬프입니다.
revoked	boolean	키가 폐기되었는지 여부입니다. 목록 응답에서는 폐기된 키가 필터링되므로 일반적으로 false입니다.

예제

{
  "id": "key_m3x9kq72",
  "userId": "u_abc123",
  "name": "Production Server",
  "prefix": "dm_live_a1b2c3d4",
  "expiresAt": "2025-03-15T00:00:00.000Z",
  "lastUsedAt": "2025-01-10T09:22:14.000Z",
  "createdAt": "2024-12-15T10:00:00.000Z",
  "revoked": false
}

WebhookPublic

웹훅의 공개 프로젝션입니다. 서명 시크릿은 생성 후 반환되지 않습니다.

interface WebhookPublic {
  id: string              // Webhook ID
  userId: string          // Owner user ID
  url: string             // Registered endpoint URL
  events: WebhookEvent[]  // Subscribed events
  active: boolean         // Whether the webhook is active
  createdAt: string       // ISO 8601 timestamp
}

type WebhookEvent = 'extraction.completed' | 'extraction.failed'

필드 설명

필드	타입	설명
id	string	웹훅의 고유 식별자입니다.
userId	string	이 웹훅을 소유한 사용자의 ID입니다.
url	string	웹훅 POST 요청을 수신하는 HTTPS 엔드포인트입니다.
events	string[]	이 웹훅이 구독한 이벤트입니다. 값: "extraction.completed", "extraction.failed".
active	boolean	웹훅이 활성 상태인지 여부입니다. 목록 응답에서는 활성 웹훅만 반환되므로 항상 true입니다.
createdAt	string	웹훅이 생성된 ISO 8601 타임스탬프입니다.

예제

{
  "id": "webhook-abc123def456",
  "userId": "uid_a1b2c3d4e5f6",
  "url": "https://your-app.com/webhooks/docmap",
  "events": ["extraction.completed", "extraction.failed"],
  "active": true,
  "createdAt": "2025-01-15T10:00:00.000Z"
}

Variable

변수는 추출 템플릿에서 단일 필드를 정의합니다. 변수는 AI에게 어떤 데이터를 찾고 어떤 타입으로 반환할지 알려줍니다.

interface Variable {
  key: string              // Field name in extracted data
  type: 'string' | 'number' | 'date' | 'boolean' | 'object' | 'array'
  context: string          // Description/hint for the AI extractor
  required?: boolean       // Whether the field is required
  fields?: Variable[]      // Nested fields (for type: 'object')
  arrayType?: 'string' | 'number' | 'object'  // Item type (for type: 'array')
}

필드 설명

필드	타입	설명
key	string	추출된 데이터에서 키로 나타나는 필드 이름입니다. 최소 1자 이상이어야 합니다.
type	string	예상 데이터 타입입니다. string, number, date, boolean, object, array 중 하나입니다.
context	string	AI가 이 필드에서 무엇을 추출할지 이해하는 데 도움이 되는 자연어 설명입니다. 더 구체적인 컨텍스트가 더 나은 결과를 생성합니다.
required	boolean	(선택사항) true이면 AI가 항상 이 필드에 대한 값을 반환하려고 시도합니다.
fields	Variable[]	(선택사항) type: "object"인 경우 객체 내의 중첩된 필드를 정의합니다. 이는 재귀적입니다 -- 중첩된 객체는 자체 fields를 포함할 수 있습니다.
arrayType	string	(선택사항) type: "array"인 경우 배열 항목의 타입을 지정합니다. string, number, object 중 하나입니다. arrayType이 "object"인 경우 fields를 사용하여 각 항목의 구조를 정의합니다.

재귀적 구조

변수는 fields 속성을 통해 임의 깊이의 중첩을 지원합니다. object 변수는 하위 변수를 포함하고, arrayType: "object"인 array 변수도 fields를 사용하여 각 배열 항목을 설명합니다.

이를 통해 항목이 포함된 송장, 여러 당사자가 있는 계약서, 또는 기타 계층적 데이터와 같은 복잡한 문서 구조를 모델링할 수 있습니다.

예제: 중첩 변수가 있는 송장 템플릿

[
  {
    "key": "vendor_name",
    "type": "string",
    "context": "Name of the vendor or supplier company",
    "required": true
  },
  {
    "key": "invoice_number",
    "type": "string",
    "context": "Invoice or reference number"
  },
  {
    "key": "invoice_date",
    "type": "date",
    "context": "Date the invoice was issued (YYYY-MM-DD)"
  },
  {
    "key": "total_amount",
    "type": "number",
    "context": "Total amount due including tax"
  },
  {
    "key": "billing_address",
    "type": "object",
    "context": "The billing address on the invoice",
    "fields": [
      { "key": "street", "type": "string", "context": "Street address" },
      { "key": "city", "type": "string", "context": "City name" },
      { "key": "state", "type": "string", "context": "State or province" },
      { "key": "zip", "type": "string", "context": "Postal or ZIP code" },
      { "key": "country", "type": "string", "context": "Country name or code" }
    ]
  },
  {
    "key": "line_items",
    "type": "array",
    "context": "Individual line items listed on the invoice",
    "arrayType": "object",
    "fields": [
      { "key": "description", "type": "string", "context": "Item description" },
      { "key": "quantity", "type": "number", "context": "Quantity ordered" },
      { "key": "unit_price", "type": "number", "context": "Price per unit" },
      { "key": "total", "type": "number", "context": "Line total (quantity x unit_price)" }
    ]
  },
  {
    "key": "tags",
    "type": "array",
    "context": "Keywords or categories that describe this invoice",
    "arrayType": "string"
  }
]

이 예제에서:

• billing_address는 다섯 개의 중첩된 string 필드를 가진 object입니다.
• line_items는 각각 description, quantity, unit_price, total을 가진 객체의 array입니다.
• tags는 중첩된 fields 없이 문자열의 단순한 array입니다.

UsageResponse

GET /v1/usage 엔드포인트에서 반환됩니다. 인증된 사용자의 현재 플랜과 청구 기간 동안의 추출 사용량을 보여줍니다.

interface UsageResponse {
  plan: 'free' | 'starter' | 'core' | 'pro'
  usage: number            // Extractions used this period
  limit: number            // Maximum for current plan
  periodKey: string        // Current period (e.g., "2025-01")
}

필드 설명

필드	타입	설명
plan	string	사용자의 현재 플랜입니다. free, starter, core, pro 중 하나입니다.
usage	number	현재 청구 기간에 소비된 추출 횟수입니다.
limit	number	사용자의 플랜에서 허용되는 최대 추출 횟수입니다.
periodKey	string	YYYY-MM 형식의 현재 청구 기간입니다 (예: "2025-01").

예제

{
  "data": {
    "plan": "starter",
    "usage": 142,
    "limit": 500,
    "periodKey": "2025-01"
  }
}

TIP

사용량 엔드포인트는 위에 표시된 것처럼 data 객체로 감싸서 데이터를 반환합니다.

ErrorResponse

모든 API 오류는 기계가 읽을 수 있는 code와 사람이 읽을 수 있는 message로 구성된 일관된 구조를 따릅니다.

interface ErrorResponse {
  error: {
    code: string           // Machine-readable error code
    message: string        // Human-readable description
  }
}

예제

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Extraction not found"
  }
}

전체 오류 코드 목록, HTTP 상태 코드, 해결 방법은 오류 코드 레퍼런스를 참조하세요.