Skip to Content
Primo RPA AI ServerРазработчикамПошаговое руководство по APIПакетная обработка

Пакетная обработка

Описание

Пакетная обработка позволяет отправить набор документов (пакет) для последовательной обработки конвейером: классификации, распознавания, извлечения данных, постобработки и валидации. В отличие от одиночных запросов к Умному OCR или NLP, пакетная обработка управляется единым конвейером и возвращает структурированные результаты по каждому документу.

Взаимодействие с API пакетной обработки выполняется по следующей схеме:

  1. Создание пакета — получение идентификатора.
  2. Настройка конвейера — загрузка JSON-конфигурации обработки.
  3. Загрузка файлов — отправка документов в пакет.
  4. Запуск обработки — старт конвейера.
  5. Ожидание завершения — опрос списка готовых пакетов.
  6. Получение результатов — чтение данных обработки.

Расширенные операции

Конвейер обработки

Конвейер — это JSON-конфигурация, описывающая последовательность шагов обработки. Подробное руководство по созданию конвейера см. в статье Конвейер пакетной обработки.

Авторизация

Каждый запрос в данном разделе требует указания заголовка Authorization. Подробнее см. в разделе Авторизация.

Создать пакет

Пакет создаётся методом:

POST /api/packages

Тип содержимого: application/json

POST /api/packages HTTP/1.1
Host: ai-server-endpoint:44392
Accept: application/json
Authorization: ••••••
Content-Type: application/json

Опциональный query-параметр requestGroup позволяет указать группу приоритизации для обработки пакета в отдельной очереди.

POST /api/packages?requestGroup=priority-1 HTTP/1.1

При успешном создании сервер возвращает статус 201 Created с информацией о пакете:

{
    "key": "e1f19acc-f9a2-435c-9c9b-38c4a09a7468",
    "createdAt": "2026-06-11T10:00:00.000+03:00",
    "expiresAt": "2026-06-11T11:00:00.000+03:00",
    "processing": {
        "isStarted": false,
        "isReady": false,
        "isCancelled": false,
        "documents": [],
        "errors": []
    },
    "files": [],
    "stepsInWork": []
}

Настроить конвейер

Конвейер загружается отдельным запросом:

POST /api/packages/{requestKey}/pipeline

В теле запроса передаётся JSON-объект конвейера. Подробное описание структуры см. в статье Конвейер пакетной обработки.

POST /api/packages/e1f19acc-f9a2-435c-9c9b-38c4a09a7468/pipeline HTTP/1.1
Host: ai-server-endpoint:44392
Accept: application/json
Authorization: ••••••
Content-Type: application/json

{
    "documentDefinitions": [
        { "title": "Invoice", "titleClasses": ["Invoice"], "isPdfGenerated": true }
    ],
    "steps": [
        {
            "id": "classify",
            "routingKey": "ocr-clas-a1b2",
            "meta": { "component": "SmartOCR", "smartOcrType": "Classification" },
            "classify": { "fallback": "Unknown" },
            "nextSteps": [
                {
                    "id": "recognize-invoice",
                    "routingKey": "ocr-rec-struct-c3d4",
                    "meta": { "component": "SmartOCR", "smartOcrType": "Recognition" },
                    "classCondition": "Invoice",
                    "recognition": {}
                }
            ]
        }
    ]
}

При успешном сохранении сервер возвращает 204 No Content.

⚠️

Конвейер нельзя изменить после запуска обработки. Если пакет уже запущен, сервер вернёт ошибку 400 Bad Request.

ℹ️

Сервер валидирует конвейер при сохранении. Если JSON не проходит валидацию (отсутствуют обязательные поля, некорректные значения), сервер вернёт 400 Bad Request с описанием ошибок.

Загрузить файлы

Файлы загружаются методом:

POST /api/packages/{requestKey}/files

Тип содержимого: multipart/form-data

POST /api/packages/e1f19acc-f9a2-435c-9c9b-38c4a09a7468/files HTTP/1.1
Host: ai-server-endpoint:44392
Accept: application/json
Authorization: ••••••
Content-Type: multipart/form-data; boundary=----Boundary

------Boundary
Content-Disposition: form-data; name="file1"; filename="invoice-01.png"
Content-Type: image/png

(data)
------Boundary
Content-Disposition: form-data; name="file2"; filename="invoice-02.pdf"
Content-Type: application/pdf

(data)
------Boundary--

Поддерживаемые форматы: jpg, jpeg, png, pdf, tiff, bmp.

При успешной загрузке сервер возвращает массив идентификаторов файлов:

