Начало работы

Это руководство проведет вас через настройку окружения и выполнение первого запроса на извлечение данных с помощью DocMap API.

Предварительные требования

Перед началом работы убедитесь, что у вас есть:

1. Аккаунт DocMap -- Зарегистрируйтесь на docmap.io, если вы еще этого не сделали.
2. Хотя бы один шаблон извлечения -- Создайте шаблон в Панели управления, определяющий поля, которые вы хотите извлекать из документов.

TIP

Шаблоны определяют структуру данных, которые вы хотите извлечь. Например, шаблон для счетов может включать такие поля, как vendor_name, invoice_number, total_amount и массив line_items. Вы можете создавать и управлять шаблонами через панель управления перед выполнением любых API-вызовов.

Базовый URL

Все API-запросы выполняются по адресу:

https://api.docmap.io

Все эндпоинты имеют префикс /v1/. Например, эндпоинт извлечений:

https://api.docmap.io/v1/extractions/run

Создание API-ключа

1. Перейдите в Панель управления > Настройки > API-ключи.
2. Нажмите Создать API-ключ.
3. Дайте ключу описательное имя (например, "Production Server" или "Local Development").
4. Выберите срок действия.
5. Скопируйте ключ немедленно -- он отображается только один раз и не может быть получен позже.

WARNING

Храните ваш API-ключ в безопасном месте. Он будет показан только один раз при создании. Если вы его потеряете, вам придется создать новый.

Ваш API-ключ будет иметь формат dm_live_... и используется в заголовке Authorization каждого запроса.

Ваш первый запрос

Проверьте настройку, обратившись к эндпоинту проверки состояния API:

curl

curl https://api.docmap.io/health

TypeScript

const res = await fetch('https://api.docmap.io/health')
const data = await res.json()
console.log(data) // { status: "ok" }

Python

import requests
res = requests.get('https://api.docmap.io/health')
print(res.json())  # {"status": "ok"}

Если все работает, вы получите:

{ "status": "ok" }

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

Имея API-ключ и готовый шаблон, вы можете извлечь структурированные данные из PDF. Закодируйте PDF-файл в строку base64 и отправьте его на эндпоинт /v1/extractions/run.

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": "your-template-id",
    "fileName": "invoice.pdf",
    "pdfBase64": "JVBERi0xLjQ...",
    "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: 'your-template-id',
    fileName: 'invoice.pdf',
    pdfBase64: 'JVBERi0xLjQ...', // base64-encoded PDF
    mimeType: 'application/pdf',
  }),
})

const data = await response.json()
console.log(data)

Python

import requests
import base64

api_key = "dm_live_your_api_key"

# Read and encode the PDF
with open("invoice.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": "your-template-id",
        "fileName": "invoice.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

print(response.json())

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

Успешное извлечение возвращает извлеченные данные, соответствующие полям вашего шаблона:

{
  "id": "ext_abc123",
  "templateId": "your-template-id",
  "fileName": "invoice.pdf",
  "status": "completed",
  "data": {
    "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
      }
    ]
  },
  "createdAt": "2024-11-20T14:30:00.000Z"
}

Проверка использования

Отслеживайте использование API, чтобы оставаться в рамках лимитов вашего плана:

curl

curl https://api.docmap.io/v1/usage \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const res = await fetch('https://api.docmap.io/v1/usage', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
})
const usage = await res.json()
console.log(usage)

Python

response = requests.get(
    "https://api.docmap.io/v1/usage",
    headers={"Authorization": f"Bearer {api_key}"},
)
print(response.json())

Дальнейшие шаги

Теперь, когда вы выполнили свое первое извлечение, изучите остальную документацию:

• Аутентификация -- Узнайте об API-ключах и лучших практиках безопасности.
• Справочник API -- Полный справочник по всем доступным эндпоинтам.