Схемы данных

На этой странице описаны модели данных, возвращаемые API DocMap. Все ответы используют формат JSON.

ExtractionRecord

Запись извлечения представляет собой результат однократной обработки PDF-документа с использованием шаблона.

typescript

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`	Идентификатор пользователя, которому принадлежит это извлечение.
`templateId`	`string`	Идентификатор шаблона, использованного для определения схемы извлечения.
`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`	`"dashboard"` — если извлечение было запущено из веб-интерфейса, `"api"` — если через API.
`runId`	`string \| null`	Если извлечение являлось частью пакетного запуска, здесь указывается общий идентификатор запуска. `null` для отдельных извлечений.
`processingTimeMs`	`number \| null`	Продолжительность извлечения в миллисекундах. `null`, если значение не было записано.
`createdAt`	`string`	Временная метка ISO 8601 создания записи извлечения.

Пример

json

{
  "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-ключа. Фактическое значение ключа и его хеш никогда не возвращаются после создания.

typescript

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`	Идентификатор пользователя, которому принадлежит этот ключ.
`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`.

Пример

json

{
  "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

Публичная проекция вебхука. Секрет подписи никогда не возвращается после создания.

typescript

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`	Идентификатор пользователя, которому принадлежит этот вебхук.
`url`	`string`	HTTPS-эндпоинт, на который отправляются POST-запросы вебхука.
`events`	`string[]`	События, на которые подписан вебхук. Значения: `"extraction.completed"`, `"extraction.failed"`.
`active`	`boolean`	Активен ли вебхук. В ответах со списком возвращаются только активные вебхуки, поэтому это значение всегда равно `true`.
`createdAt`	`string`	Временная метка ISO 8601 создания вебхука.

Пример

json

{
  "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

Переменная определяет одно поле в шаблоне извлечения. Переменные указывают ИИ, какие данные искать и в каком типе их возвращать.

typescript

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`	Описание на естественном языке, помогающее ИИ понять, что именно нужно извлечь для данного поля. Более конкретное описание даёт лучшие результаты.
`required`	`boolean`	(Необязательно) Если `true`, ИИ всегда будет пытаться вернуть значение для этого поля.
`fields`	`Variable[]`	(Необязательно) Для `type: "object"` определяет вложенные поля внутри объекта. Поддерживается рекурсия — вложенные объекты могут содержать собственные `fields`.
`arrayType`	`string`	(Необязательно) Для `type: "array"` указывает тип элементов массива. Одно из значений: `string`, `number`, `object`. Когда `arrayType` равен `"object"`, используйте `fields` для определения структуры каждого элемента.

Рекурсивная структура

Переменные поддерживают произвольную вложенность через свойство fields. Переменная типа object содержит дочерние переменные, а переменная типа array с arrayType: "object" также использует fields для описания каждого элемента массива.

Это позволяет моделировать сложные структуры документов: счета с позициями, контракты с несколькими сторонами или любые иерархические данные.

Пример: шаблон счёта с вложенными переменными

json

[
  {
    "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 — это object с пятью вложенными полями типа string.
line_items — это array объектов, каждый из которых содержит поля description, quantity, unit_price и total.
tags — это простой array строк без вложенных fields.

UsageResponse

Возвращается эндпоинтом GET /v1/usage. Показывает текущий тарифный план аутентифицированного пользователя и использование извлечений за расчётный период.

typescript

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"`).

Пример

json

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

TIP

Эндпоинт использования возвращает данные, обёрнутые в объект data, как показано выше.

ErrorResponse

Все ошибки API следуют единой структуре с машиночитаемым полем code и человекочитаемым полем message.

typescript

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

Пример

json

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

Полный список кодов ошибок, их HTTP-статусов и способов устранения см. в справочнике Коды ошибок.

Схемы данных ​

ExtractionRecord ​

Описание полей ​

Пример ​

ApiKeyPublic ​

Описание полей ​

Пример ​

WebhookPublic ​

Описание полей ​

Пример ​

Variable ​

Описание полей ​

Рекурсивная структура ​

Пример: шаблон счёта с вложенными переменными ​

UsageResponse ​

Описание полей ​

Пример ​

ErrorResponse ​

Пример ​

Схемы данных

ExtractionRecord

Описание полей

Пример

ApiKeyPublic

Описание полей

Пример

WebhookPublic

Описание полей

Пример

Variable

Описание полей

Рекурсивная структура

Пример: шаблон счёта с вложенными переменными

UsageResponse

Описание полей

Пример

ErrorResponse

Пример