API DOKIVO: текстовые PDF-спецификации в проверяемый Excel

Передавать спецификации в обработку из своей системы

Закупщику приходят PDF от нескольких поставщиков. В каждом нужно найти таблицу позиций, сопоставить артикул, название, количество, цену и сумму, затем собрать общую книгу Excel. Когда такой набор появляется регулярно, повторять настройки руками неудобно. В DOKIVO теперь можно сохранить проверенные правила как версию сценария и передавать новые спецификации через API.

Первый принятый сценарий связывает извлечение таблиц PDF в Excel с разделом автоматизации. На сайте видны источник, действие и результат, а интеграция использует ту же сохранённую версию. Разработчику не нужно заново описывать устройство таблицы в каждом запросе; сотрудник, который проверял образец, понимает, какие правила попадут в работу.

Речь о текстовых PDF спецификаций. В принятом 28 октября сценарии OCR выключен: фотографию страницы нельзя считать эквивалентом PDF с текстовым слоем. Расширение API на остальные обработчики на дату проверки разрабатывается отдельно. Здесь разбираем уже установленный путь PDF → правила спецификации → XLSX и его фактическую проверку.

Правила сохраняются отдельно от документов

Сначала откройте работу со спецификациями, настройте сопоставление столбцов на понятном образце и проверьте результат. По явному действию «Сохранить для API и n8n» нормализованный рецепт сохраняется в аккаунте. В него входят настройки извлечения и проверки; исходные PDF и строки найденных таблиц не становятся частью рецепта.

Такое разделение важно для повторяемости. Правило «этот столбец — артикул» полезно на следующей спецификации; старая цена из конкретной строки полезной настройкой не является. Сценарий хранит способ обработки, а каждый запуск получает собственные файлы. Общая таблица результата остаётся самостоятельным документом со своим сроком скачивания.

У версии есть номер. Если позже изменить соответствия или условия включения строк, новая версия не меняет старый запуск. Интеграция явно указывает, какие правила использовать. Поэтому результат можно объяснить не фразой «так сейчас настроен сайт», а связкой из входного комплекта, сценария, версии и конкретного запуска.

Что происходит между POST и готовой книгой

Описание маршрутов доступно в OpenAPI DOKIVO. Запуск создаётся запросом POST /api/v1/runs: multipart-поля files содержат PDF, а текстовое поле request — JSON с scenarioId, version и requestCreatedAt. API-ключ передаётся заголовком Authorization, а не частью адреса.

Ответ 202 означает, что задание принято, и возвращает runId и адрес статуса. Это ещё не доказательство готовности таблицы. Клиент проверяет GET /api/v1/runs/:id, дожидается конечного состояния и скачивает результат по отдельному маршруту. Повтор скачивания не должен создавать ещё одну обработку PDF.

Под этим контрактом используется прежняя очередь заданий, резервирование доступной квоты, изолированный обработчик и зашифрованное временное хранилище. Мы не добавляли второй независимый конвертер только для API: интерфейс и интеграция обращаются к существующему пути обработки. Это позволяет проверять одни и те же правила на сайте и в автоматическом запуске.

Три PDF, четыре строки и проверка настоящего XLSX

В приёмке использовали три публичных учебных PDF. Два документа дали четыре точные строки, третий был исключён как схема. Итог имел состояние needs_attention. Это ожидаемый полезный результат: сервис не превратил неподходящий файл в молчаливо пустую «успешную» таблицу, а оставил объяснение в книге.

Скачанный XLSX независимо открыли библиотекой ExcelJS. Проверили пять листов, четыре ожидаемые строки, арифметические произведения, ведущие нули текстового артикула и запись, похожую на формулу. Исполняемых формул в этом контрольном результате было ноль. Два скачивания одного API-результата совпали побайтно; срок доступности при повторе не увеличился.

Отдельный путь прошли через сайт на широком и узком экранах: выбрали три PDF, запустили сохранённый сценарий, скачали книгу и повторили скачивание. Сохранённые байты также прочитали независимо. Проверка интерфейса не подменяла проверку файла: надпись «готово» сама по себе не показала бы, потерялся ли ноль в артикуле или превратилась ли строка в формулу.

Серверный набор включал проверки API и базы данных, шаблона n8n, вебхуков и интерфейса. Эти результаты относятся к описанному сценарию. Они не означают, что любая таблица любого поставщика извлекается без пропусков, а все исходные цены правильны. Важные строки и замечания по-прежнему проверяйте по исходной спецификации.

С чего начать интеграцию

1. Выберите контрольную спецификацию. Нужен PDF с текстовым слоем и понятной структурой. Проверьте его в обычном инструменте, затем сохраните правила для API и n8n.
2. Создайте ключ в разделе подключений. Для доступа нужны вход и подтверждённая почта. Сохраните показанный один раз секрет в защищённой настройке своей системы.
3. Передайте файлы и конкретную версию. Добавьте постоянный ключ намерения, чтобы потерянный сетевой ответ не превратился в дублирующий запуск.
4. Разделите два исхода. Книгу без замечаний направляйте в дальнейшую работу, а needs_attention — на проверку исключённых файлов и спорных значений.
5. Скачайте и сохраните результат. Файл доступен временно. Успех загрузки в вашу CRM или хранилище должна подтвердить уже целевая система.

Лимиты действуют совместно: возможности аккаунта и пределы сценария. У первой версии есть технические ограничения на число и размер PDF; API не отменяет квоты сайта. Поэтому перед пакетной интеграцией проверьте действующий доступ в своём аккаунте, а не копируйте число файлов из чужого снимка экрана.

API, n8n и MCP: какую возможность мы действительно предоставляем

OpenAPI описывает HTTP-контракт, а n8n связывает этот контракт с источником файлов и дальнейшими действиями. MCP — отдельный способ предоставлять инструменты ИИ-приложению. Наличие HTTP API и JSON-шаблона n8n само по себе не означает, что у DOKIVO уже работает отдельный MCP-сервер. В принятом здесь выпуске такой сервер не заявлен.

Для собственного агента разработчик может использовать подтверждённый API как интеграционный контракт, сохраняя контроль версии, прав и результата. Но настройка обёртки, выбор документов и разрешение на запуск остаются частью его приложения. Мы отделяем работающий путь от возможного следующего подключения, чтобы техническое описание помогало воспроизвести результат.

Частые вопросы