API Документов

API для загрузки и обработки документов.

Создание запроса на обработку

Загрузите один или несколько PDF файлов для OCR обработки.

Endpoint

POST /documents/api/v1/request/

Аутентификация

Не требуется (публичный endpoint)

Параметры

Параметр	Тип	Описание
files_list	File[]	Список PDF файлов

Пример запроса

curl -X POST http://localhost:8000/documents/api/v1/request/ \
  -F "files_list=@invoice1.pdf" \
  -F "files_list=@invoice2.pdf"

Успешный ответ (202 Accepted)

{
  "request_id": "ceaf3ee3-3bdd-43dc-8c61-d4e14c498bb0"
}

Ошибки

400 Bad Request - файлы не переданы:

{
  "error": "Error: файлы не были добавлены! 'files_list': None"
}

---

Получение статуса и результатов

Получите информацию о запросе и результаты обработки.

Endpoint

GET /documents/api/v1/request/{request_id}/

Аутентификация

Не требуется (публичный endpoint)

Параметры пути

Параметр	Тип	Описание
request_id	UUID	ID запроса

Пример запроса

curl http://localhost:8000/documents/api/v1/request/ceaf3ee3-3bdd-43dc-8c61-d4e14c498bb0/

Успешный ответ (200 OK)

{
  "id": "ceaf3ee3-3bdd-43dc-8c61-d4e14c498bb0",
  "user": null,
  "status": "COMPLETED",
  "created_at": "2025-11-21T13:18:30.667414Z",
  "tasks": [
    {
      "id": "aff7fe90-2279-4a86-b5a3-07001b67c7e0",
      "document_name": "invoice.pdf",
      "document_type": {
        "id": "4a144393-1554-4716-ae47-e045e84dda96",
        "name": "Invoice",
        "code": "1404"
      },
      "status": "COMPLETED",
      "file_url": "/media/documents/1404/10e48dcb-5dbf-414f-83e1-752afd0dee2b_invoice.pdf",
      "ocr_result": {
        "raw_text": "Invoice #12345\nDate: 2024-01-15\nAmount: $1,500.00",
        "items": [
          {
            "invoice_number": "12345",
            "date": "2024-01-15",
            "amount": 1500.00
          }
        ]
      }
    }
  ]
}

Структура items

Поле items содержит массив объектов, где каждый объект представляет одну строку данных (например, строку в таблице счёта). Поля группируются по индексу (index) и возвращаются как key-value пары.

Ошибки

404 Not Found - запрос не найден:

{
  "error": "Запрос не найден."
}

---

Отмена запроса

Отмена запроса на обработку и всех связанных задач.

Endpoint

POST /documents/api/v1/request/cancel/{pk}/

Аутентификация

Не требуется (публичный endpoint)

Параметры пути

Параметр	Тип	Описание
pk	UUID	ID запроса

Пример запроса

curl -X POST http://localhost:8000/documents/api/v1/request/cancel/ceaf3ee3-3bdd-43dc-8c61-d4e14c498bb0/

Успешный ответ (200 OK)

{
  "status": "Запрос отменен"
}

Ошибки

400 Bad Request - невозможно отменить:

{
  "error": "Невозможно отменить (уже завершен или не найден)"
}

примечание

Запрос можно отменить только если он находится в статусах PENDING или PROCESSING. Уже завершённые (COMPLETED, FAILED, CANCELLED) запросы отменить нельзя.

---

Статусы

Статусы запроса (Request)

Статус	Описание
PENDING	В очереди
PROCESSING	В обработке
COMPLETED	Завершено успешно
PARTIAL_FAILURE	Часть документов не обработана
PARTIAL_SUCCESS	Частично успешно
CANCELLED	Отменено
FAILED	Ошибка

Статусы задачи (Task)

Статус	Описание
PREPROCESS	В проверке
PENDING	В очереди
PROCESSING_OCR	Распознавание текста
PROCESSING_CLASSIFY	Классификация
PROCESSING_EXTRACT	Анализ полей
SAVING	Сохранение
COMPLETED	Готово
FAILED	Ошибка
CANCELLED	Отменено

---

Типы документов

Система автоматически классифицирует документы. Поддерживаемые типы настраиваются в админ-панели.

Стандартные типы

Тип	Код	Описание
Invoice	1404	Счёт-фактура
Contract	2001	Договор

Поля документов

Каждый тип имеет свой набор извлекаемых полей:

Invoice:

• invoice_number - номер счёта
• date - дата
• amount - сумма
• vendor_name - поставщик

---

Примеры интеграции

Python

import requests
import time

# Загрузка документа
with open("invoice.pdf", "rb") as f:
    response = requests.post(
        "http://localhost:8000/documents/api/v1/request/",
        files={"files_list": f}
    )
request_id = response.json()["request_id"]

# Ожидание результата
while True:
    response = requests.get(
        f"http://localhost:8000/documents/api/v1/request/{request_id}/"
    )
    data = response.json()

    if data["status"] == "COMPLETED":
        for task in data["tasks"]:
            print(f"Document: {task['document_name']}")
            print(f"Type: {task['document_type']['name']}")
            for item in task["ocr_result"]["items"]:
                for key, value in item.items():
                    print(f"  {key}: {value}")
        break

    time.sleep(2)

JavaScript

async function processDocument(file) {
  const formData = new FormData();
  formData.append("files_list", file);

  // Загрузка
  const uploadResponse = await fetch(
    "http://localhost:8000/documents/api/v1/request/",
    { method: "POST", body: formData }
  );
  const { request_id } = await uploadResponse.json();

  // Polling
  while (true) {
    const statusResponse = await fetch(
      `http://localhost:8000/documents/api/v1/request/${request_id}/`
    );
    const data = await statusResponse.json();

    if (data.status === "COMPLETED") {
      return data.tasks;
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}