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

Обзор

Эндпоинт извлечения принимает документ (в кодировке base64), обрабатывает его через определенный вами шаблон и возвращает структурированные данные, соответствующие переменным шаблона. Один вызов API обрабатывает весь конвейер -- загрузку, обработку ИИ и структурированный вывод.

Все запросы на извлечение направляются через POST /v1/extractions/run.

Подготовка документа

Перед отправкой документа в API необходимо закодировать содержимое файла в base64.

Ограничения:

• Максимальный размер тела запроса: 15 МБ
• Поддерживаемые MIME-типы:
  • application/pdf (PDF)
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document (DOCX)

Bash

# Base64-encode a PDF file
base64 -i invoice.pdf -o invoice_b64.txt

# Or inline (macOS / Linux)
PDF_BASE64=$(base64 -w 0 invoice.pdf)

TypeScript

import { readFileSync } from "fs";

const pdfBuffer = readFileSync("invoice.pdf");
const pdfBase64 = pdfBuffer.toString("base64");

Python

import base64

with open("invoice.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

WARNING

Кодирование в base64 увеличивает размер файла примерно на 33%. PDF размером 10 МБ становится примерно 13,3 МБ после кодирования, поэтому исходные файлы должны быть менее ~11 МБ, чтобы уложиться в лимит запроса 15 МБ.

Выполнение запроса

Отправьте POST-запрос на /v1/extractions/run со следующим JSON-телом:

Поле	Тип	Обязательно	Описание
templateId	string	Да	ID шаблона для извлечения
fileName	string	Да	Исходное имя файла (например, "invoice.pdf")
pdfBase64	string	Да	Содержимое файла в кодировке base64
mimeType	string	Да	MIME-тип файла
runId	string	Нет	Необязательный идентификатор для группировки нескольких извлечений в пакет

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": "tmpl_abc123",
    "fileName": "invoice.pdf",
    "pdfBase64": "JVBERi0xLjQKJeLj...",
    "mimeType": "application/pdf"
  }'

TypeScript

const response = await fetch("https://api.docmap.io/v1/extractions/run", {
  method: "POST",
  headers: {
    Authorization: "Bearer dm_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    templateId: "tmpl_abc123",
    fileName: "invoice.pdf",
    pdfBase64: pdfBase64,
    mimeType: "application/pdf",
  }),
});

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

Python

import requests

response = requests.post(
    "https://api.docmap.io/v1/extractions/run",
    headers={
        "Authorization": "Bearer dm_live_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "templateId": "tmpl_abc123",
        "fileName": "invoice.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

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

Понимание ответа

Успешное извлечение возвращает ответ, обернутый в объект data:

{
  "data": {
    "id": "ext_abc123def456",
    "userId": "user_789",
    "templateId": "tmpl_abc123",
    "templateName": "Invoice Parser",
    "fileName": "invoice.pdf",
    "status": "completed",
    "extractedData": {
      "vendor_name": "Acme Corp",
      "invoice_number": "INV-2024-001",
      "total_amount": 1250.00,
      "line_items": [
        { "description": "Widget A", "quantity": 10, "unit_price": 125.00 }
      ]
    },
    "error": null,
    "variables": [
      { "name": "vendor_name", "type": "string", "description": "Company name of the vendor" },
      { "name": "invoice_number", "type": "string", "description": "Invoice reference number" },
      { "name": "total_amount", "type": "number", "description": "Total invoice amount" },
      { "name": "line_items", "type": "array", "description": "List of line items" }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": 3420,
    "createdAt": "2025-07-15T10:30:00.000Z"
  }
}

Поле	Описание
id	Уникальный ID извлечения (с префиксом ext_)
status	"processing" во время выполнения (асинхронный режим), "completed", если данные успешно извлечены, "failed", если при обработке произошла ошибка
extractedData	Объект, ключи которого соответствуют именам переменных вашего шаблона. null, если извлечение не удалось
error	Строка с сообщением об ошибке, если извлечение не удалось. null при успехе
processingTimeMs	Время обработки документа ИИ в миллисекундах
source	"api" при запуске через API-ключ, "dashboard" при запуске через веб-интерфейс
variables	Определения переменных шаблона, использованные для этого извлечения
runId	Идентификатор пакета, если он был указан, или null
templateName	Читаемое имя использованного шаблона
createdAt	Временная метка ISO 8601 создания извлечения

TIP

Всегда проверяйте поле status перед обращением к extractedData. Если status равен "failed", поле error содержит описание того, что пошло не так.

Пакетные извлечения

Для обработки нескольких файлов как логического пакета передавайте одинаковый runId в каждый запрос на извлечение. Это не меняет способ обработки документов -- каждый файл по-прежнему извлекается независимо -- но позволяет запрашивать все результаты пакета вместе.

const runId = "batch-invoices-2025-07";
const files = ["invoice-001.pdf", "invoice-002.pdf", "invoice-003.pdf"];

// Process each file with the same runId
const results = await Promise.all(
  files.map(async (fileName) => {
    const pdfBase64 = readFileSync(fileName).toString("base64");

    const response = await fetch("https://api.docmap.io/v1/extractions/run", {
      method: "POST",
      headers: {
        Authorization: "Bearer dm_live_your_api_key",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        templateId: "tmpl_abc123",
        fileName,
        pdfBase64,
        mimeType: "application/pdf",
        runId,
      }),
    });

    return response.json();
  })
);

Затем получите все извлечения из пакета:

curl

curl "https://api.docmap.io/v1/extractions?runId=batch-invoices-2025-07" \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const response = await fetch(
  "https://api.docmap.io/v1/extractions?runId=batch-invoices-2025-07",
  {
    headers: { Authorization: "Bearer dm_live_your_api_key" },
  }
);

const { data } = await response.json();
console.log(`Batch contains ${data.length} extractions`);

Python

response = requests.get(
    "https://api.docmap.io/v1/extractions",
    params={"runId": "batch-invoices-2025-07"},
    headers={"Authorization": "Bearer dm_live_your_api_key"},
)

data = response.json()["data"]
print(f"Batch contains {len(data)} extractions")

TIP

Эндпоинт списка также поддерживает фильтрацию по templateId и параметр limit (1--100, по умолчанию 50). Фильтры можно комбинировать: ?runId=batch-001&templateId=tmpl_abc123&limit=100.

Асинхронный рабочий процесс

По умолчанию запросы на извлечение являются синхронными -- API блокируется до завершения обработки. Для длительных извлечений или когда вы хотите избежать тайм-аутов HTTP, используйте асинхронный режим, добавив ?async=true к URL. API немедленно возвращает ответ со статусом "processing", а вы опрашиваете отдельный эндпоинт до готовности результата.

Паттерн отправки + опроса

TypeScript

import { readFileSync } from "fs";

const API_BASE = "https://api.docmap.io";
const API_KEY = process.env.DOCMAP_API_KEY!;

// 1. Submit the extraction asynchronously
const submitResponse = await fetch(`${API_BASE}/v1/extractions/run?async=true`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    templateId: "tmpl_abc123",
    fileName: "invoice.pdf",
    pdfBase64: readFileSync("invoice.pdf").toString("base64"),
    mimeType: "application/pdf",
  }),
});

