Запуск извлечения

POST /v1/extractions/run

Запуск извлечения из PDF-документа. Документ обрабатывается с использованием указанного шаблона, а извлеченные данные возвращаются в виде структурированного JSON, соответствующего определениям полей шаблона.

Попробуйте

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

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

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

Запрос

Заголовки

Заголовок	Значение	Обязательно
Authorization	Bearer <token>	Да
Content-Type	application/json	Да

Параметры запроса

Параметр	Тип	Обязательно	Описание
async	string	Нет	Установите значение "true", чтобы немедленно получить ответ со статусом processing вместо ожидания завершения. Поведение по умолчанию (не указан или "false") -- синхронное.

Тело запроса

Поле	Тип	Обязательно	Описание
templateId	string	Да	ID шаблона извлечения для использования.
fileName	string	Да	Исходное имя файла документа.
pdfBase64	string	Да	Содержимое PDF-файла, закодированное в Base64.
mimeType	string	Да	MIME-тип файла. Допустимые значения: application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document.
runId	string	Нет	Необязательный идентификатор для группировки связанных извлечений в пакетном запуске.

Примеры кода

curl

curl -X POST https://api.docmap.io/v1/extractions/run \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "fileName": "invoice-2024-001.pdf",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YW...",
    "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: 'tmpl_8f3a2b1c4d5e6f7g',
    fileName: 'invoice-2024-001.pdf',
    pdfBase64: pdfBuffer.toString('base64'),
    mimeType: 'application/pdf',
  }),
})

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

Python

import requests
import base64

api_key = "dm_live_abc123def456ghi789jkl012mno345"

with open("invoice-2024-001.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": "tmpl_8f3a2b1c4d5e6f7g",
        "fileName": "invoice-2024-001.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

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

Ответ

Статус: 200 OK

Тело ответа обернуто в объект data.

Поля

Поле	Тип	Описание
id	string	Уникальный ID извлечения (с префиксом extract_).
userId	string	ID пользователя, которому принадлежит это извлечение.
templateId	string	ID шаблона, использованного для извлечения.
templateName	string	Отображаемое имя использованного шаблона.
fileName	string	Исходное имя загруженного документа.
status	"processing" | "completed" | "failed"	Текущий статус извлечения. "processing" при использовании асинхронного режима, "completed" при успехе, "failed" при ошибке.
extractedData	object | null	Извлеченные данные, соответствующие полям шаблона. null, если извлечение не удалось.
error	string | null	Сообщение об ошибке с описанием неудачи. null, если извлечение прошло успешно.
variables	Variable[]	Массив определений переменных шаблона, использованных при извлечении.
source	"dashboard" | "api"	Способ запуска извлечения.
runId	string | null	ID пакетного запуска, если он был указан в запросе.
processingTimeMs	number | 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",
      "invoice_date": "2024-11-15",
      "total_amount": 1250.00,
      "currency": "USD",
      "line_items": [
        {
          "description": "Widget A",
          "quantity": 10,
          "unit_price": 125.00
        }
      ]
    },
    "error": null,
    "variables": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      },
      {
        "name": "total_amount",
        "type": "number",
        "description": "Total invoice amount"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": 3842,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

Асинхронный режим

По умолчанию API ожидает завершения извлечения перед отправкой ответа (синхронный режим). Для длительных извлечений вы можете использовать асинхронный режим, чтобы получить немедленный ответ и затем опрашивать результат.

Добавьте ?async=true к URL для включения асинхронного режима:

curl -X POST "https://api.docmap.io/v1/extractions/run?async=true" \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "fileName": "invoice-2024-001.pdf",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YW...",
    "mimeType": "application/pdf"
  }'

Ответ: 202 Accepted

Ответ имеет ту же структуру, что и синхронный ответ, но status будет "processing", extractedData будет null, а processingTimeMs будет null:

{
  "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": [...],
    "source": "api",
    "runId": null,
    "processingTimeMs": null,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

Используйте возвращенный id для опроса эндпоинта Получение извлечения, пока status не изменится на "completed" или "failed".

WARNING

Если извлечение остается в статусе "processing" более 2 минут, считайте его неудачным. Автоматического тайм-аута нет -- в редких случаях (например, при перезагрузке сервера) запись может оставаться в статусе "processing" бесконечно.

Ошибки

Статус	Код	Описание
401	UNAUTHORIZED	Отсутствующий, недействительный или просроченный API-ключ / токен.
404	NOT_FOUND	Указанный шаблон не найден или не принадлежит вашему аккаунту.
429	USAGE_LIMIT_EXCEEDED	Вы достигли ежемесячного лимита извлечений вашего плана.
500	INTERNAL_ERROR	Произошла непредвиденная ошибка во время обработки извлечения.