Описание API

Обзор

API предоставляет возможности для автоматического распознавания и извлечения данных из документов (паспорта, СНИЛС, водительские права и др.) с использованием машинного обучения.

Базовый URL

https://my.documind.ru/api/v1

Поддерживаемые форматы

Изображения: JPG, JPEG, PNG, BMP, TIFF, WEBP
Документы: PDF (до 20 страниц)

Лимиты

• Максимум 5 файлов за запрос
• До 50 МБ на файл
• До 3 активных задач одновременно

Авторизация

Все запросы к API требуют авторизации через Bearer Token в заголовке Authorization.

Authorization: Bearer <access_token>

Получение токенов

Первичная генерация пары access_token и refresh_token доступна только через веб-интерфейс. После получения токенов используйте endpoint для их обновления.

Управление токенами

POST https://my.documind.ru/api/v1/api-tokens/refresh

Обновляет пару access/refresh токенов для продления сессии.

Запрос

{
  "refresh_token": "your_refresh_token"
}

Ответ

{
  "success": true,
  "message": "Токены обновлены",
  "name": "API Token (Production)",
  "access_token": "your_access_token",
  "access_token_valid_to": "2025-01-15T14:30:00.000000Z",
  "refresh_token": "your_refresh_token",
  "refresh_token_valid_to": "2025-02-15T14:30:00.000000Z"
}

Загрузка документов

POST https://my.documind.ru/api/v1/documents/upload

Загружает и отправляет документы на распознавание. Поддерживает как одиночные файлы, так и множественную загрузку.

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

Параметр	Тип	Описание
file	File	Одиночный файл для обработки
files	File[]	Множественные файлы
document_type	String	Обязательный Тип документа: `passport`, `snils`

Параметр document_type обязателен

Каждый запрос на загрузку должен содержать параметр document_type. Без указания типа документа сервис отклонит запрос с ошибкой 400. Указанный тип применяется ко всем файлам в запросе.

Зачем указывать тип документа?

Для каждого типа документа сервис применяет специализированную конфигурацию распознавания: индивидуальный набор извлекаемых полей и правила валидации. Указание типа документа обеспечивает максимальную точность извлечения данных.

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

{
    "main_task_id": "uuid_main_task_id",
    "message": "Обработка 2 документов начата",
    "subtasks_count": 2,
    "success": true,
    "tasks": [
        {
            "document_type": "passport",
            "filename": "00028.jpg",
            "job_id": "uuid_job_id",
            "status": "pending",
            "task_id": "uuid_task_id"
        },
        {
            "document_type": "passport",
            "filename": "1551114833_Qkr8HprHdtA.jpg",
            "job_id": "uuid_job_id",
            "status": "pending",
            "task_id": "uuid_task_id"
        }
    ]
}

Статусы задач

GET https://my.documind.ru/api/v1/documents/tasks/{task_id}/status

Получает текущий статус задачи (pending, processing, completed, failed).

{
    "success": true,
    "task_id": "uuid_task_id",
    "status": "completed",
    "created_at": "2025-01-15T14:30:00.000000Z",
    "updated_at": "2025-01-15T14:30:05.000000Z"
}

pending

Задача в очереди на обработку

processing

Задача выполняется

completed

Задача успешно завершена

failed

Ошибка при обработке

completed_with_errors

Частично выполнено (для главных задач)

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

GET https://my.documind.ru/api/v1/documents/tasks/{task_id}/result

Получает результаты обработки документа по ID задачи (поддерживает как главные задачи - main_task_id, так и подзадачи - task_id).