const { data: submitted } = await submitResponse.json();
console.log(`Extraction ${submitted.id} submitted, status: ${submitted.status}`);

// 2. Poll until complete
async function poll(extractionId: string): Promise<any> {
  for (let i = 0; i < 30; i++) {
    const res = await fetch(`${API_BASE}/v1/extractions/${extractionId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    const { data } = await res.json();
    if (data.status !== "processing") return data;
    await new Promise((r) => setTimeout(r, 2000));
  }
  throw new Error("Extraction timed out");
}

const result = await poll(submitted.id);
console.log(`Final status: ${result.status}`);
console.log("Extracted data:", result.extractedData);

Python

import base64
import time
import requests

API_BASE = "https://api.docmap.io"
API_KEY = "dm_live_your_api_key"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1. Submit the extraction asynchronously
with open("invoice.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

submit_response = requests.post(
    f"{API_BASE}/v1/extractions/run?async=true",
    headers=headers,
    json={
        "templateId": "tmpl_abc123",
        "fileName": "invoice.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

submitted = submit_response.json()["data"]
print(f"Extraction {submitted['id']} submitted, status: {submitted['status']}")

# 2. Poll until complete
def poll(extraction_id: str):
    for _ in range(30):
        res = requests.get(
            f"{API_BASE}/v1/extractions/{extraction_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        data = res.json()["data"]
        if data["status"] != "processing":
            return data
        time.sleep(2)
    raise TimeoutError("Extraction timed out")

result = poll(submitted["id"])
print(f"Final status: {result['status']}")
print("Extracted data:", result["extractedData"])

Когда использовать асинхронный режим

Используйте асинхронный режим при обработке больших документов, когда ваш HTTP-клиент имеет короткие тайм-ауты, или когда вы хотите отправить несколько извлечений и собрать результаты позже. Для большинства извлечений одного документа синхронный режим проще.

Полный пример рабочего процесса

Вот полный сквозной пример на TypeScript, который читает PDF с диска, запускает извлечение и обрабатывает как успешный, так и неуспешный результат:

import { readFileSync } from "fs";

const API_BASE = "https://api.docmap.io";
const API_KEY = process.env.DOCMAP_API_KEY!;

async function extractInvoice(filePath: string) {
  // 1. Read and encode the PDF
  const pdfBuffer = readFileSync(filePath);
  const pdfBase64 = pdfBuffer.toString("base64");
  const fileName = filePath.split("/").pop()!;

  console.log(`Processing ${fileName} (${(pdfBuffer.length / 1024).toFixed(0)} KB)...`);

  // 2. Run the extraction
  const response = await fetch(`${API_BASE}/v1/extractions/run`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      templateId: "tmpl_invoice_parser",
      fileName,
      pdfBase64,
      mimeType: "application/pdf",
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API error ${response.status}: ${error.error.message}`);
  }

  const { data } = await response.json();

  // 3. Check the extraction result
  if (data.status === "failed") {
    console.error(`Extraction failed: ${data.error}`);
    return null;
  }

  console.log(`Extraction completed in ${data.processingTimeMs}ms`);
  console.log("Extracted data:", JSON.stringify(data.extractedData, null, 2));

  return data.extractedData;
}

// Run it
extractInvoice("./invoices/invoice-001.pdf")
  .then((result) => {
    if (result) {
      console.log(`Vendor: ${result.vendor_name}`);
      console.log(`Total: $${result.total_amount}`);
    }
  })
  .catch(console.error);