[
    "d353c73d-c1f9-4dc5-bdd1-9a73565e566c",
    "a7b8c9d0-e1f2-4a3b-8c5d-6e7f8a9b0c1d"
]
ℹ️

В пакет можно загрузить несколько файлов. При отправке PDF или многостраничного TIFF каждая страница обрабатывается отдельно. Файлы можно загружать несколькими запросами — каждый вызов добавляет файлы к пакету.

⚠️

Файлы нельзя добавлять после запуска обработки.

Запустить обработку

Обработка запускается методом:

POST /api/packages/{requestKey}/start

POST /api/packages/e1f19acc-f9a2-435c-9c9b-38c4a09a7468/start HTTP/1.1
Host: ai-server-endpoint:44392
Accept: application/json
Authorization: ••••••
Content-Type: application/json

При успешном запуске сервер возвращает 204 No Content.

Перед запуском сервер проверяет:

  • Пакет ещё не запущен
  • В пакете есть хотя бы один файл
  • Конвейер валиден

Если условия не выполнены, сервер вернёт 400 Bad Request.

Проверка готовых пакетов

Для проверки завершённых пакетов используется метод:

GET /api/packages/ready

GET /api/packages/ready HTTP/1.1
Host: ai-server-endpoint:44392
Accept: application/json
Authorization: ••••••

Сервер возвращает массив идентификаторов готовых пакетов:

["e1f19acc-f9a2-435c-9c9b-38c4a09a7468"]
ℹ️

Пакет появляется в этом списке, когда обработка всех его страниц завершена (processing.isReady = true).

Получить пакет

Результаты обработки можно получить методом:

GET /api/packages/{requestKey}

GET /api/packages/e1f19acc-f9a2-435c-9c9b-38c4a09a7468 HTTP/1.1
Host: ai-server-endpoint:44392
Accept: application/json
Authorization: ••••••

Сервер возвращает полную информацию о пакете:

{
    "key": "e1f19acc-f9a2-435c-9c9b-38c4a09a7468",
    "createdAt": "2026-06-11T10:00:00.000+03:00",
    "expiresAt": "2026-06-11T11:00:00.000+03:00",
    "processing": {
        "startedAt": "2026-06-11T10:00:05.000+03:00",
        "isStarted": true,
        "readyAt": "2026-06-11T10:00:45.000+03:00",
        "isReady": true,
        "isCancelled": false,
        "documents": [
            {
                "id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
                "title": "Invoice",
                "classConfidence": 0.95,
                "pages": [
                    {
                        "class": "Invoice",
                        "classConfidence": 0.95,
                        "indexInPackage": 0,
                        "file": {
                            "id": "d353c73d-c1f9-4dc5-bdd1-9a73565e566c",
                            "originalFileName": "invoice-01.png",
                            "extension": ".png",
                            "contentType": "image/png",
                            "contentLength": 114159,
                            "type": "Image",
                            "sourceFileType": "png",
                            "fileType": "png"
                        },
                        "rawResult": {
                            "items": [
                                {
                                    "field": "INN",
                                    "confidence": 0.92,
                                    "text": "7707083893",
                                    "isValid": true,
                                    "coordinates": {
                                        "minX": 100,
                                        "minY": 200,
                                        "maxX": 300,
                                        "maxY": 230
                                    }
                                },
                                {
                                    "field": "TotalAmount",
                                    "confidence": 0.88,
                                    "text": "150000.00",
                                    "isValid": true
                                }
                            ],
                            "unifiedText": "ИНН 7707083893\n\nИтого: 150 000,00 руб."
                        },
                        "stepIds": ["classify", "recognize-invoice"]
                    }
                ],
                "items": [
                    {
                        "field": "INN",
                        "confidence": 0.92,
                        "text": "7707083893",
                        "isValid": true,
                        "coordinates": {
                            "minX": 100,
                            "minY": 200,
                            "maxX": 300,
                            "maxY": 230
                        }
                    },
                    {
                        "field": "TotalAmount",
                        "confidence": 0.88,
                        "text": "150000.00",
                        "isValid": true
                    }
                ],
                "isPdfCreated": true,
                "stepIds": ["classify", "recognize-invoice"]
            }
        ],
        "errors": []
    },
    "files": [
        {
            "id": "d353c73d-c1f9-4dc5-bdd1-9a73565e566c",
            "originalFileName": "invoice-01.png",
            "extension": ".png",
            "contentType": "image/png",
            "contentLength": 114159,
            "type": "Image",
            "sourceFileType": "png",
            "fileType": "png"
        }
    ],
    "stepsInWork": []
}

