Получение извлечения

GET /v1/extractions/{id}

Получение одной записи извлечения по ID. Этот эндпоинт в основном используется для опроса результата асинхронного извлечения.

Попробуйте

Протестируйте этот эндпоинт интерактивно в Swagger UI.

Требуется авторизация

Укажите ваш API-ключ в заголовке Authorization.

Запрос

Заголовки

Заголовок	Значение	Обязательно
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 не найдено.