{
    "completed_tasks": 1,
    "failed_tasks": 1,
    "main_task_id": "uuid_main_task_id",
    "results": [
        {
            "document_type": "recognized_document_type",
            "error": "ERROR",
            "filename": "uploaded_filename",
            "status": "failed",
            "subtask_id": "uuid_subtask_id"
        },
        {
            "confidence": float(confidence),
            "document_type": "recognized_document_type",
            "filename": "uploaded_filename",
            "processing_time_ms": int(processing_time_ms),
            "result": {
                "birthday": "recognized_birthday",
                "division_code": "recognized_division_code",
                "document_class": "recognized_document_class",
                "document_source": "recognized_document_source",
                "first_name": "recognized_first_name",
                "gender": "recognized_gender",
                "has_errors": bool(true/false),
                "issue_date": "recognized_issue_date",
                "last_name": "recognized_last_name",
                "mrz1": "recognized_mrz1",
                "mrz2": "recognized_mrz2",
                "passport_series_number_page2": "recognized_passport_series_number_page2",
                "passport_series_number_page3": "recognized_passport_series_number_page3",
                "patronymic": "recognized_patronymic",
                "place_of_birth": "recognized_place_of_birth",
                "processing_time": float(processing_time),
                "validation_errors": [
                    "first_validation_error",
                    "second_validation_error",
                    "third_validation_error"
                ],
                "who_issued": "recognized_who_issued"
            },
            "status": "completed",
            "subtask_id": "uuid_subtask_id"
        }
    ],
    "status": "completed_with_errors",
    "success": boolean(true/false),
    "task_type": "main_task",
    "total_tasks": 2
}

Лимиты

Позволяет узнать текущее количество доступных распознаваний по каждому типу документа. Лимиты обновляются ежедневно с 01:00 по 02:00 по московскому времени.

GET https://my.documind.ru/api/v1/documents/limits

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

{
    "success": true,
    "limits": {
        "passport_recognitions": 10,
        "snils_recognitions": 5
    }
}

Ваши текущие лимиты

Рекомендуем проверять лимиты перед пакетной загрузкой, чтобы убедиться в наличии достаточного количества распознаваний. При нехватке лимитов запрос на загрузку вернёт ошибку 402.

Коды ошибок

Код	Описание
400	Неверные параметры запроса
401	Не авторизован или недействительный токен
402	Недостаточно лимитов
403	Доступ запрещён
404	Ресурс не найден
413	Файл превышает максимальный размер (50 МБ)
415	Неподдерживаемый формат файла
429	Превышен лимит запросов или активных задач
500	Внутренняя ошибка сервера

Недостаточно лимитов

{
    "error": "There are not enough limits. Requested: N, available: 0",
    "error_code": "INSUFFICIENT_LIMITS",
    "success": false
}

Превышен лимит активных задач

{
  "success": false,
  "error": "Too many active tasks: 3/3",
  "error_code": "TOO_MANY_ACTIVE_TASKS",
  "retry_after": 30
}

Превышен лимит частоты запросов (Rate limit)

Возникает при слишком частых обращениях к API. Поле retry_after указывает количество секунд, через которое можно повторить запрос.

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Maximum 60 requests per 1 minutes",
  "retry_after": 45
}

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

Базовый сценарий обработки

1. Загрузка документа

curl -X POST "https://my.documind.ru/api/v1/documents/upload" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@passport.jpg" \
  -F "document_type=passport"

2. Проверка статуса

curl "https://my.documind.ru/api/v1/documents/tasks/YOUR_TASK_ID/status" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

3. Получение результата

curl "https://my.documind.ru/api/v1/documents/tasks/YOUR_TASK_ID/result" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Пакетная загрузка (batch)

API поддерживает пакетную обработку — вы можете отправить до 5 файлов в одном запросе. Все файлы будут обработаны параллельно, каждый получит свой task_id, а весь пакет объединяется под общим main_task_id.

Используйте параметр files (множественное число) для пакетной отправки. Результаты можно получить как по отдельным подзадачам, так и по main_task_id — в этом случае вернутся результаты всех файлов сразу.

curl -X POST "https://my.documind.ru/api/v1/documents/upload" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "files=@passport_main.jpg" \
  -F "files=@passport_registration.jpg" \
  -F "files=@snils.png" \
  -F "document_type=passport"