Описание полей ответа

  • expiresAt — дата и время удаления пакета с сервера. По умолчанию пакет хранится 1 час. Значение можно изменить в параметре ClearRequestsService > DefaultExpirationSeconds файла конфигурации Api.Inference.

    Даже если пакет не успел обработаться за отведённое время, он всё равно будет удалён с сервера.

  • processing.isStarted — запущена ли обработка пакета.

  • processing.isReady — завершена ли обработка пакета.

    • true — все шаги конвейера завершены.
    • false — обработка ещё продолжается.

  • processing.isCancelled — отменена ли обработка.

  • processing.documents — массив распознанных документов. Каждый документ содержит:

    • title — название (из documentDefinitions конвейера)
    • classConfidence — уверенность классификации
    • pages — массив страниц с постраничными результатами
    • items — объединённые данные документа (все поля со всех страниц)
    • isPdfCreated — готов ли PDF к скачиванию

  • processing.notClassified — страницы, не попавшие ни в один класс документа.

  • processing.errors — ошибки, возникшие при обработке (с указанием stepId и fileIds).

  • stepsInWork — шаги, находящиеся в процессе выполнения, с индексами обрабатываемых файлов.

Подробное описание структуры результатов см. в статье Конвейер пакетной обработки — Интерпретация результатов.

Получить конвейер

Текущую конфигурацию конвейера можно получить методом:

GET /api/packages/{requestKey}/pipeline

GET /api/packages/e1f19acc-f9a2-435c-9c9b-38c4a09a7468/pipeline HTTP/1.1
Host: ai-server-endpoint:44392
Accept: application/json
Authorization: ••••••

Сервер возвращает JSON-объект конвейера — ту же структуру, которая была загружена при настройке.

Получить документ

Результаты отдельного документа можно получить методом:

GET /api/packages/{requestKey}/Document/{documentId}

Где:

  • {requestKey} — идентификатор пакета
  • {documentId} — идентификатор документа из поля processing.documents[].id
GET /api/packages/e1f19acc-f9a2-435c-9c9b-38c4a09a7468/Document/b2c3d4e5-f6a7-8901-bcde-f01234567890 HTTP/1.1
Host: ai-server-endpoint:44392
Accept: application/json
Authorization: ••••••

Сервер возвращает JSON-объект документа (PackageDocumentDto).

Скачать PDF документа

PDF-файл документа можно скачать методом:

GET /api/packages/{requestKey}/Document/{documentId}/File

GET /api/packages/e1f19acc-f9a2-435c-9c9b-38c4a09a7468/Document/b2c3d4e5-f6a7-8901-bcde-f01234567890/File HTTP/1.1
Host: ai-server-endpoint:44392
Accept: application/pdf
Authorization: ••••••

В ответ возвращается бинарное содержимое PDF-файла.

ℹ️

PDF генерируется только для документов с isPdfGenerated: true в documentDefinitions. Если PDF ещё не готов, сервер вернёт статус 102 Processing.

Скачать изображение страницы

Изображение обработанной страницы можно скачать методом:

GET /api/packages/{requestKey}/File/{fileId}

Где:

  • {requestKey} — идентификатор пакета
  • {fileId} — идентификатор файла из поля pages[].file.id документа
GET /api/packages/e1f19acc-f9a2-435c-9c9b-38c4a09a7468/File/d353c73d-c1f9-4dc5-bdd1-9a73565e566c HTTP/1.1
Host: ai-server-endpoint:44392
Accept: application/octet-stream
Authorization: ••••••

В ответ возвращается бинарное содержимое изображения.

Отменить обработку

Обработку пакета можно прервать методом:

POST /api/packages/{requestKey}/cancel

POST /api/packages/e1f19acc-f9a2-435c-9c9b-38c4a09a7468/cancel HTTP/1.1
Host: ai-server-endpoint:44392
Accept: application/json
Authorization: ••••••

При успешной отмене сервер возвращает 204 No Content.

Сервер отменит все шаги, находящиеся в процессе выполнения, и освободит занятых агентов. Пакет получит флаг processing.isCancelled = true.

⚠️

Отмена возможна только для запущенных, но ещё не завершённых пакетов. Если пакет уже обработан или ещё не запущен, сервер вернёт ошибку 422 Unprocessable Entity.

Коды ответов

КодОписание
200Запрос выполнен
201Пакет создан
204Операция выполнена (конвейер сохранён, обработка запущена/отменена)
400Неверные параметры запроса или невалидный конвейер
402Нет доступных лицензий
403Доступ запрещён
404Пакет или документ не найден
422Операция невозможна в текущем состоянии пакета
Агентская системаКонвейер пакетной обработки