Описание 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": "passport",
            "error": "No passport document detected",
            "filename": "photo_without_document.jpg",
            "status": "failed",
            "subtask_id": "uuid_subtask_id"
        },
        {
            "confidence": null,
            "document_type": "passport",
            "filename": "passport.jpg",
            "processing_time_ms": 1870,
            "result": {
                "processing_time": 1.17,
                "documents": {
                    "passport_page2": {
                        "passport_series_number_page2": "92 16 147936",
                        "date_of_issue": "15.06.2010",
                        "division_code": "770-012",
                        "issuing_authority": "ОТДЕЛЕНИЕМ УФМС РОССИИ ПО Г. МОСКВА"
                    },
                    "passport_page3": {
                        "last_name": "ИВАНОВ",
                        "first_name": "ИВАН",
                        "patronymic": "ИВАНОВИЧ",
                        "date_of_birth": "14.03.1980",
                        "place_of_birth": "Г. МОСКВА",
                        "gender": "МУЖ.",
                        "passport_series_number_page3": "92 16 147936",
                        "mrz1": "PNRUSIVANOV<<IVAN<IVANOVI3<<<<<<<<<<<<<<<<<<<<",
                        "mrz2": "9216147936RUS8003144M<<<<<<<<161231160012<82"
                    }
                },
                "document_class": "passport",
                "document_source": "photo",
                "validation_errors": [],
                "has_errors": false
            },
            "status": "completed",
            "subtask_id": "uuid_subtask_id"
        }
    ],
    "status": "completed_with_errors",
    "success": true,
    "task_type": "main_task",
    "total_tasks": 2
}

Структура поля `result`

documents — словарь распознанных документов: ключ — тип (passport_page2, passport_page3, passport_page5…passport_page12, passport_page19, snils), значение — извлечённые поля. Даже единственный документ вложен в documents.
Поле, которое не удалось обнаружить или прочитать, возвращается со значением null.
document_class — класс документа: passport, snils.
document_source — источник снимка: photo, scan, photo_of_scan, photo_of_screen, selphi.
validation_errors — массив строк с ошибками валидации; has_errors — их наличие.

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

Паспорт РФ — страница 2 (`passport_page2`)

passport_series_number_page2 — серия и номер (XX XX XXXXXX)
date_of_issue — дата выдачи (DD.MM.YYYY)
division_code — код подразделения (XXX-XXX)
issuing_authority — кем выдан

Паспорт РФ — страница 3 (`passport_page3`)

last_name, first_name, patronymic — ФИО
date_of_birth — дата рождения (DD.MM.YYYY)
place_of_birth — место рождения
gender — пол (МУЖ./ЖЕН.)
passport_series_number_page3 — серия и номер
mrz1, mrz2 — машиночитаемая зона

Паспорт РФ — регистрация, стр. 5–12 (`passport_page5`…`passport_page12`)

registrations — массив записей о регистрации, каждая содержит:

page, index — страница и позиция блока
block_type — printed или handwritten (рукописные не распознаются, поле message)
registration_status — ЗАРЕГИСТРИРОВАН / СНЯТ С РЕГИСТРАЦИОННОГО УЧЕТА
date_of_registration — дата регистрации
Адрес: region, district, locality, street, house, building, apartment
department, division_code, division_name — орган регистрации

Паспорт РФ — ранее выданные паспорта, стр. 19 (`passport_page19`)

stamps — массив блоков, каждый содержит:

block_index — позиция блока на странице
format — stamp (одиночный штамп) или table (табличная форма)
records — записи: serial, number, date, issuer, division_code

СНИЛС (`snils`)

number — номер СНИЛС (XXX-XXX-XXX XX)
last_name, first_name, patronymic — ФИО
date_of_birth, place_of_birth, gender — данные владельца
date_of_registration — дата регистрации в ПФР

Многостраничный PDF

Если в задаче обрабатывался многостраничный PDF, поле result содержит постраничные результаты в массиве pages. Нумерация page_number начинается с 0. Страница, на которой документ выбранного типа не найден, возвращается со статусом failed и полем error — лимиты за такие страницы не списываются.

{
    "is_multi_document": true,
    "total_pages": 3,
    "processing_time": 3.47,
    "pages": [
        {
            "page_number": 0,
            "status": "completed",
            "processing_time": 1.27,
            "documents": {
                "passport_page2": { "...": "..." },
                "passport_page3": { "...": "..." }
            },
            "document_class": "passport",
            "document_source": "scan",
            "validation_errors": [],
            "has_errors": false
        },
        {
            "page_number": 1,
            "status": "completed",
            "processing_time": 1.14,
            "documents": {
                "passport_page5": {
                    "registrations": [
                        {
                            "page": 5,
                            "index": 0,
                            "block_type": "printed",
                            "registration_status": "ЗАРЕГИСТРИРОВАН",
                            "date_of_registration": "15.06.2020",
                            "region": "Г. МОСКВА",
                            "district": null,
                            "locality": "Г. МОСКВА",
                            "street": "УЛ. ПОКРОВКА",
                            "house": "15",
                            "building": "1",
                            "apartment": "52",
                            "department": "ОТДЕЛЕНИЕМ УФМС РОССИИ ПО Г. МОСКВА",
                            "division_code": "770-012",
                            "division_name": "ГУ МВД РОССИИ ПО Г. МОСКВЕ"
                        }
                    ]
                }
            },
            "document_class": "passport",
            "document_source": "scan",
            "validation_errors": [],
            "has_errors": false
        },
        {
            "page_number": 2,
            "status": "failed",
            "error": "Страница 3: документ не распознан"
        }
    ]
}

Лимиты

Позволяет узнать текущее количество доступных распознаваний по каждому типу документа. Лимиты обновляются ежедневно с 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"

Описание API

Обзор

Базовый URL

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

Лимиты

Авторизация

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

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

Запрос

Ответ

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

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

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

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

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

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

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

Структура поля result

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

Паспорт РФ — страница 2 (passport_page2)

Паспорт РФ — страница 3 (passport_page3)

Паспорт РФ — регистрация, стр. 5–12 (passport_page5…passport_page12)

Паспорт РФ — ранее выданные паспорта, стр. 19 (passport_page19)

СНИЛС (snils)

Многостраничный PDF

Лимиты

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

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

Коды ошибок

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

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

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

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

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

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

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

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

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

Структура поля `result`

Паспорт РФ — страница 2 (`passport_page2`)

Паспорт РФ — страница 3 (`passport_page3`)

Паспорт РФ — регистрация, стр. 5–12 (`passport_page5`…`passport_page12`)

Паспорт РФ — ранее выданные паспорта, стр. 19 (`passport_page19`)

СНИЛС (`snils`)