Руководство по интеграции

1. Общие сведения

2. Быстрый старт

Типовой сценарий работы с API включает следующие шаги:

1. Создание пакета — получить идентификатор пакета для группы файлов.
2. Добавление файлов в пакет.
3. Запуск распознавания по пакету.
4. Получение пакета (состояние и результат) — опрос состояния пакета и получение распознанных данных (структура ответа — раздел 5.4, коды ошибок — раздел 8).

3. Аутентификация и заголовки

Все запросы к API должны содержать заголовок авторизации:

Authorization: Bearer <токен>

Где <токен> — выданный клиенту токен доступа. Для получения токена необходимо сформировать в личном кабинете API ключ и обменять его на токен.

Request:

POST https://api.doculus.pro/facades/correct/api/auth
Content-Type: application/json
Body:
{
  "apiKey": "API ключ"
}

Response:

{
  "bearer": "your_token"
}

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

Дополнительно:

• при отправке JSON — Content-Type: application/json;
• при загрузке файлов — Content-Type: multipart/form-data.

4. Группы методов

API делится на три группы:

• Packages — работа с пакетами (создание, запуск, получение).
• Images — загрузка и получение изображений (старая версия, поддержка обратной совместимости).
• Files — загрузка файлов в пакет (предпочтительное использование вместо Images).

5. Пакеты (Packages)

5.1. Создание пакета

Создаёт новый пакет для последующей загрузки изображений и файлов.

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

POST https://api.doculus.pro/facades/correct/api/Packages
Authorization: Bearer <токен>
Content-Type: application/json

Обязательный заголовок авторизации. Идентификатор созданного пакета далее используется в методах Images, Files при запуске распознавания и при получении результата распознавания.

5.2. Запуск распознавания

Запускает обработку файлов в уже созданном пакете.

Пример URL:

POST https://api.doculus.pro/facades/correct/api/Packages/13/start

После успешного вызова необходимо периодически опрашивать состояние пакета (см. п. 5.3) до перехода в финальное состояние (state: "Recognized"), затем получать результат распознавания (структура ответа — п. 5.4).

5.3. Получение пакета (состояние и результат)

Возвращает текущее состояние пакета и данные распознавания.

Пример URL:

GET https://api.doculus.pro/facades/correct/api/Packages/13

Необходимо использовать этот метод для опроса состояния пакета после вызова «Запуск распознавания». Структура ответа при 200 OK описана в разделе 5.4.

5.4. Структура ответа GET пакета (результат распознавания)

Тело ответа метода GET .../Packages/{packageId} в формате JSON имеет следующую структуру.

Уровень пакета (корень объекта):

Объект документа (элемент documents):

Объект поля (элемент fields):

Объект ошибки валидации (элемент validationErrors):

Пример фрагмента ответа (пакет и один документ с частью полей):

{
  "id": 5000465,
  "state": "Recognized",
  "createdAt": "2026-02-26T09:07:02.681319+00:00",
  "documents": [
    {
      "id": "1f2c5cf9-3fdf-4ca8-b4de-f500c52bf912",
      "docType": "УПД",
      "pages": [{"id": 10002090}],
      "fields": [
        {"fieldKey": "DocNum", "fieldValue": "6", "confidence": 0.75, "tableRow": null, "tableIndex": null, "documentPageIndex": 0},
        {"fieldKey": "DocDate", "fieldValue": "27.04.2024", "confidence": 0.75, "documentPageIndex": 0},
        {"fieldKey": "ContractorName", "fieldValue": "ООО \"ДОКУЛУС\"", "confidence": 0.75, "documentPageIndex": 0}
      ],
      "codes": [],
      "signatures": []
    }
  ],
  "unrecognizedFiles": [],
  "unrecognizedPages": [],
  "validationErrors": [
    {
      "errorCode": 100,
      "errorText": "Страница не распознана из-за низкого качества печати",
      "imageId": 10002091
    },
    {
      "errorCode": 200,
      "errorText": "На документе отсутствует ИНН поставщика",
      "documentId": "1f2c5cf9-3fdf-4ca8-b4de-f500c52bf912",
      "imageId": 10002090
    },
    {
      "errorCode": 201,
      "errorText": "Дата документа больше сегодняшнего дня",
      "documentId": "1f2c5cf9-3fdf-4ca8-b4de-f500c52bf912",
      "imageId": 10002090
    }
  ]
}

Полный пример ответа с табличными строками и координатами полей приведён в файле пример ответа пакета. Идентификаторы из documents[].pages[].id используются для запроса изображения страницы: GET .../Images/{id}.

6. Изображения (Images)

6.1. Добавление изображений в пакет

Загружает изображения (или страницы PDF) в существующий пакет. Порядок загрузки должен соответствовать порядку страниц в документе.

Устарело. Оставлено для обратной совместимости и будет удалено в будущих версиях API. Используйте Файлы (Files)

Пример URL:

POST https://api.doculus.pro/facades/correct/api/Images/package/13

Типичные варианты тела запроса:

• multipart/form-data
• application/json — поле с содержимым в Base64.

Форматы: JPG, PNG, PDF, DOC, DOCX, RTF. Не рекомендуется загружать более 50 страниц в пакет.

6.2. Получение изображения

Возвращает данные изображения по идентификатору.

Пример URL:

GET https://api.doculus.pro/facades/correct/api/Images/13

Идентификаторы изображений приходят в ответе на добавление изображений и в составе результата распознавания пакета — в массиве documents[].pages (поле id), см. п. 5.4.

7. Файлы (Files)

7.1. Добавление файлов в пакет

Добавляет в пакет файлы: изображения (JPG, PNG, PDF, DOC, DOCX, RTF).

Пример URL:

POST https://api.doculus.pro/facades/correct/api/Files/package/13

Формат тела запроса — multipart/form-data или JSON с Base64; в ответе при успехе возвращаются идентификаторы добавленных файлов и изображений.

8. Коды ошибок

При интеграции необходимо обрабатывать и ошибочные ответы. Типичные коды HTTP и рекомендуемые действия: