PDF.co позволяет извлекать текст и таблицы из PDF, распознавать сканы, превращать документы в JSON, CSV, XML, Excel, HTML и изображения, объединять и разделять страницы, заполнять формы, добавлять текст, подписи и графику, а также встраивать эти операции в автоматические процессы через API. Для проверки запроса без написания программы служат API Tester, PDF Inspector, Document Parser, хранилище Files и журналы выполнения, поэтому один и тот же сценарий можно сначала отладить вручную, а затем перенести в код, Zapier, Make или n8n.

Рабочий процесс начинается с выбора инструмента в разделе API Tools. Карточки ведут к тестеру запросов, шаблонам извлечения, классификатору, инспектору PDF, генератору HTML-шаблонов и файловому хранилищу. В типовом задании пользователь загружает исходный документ или указывает доступную ссылку, выбирает конечный формат, задаёт страницы, язык OCR и дополнительные параметры, отправляет запрос и получает структурированный ответ с результатом, количеством обработанных страниц, расходом кредитов и временной ссылкой на созданный файл.

PDF.co особенно полезен там, где операция должна повторяться по единым правилам: разбирать счета, получать реквизиты из форм, делать сканы доступными для поиска, формировать PDF из HTML, раскладывать многостраничные пакеты по отдельным документам или передавать результат в CRM и облачное хранилище. При разовой ручной правке страницы потребуется больше подготовки, потому что положение текста и изображений задаётся координатами или именами полей, зато настроенный запрос обрабатывает следующие документы без повторения однообразных действий.

Интерфейс и выбор инструмента

Главная рабочая область собрана вокруг вкладок Home, API Tools, API Logs и Subscription. В API Tools инструменты разбиты по назначению: извлечение данных, создание и редактирование, преобразование и управление документами. Поиск по карточкам удобен, когда известно действие, но не название конечной точки. Например, для чтения полей формы выбирают PDF Inspector, для отладки любого метода — API Tester, для повторяемого разбора счетов — Document Parser Manager, а для постоянного доступа к шаблонам и исходникам — Files.

Карточка API Tester открывает интерактивную документацию с перечнем методов слева и формой запроса справа. Карточка Files предназначена не для просмотра PDF как в файловом менеджере операционной системы, а для хранения объектов, которые затем используются по ссылке или через file token в запросах. Document Classifier и AI Invoice Parser решают более узкие задачи: первый присваивает документу класс по правилам или модели, второй возвращает нормализованные данные счёта без ручной разметки шаблона.

Для спокойной работы стоит заранее определить, какой результат нужен на выходе. Если требуется файл, выбирают метод преобразования или редактирования; если нужны данные для базы, предпочтительны JSON, CSV, XML либо Document Parser; если задача связана с контролем структуры, сначала используют PDF Info Reader или PDF Inspector. Такой выбор уменьшает число пробных запросов и помогает не расходовать кредиты на неподходящую операцию.

API Tester: проверка запроса без программирования

API Tester показывает доступные методы, обязательные заголовки и тело запроса. После выбора операции форма подсвечивает обязательные параметры, а рядом формирует пример cURL. Пользователь вводит API-ключ, указывает ссылку на документ, при необходимости заполняет диапазон страниц, пароль, имя выходного файла, язык OCR и профиль дополнительных настроек. Кнопка Send или Run Request отправляет реальный запрос, поэтому тест следует считать полноценной обработкой, а не демонстрацией интерфейса.

Ответ содержит код состояния, признак ошибки, сообщение, имя результата, число страниц, длительность операции, затраченные и оставшиеся кредиты. Для файловых операций возвращается временная ссылка и срок её действия. Если параметр inline поддерживается выбранным методом, результат можно получить внутри JSON; это удобно для текста или небольших структур, но для крупных бинарных файлов практичнее работать со ссылкой и сразу копировать результат в собственное хранилище.

Перед переносом запроса в код полезно сделать три проверки. Сначала прогнать небольшой корректный документ и сохранить успешное тело запроса. Затем намеренно изменить один параметр, чтобы увидеть формат ошибки. Наконец, повторить операцию на документе с большим количеством страниц и оценить время, расход кредитов и необходимость асинхронного режима. Такой цикл заранее выявляет проблемы с доступностью ссылок, нумерацией страниц и форматированием JSON.

Загрузка файлов и доступ к исходникам

Большинство методов принимает исходный файл через URL. Это может быть публичная ссылка, объект в PDF.co Files, временный адрес после загрузки или ресурс облачного диска, доступный без интерактивной авторизации. Если ссылка открывает страницу просмотра вместо самого файла, сервер получает HTML и возвращает ошибку типа документа. Поэтому перед запросом стоит проверить, что адрес отдаёт PDF, изображение или другой ожидаемый формат напрямую.

Для временной загрузки крупных файлов предусмотрена схема с предварительно подписанным адресом. Сначала запрашивается presigned URL, затем файл отправляется методом PUT, после чего конечный URL передаётся в нужную операцию. Документация указывает возможность загрузки временных объектов размером до 2 ГБ; такие задачи следует запускать с async=true. Временные загрузки автоматически удаляются примерно через час, поэтому их нельзя использовать как постоянное хранилище.

Размер самого API-запроса ограничен 4 МБ. Это ограничение относится к телу запроса, а не к файлу, загруженному по отдельной ссылке. Попытка вложить большой Base64-блок непосредственно в JSON быстро превышает лимит; надёжнее загрузить файл отдельно и передать короткий URL или file token. Для очень маленьких объектов имеется отдельный метод загрузки, но его лимит заметно ниже, поэтому он подходит главным образом для служебных образцов.

Если исходник находится в Google Drive, частые обращения к одной ссылке могут упереться в ограничения самого Drive. В документации PDF.co рекомендуется не создавать поток из десятков запросов в минуту к бесплатным ссылкам Google. В массовом процессе лучше перенести исходник в PDF.co Files, Amazon S3 или другое хранилище, где доступ к объекту предсказуем и не требует открытия страницы подтверждения.

Преобразование PDF в текст и OCR

Для обычного PDF с текстовым слоем подходит быстрый метод PDF to Text Simple. Он извлекает символы без OCR, сложного анализа макета и профилей, поэтому расходует меньше ресурсов. Если документ отсканирован, содержит смешанные страницы, колонки или нестандартный порядок объектов, используют полный PDF to Text. Этот метод умеет подключать OCR и сохранять расположение строк, что важно для счетов, отчётов и форм.

Параметр lang задаёт язык распознавания. По умолчанию используется английский, но можно указать другой код или комбинацию двух языков через знак плюс. Для русско-английского документа следует выбрать оба языка, иначе фамилии, номера моделей и латинские реквизиты могут распознаться хуже. Одновременное включение лишних языков не улучшает качество автоматически: оно расширяет набор допустимых символов и иногда увеличивает число неоднозначностей.

OCRResolution управляет разрешением распознавания. Значение 300 dpi является практичной отправной точкой для большинства сканов. Низкое разрешение ускоряет работу, но ухудшает мелкий текст; чрезмерно высокое увеличивает время и расход памяти без гарантии более точного результата. Перед массовой обработкой полезно проверить 200, 300 и 400 dpi на нескольких типовых страницах, а затем закрепить лучшее значение в профиле.

Для создания поискового PDF используется операция Make Text Searchable. Она распознаёт скан и добавляет невидимый текстовый слой, сохраняя визуальный вид страницы. После обработки документ можно искать, индексировать и копировать из него фрагменты. Качество следует проверять не только по внешнему виду, но и поиском нескольких слов с разными буквами, цифрами и знаками, потому что ошибочный текстовый слой визуально не заметен.

Предобработка сканов

OCR чувствителен к перекосу, шуму, слабому контрасту и неправильной ориентации. В профилях доступны параметры режима распознавания и фильтров предварительной обработки. Их следует менять по одному: сначала исправить поворот, затем оценить контраст, после этого тестировать удаление шума. Одновременное включение нескольких агрессивных фильтров способно стереть тонкие линии таблицы или точки в адресах электронной почты.

Если PDF содержит векторные надписи, превращённые в контуры, стандартное извлечение текста может вернуть пустой результат. В таком случае требуется режим OCR, который анализирует графическое представление, а не только текстовые объекты. Обратная ситуация возникает с качественным цифровым PDF: принудительный OCR может внести ошибки туда, где исходный текст уже был точным. Поэтому режим Auto подходит для смешанных документов, а специализированный профиль — для однородной партии.

Извлечение таблиц, CSV, Excel и структурированных данных

PDF to CSV и PDF to Excel рассчитаны на документы, где строки и столбцы можно восстановить из расположения текста. Результат зависит от того, насколько последовательно построена исходная таблица. Настоящая таблица с одинаковыми координатами колонок обычно преобразуется лучше, чем страница, где значения расставлены пробелами, рамки нарисованы отдельными линиями, а ячейки объединены сложным образом.

При проверке CSV нужно смотреть не только на открытие файла, но и на количество столбцов, разделитель, кавычки, переносы строк и десятичные знаки. Если описание товара содержит запятую, корректный CSV должен заключить поле в кавычки. Если одна ячейка переносится на две строки, обработчик может создать дополнительную запись. Такие случаи лучше отлавливать до импорта в бухгалтерию или CRM.

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

После запуска шаблона результаты показываются в нескольких представлениях: таблица, JSON, CSV, XML, YAML и простой текст. Вкладка Parsing Log помогает понять, почему поле не найдено или строка пропущена. Перед сохранением шаблона стоит проверить минимум три документа одного типа: короткий, многострочный и содержащий пустые значения. Шаблон, настроенный только по идеальному примеру, часто ломается на первом реальном исключении.

JSON, XML и HTML как форматы результата

PDF to JSON подходит, когда текст и таблицы должны перейти в программу без промежуточной ручной обработки. В ответе важно различать простой текст, координаты, страницы и структурированные блоки. Если downstream-система ожидает фиксированную схему с полями invoiceNumber, date и total, прямое преобразование всего PDF в JSON может дать слишком общий результат; тогда лучше применять Document Parser или AI Invoice Parser.

XML полезен для систем, где уже настроены XPath, XSLT или обмен документами по формальным схемам. CSV проще открыть в электронных таблицах, но он плохо передаёт вложенные структуры, несколько таблиц и неоднородные страницы. HTML сохраняет больше информации о расположении и удобен для публикации или последующего анализа верстки, однако его нельзя считать точной копией исходного PDF во всех случаях: шрифты, плавающие объекты и сложные слои могут потребовать дополнительной проверки.

Параметр inline следует выбирать осознанно. Встроенный результат удобен для небольшого текста и JSON, потому что приложение получает данные одним ответом. Для больших результатов ссылка уменьшает размер ответа и позволяет скачать файл отдельным потоком. Независимо от варианта нужно проверять error, status и message, а не делать вывод об успехе только по наличию поля url.

Document Parser: шаблоны для повторяющихся документов

Document Parser Manager хранит шаблоны извлечения. В списке видны библиотечные примеры, идентификаторы и кнопки запуска. Новый шаблон открывается в визуальном редакторе: справа отображается тестовый PDF, слева — объекты и их свойства. Пользователь загружает образец, выделяет прямоугольник, задаёт имя поля, выражение, тип данных и при необходимости регулярное выражение или макрос.

Методы выбора поля различаются. Rectangle selection берёт данные из фиксированной области. Key Value extraction ищет значение рядом с подписью. Text Search привязывает поле к найденной фразе. Virtual Grid полезен, когда страница напоминает таблицу, но не содержит настоящих ячеек. Static value добавляет постоянное значение, например код канала. Правильный метод выбирают по тому, что остаётся стабильным в документах: координата, подпись, структура таблицы или контекст.

В редакторе страницы нумеруются с нуля в API, хотя интерфейс просмотра может показывать человеку первую страницу как 1. Эта разница особенно важна для многостраничных шаблонов. Поле, настроенное на pageIndex 0, относится к первой странице. Если в коде подставить 1, извлечение перейдёт на вторую страницу и вернёт пустое значение либо чужой фрагмент.

Кнопка Run Template выполняет проверку на текущем образце. Результаты отображаются рядом с документом, что позволяет сравнить ожидаемое значение и фактическое. Полезно проверять пробелы, разделители тысяч, формат даты, валютный знак и многострочные адреса. После успешной проверки шаблон сохраняют и получают Template ID; именно этот идентификатор передаётся в запрос Document Parser.

Запуск шаблона через API

В API Tester выбирают Document Parser и формат ответа, указывают Template ID, добавляют исходный PDF и решают, возвращать ли результат inline. Для JSON ответ удобнее получать встроенным, если размер данных небольшой. При XML или CSV можно использовать выходной файл. В запросе также доступны пароль документа, асинхронный режим и профили.

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

Предварительный просмотр JSON показывает имена объектов, значения, тип, индекс страницы и прямоугольник. Координаты полезны для аудита: если значение выглядит подозрительно, можно открыть исходную страницу и проверить место, откуда оно взято. Такая трассировка особенно важна для финансовых документов, где ошибочно распознанная цифра должна быть обнаружена до автоматической проводки.

AI Invoice Parser и шаблонный разбор счетов

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

Шаблонный Document Parser предпочтительнее, когда документы одного поставщика имеют стабильную форму и требуется предсказуемое извлечение специальных полей. AI-парсер удобнее для разнообразного потока и быстрого первичного разбора. В практической системе часто используют комбинацию: сначала классифицируют документ, затем известные классы направляют в шаблоны, а неизвестные счета — в AI Invoice Parser с обязательной проверкой результата.

Нельзя считать уверенность модели заменой бизнес-контролю. Общая сумма должна совпадать с суммой строк и налогов, дата не должна выходить за допустимый период, валюта должна соответствовать контрагенту, а номер счёта — проходить проверку формата. PDF.co выполняет извлечение, но правила допустимости остаются задачей системы, которая принимает данные.

Document Classifier: сортировка входящего потока

Document Classifier присваивает документу класс по содержимому. Правила можно описать в CSV, где указываются имя класса, логика OR или AND и ключевые слова либо фразы. Например, счета одного поставщика распознаются по названию компании и характерным реквизитам, банковские выписки — по заголовкам и обозначениям счетов, а договоры — по устойчивым формулировкам.

Логику OR используют, когда достаточно любого из нескольких признаков. AND уменьшает ложные совпадения, требуя присутствия всех заданных фраз. Слишком общие слова вроде итого или дата не годятся как самостоятельные признаки: они встречаются во множестве документов. Надёжное правило сочетает название организации, уникальный термин и при необходимости регулярное выражение для номера.

На сканах классификатор зависит от OCR. Если ключевая фраза распознана неверно, класс не будет найден. Поэтому для проблемных партий указывают правильный язык, проверяют ориентацию и сохраняют класс unknown для ручной обработки. Автоматическая маршрутизация должна уметь безопасно остановиться, а не назначать случайный класс при недостатке признаков.

Классификация экономит ресурсы, когда последующие операции различаются. Счёт можно отправить в парсер реквизитов, договор — в поиск дат и сторон, анкету — в чтение полей формы, а изображение штрихкода — в Barcode Reader. Один универсальный запрос обычно даёт менее точный и более дорогой результат, чем короткая цепочка специализированных шагов.

PDF Inspector: поля, координаты и структура

PDF Inspector помогает понять, из чего состоит документ. После загрузки можно выбирать текст, изображения и поля формы, видеть координаты и имена объектов. Инструмент особенно важен перед заполнением формы: значение отправляется не в визуальную подпись на странице, а в точное fieldName, которое чувствительно к регистру и вложенной структуре.

Координаты задаются в системе PDF, а страницы в API обычно индексируются с нуля. Перед добавлением текста или изображения нужно проверить x, y, ширину, высоту и ориентацию страницы. Если PDF содержит страницы разных размеров, координаты одной страницы нельзя бездумно применять ко всем. Для водяного знака на каждой странице лучше рассчитать положение относительно размеров или подготовить отдельные значения.

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

Добавление текста, изображений и подписей

Метод PDF Add добавляет поверх исходного документа текстовые аннотации, изображения, ссылки, элементы формы и содержимое других PDF. Для текста задаются координаты, страницы, шрифт, размер, цвет, выравнивание и при необходимости ссылка. Для изображения указываются URL, x, y, ширина, высота и диапазон страниц. Подпись обычно вставляется как изображение, поэтому заранее нужно подготовить прозрачный PNG и проверить его разрешение.

Диапазон страниц следует тестировать на копии. Запись 0 относится к первой странице, 0- может означать начиная с первой до конца, а перечисление и интервалы позволяют выбирать отдельные страницы. Ошибка в диапазоне способна поставить штамп на весь документ. В финансовом процессе лучше сначала создать результат для одной страницы, проверить его визуально, затем расширить правило.

Шрифт должен поддерживать нужные символы. Даже если название шрифта принимается параметром, конкретное начертание может отсутствовать или заменить кириллицу. Для русского текста нужно проверить буквы Ё, Й, Щ, кавычки, длинное тире и знак рубля. Цвет задаётся в RGB или ARGB; альфа-канал полезен для полупрозрачных водяных знаков, но слишком слабая прозрачность делает отметку нечитаемой на скане.

При добавлении изображения по ссылке ресурс должен быть доступен серверу. Локальный путь с компьютера не сработает. Файл загружают в Files или временное хранилище, получают URL либо file token и используют его в images. Если изображение растянуто, нужно сохранить пропорции: вычислить высоту из исходного отношения сторон вместо независимого задания случайных width и height.

Заполнение и создание PDF-форм

Заполнение формы выполняется через массив fields или строковый параметр fieldsString. Для каждого значения указываются страница, точное имя поля и содержимое. Текстовые поля получают строки, флажки — логическое значение, радиокнопки и списки требуют значения, которое существует в самой форме. Неверное имя обычно не создаёт новое поле, а оставляет документ без ожидаемого изменения.

Перед массовым заполнением нужно получить список полей через PDF Info Fields или PDF Inspector. Особое внимание следует уделять формам с длинными иерархическими именами. Копировать имя вручную рискованно: лишний пробел или изменение регистра приведёт к промаху. Надёжнее экспортировать карту полей и хранить её вместе с шаблоном документа.

Размер текста ограничен шириной поля. Если значение длиннее, поведение зависит от настроек самой формы: текст может уменьшиться, обрезаться или прокручиваться. Для печатного результата желательно проверять финальный PDF и при необходимости задавать шрифт и размер через расширенный формат. После заполнения форму можно уплощить профилем FlattenDocument, чтобы поля превратились в обычное содержимое и не редактировались случайно.

Создание новых полей требует координат, размеров и типа элемента. Для анкеты можно добавить текстовые области, флажки и другие контролы, но удобство такой формы зависит от точной разметки и порядка табуляции. Если задача состоит в разовом вводе нескольких подписей, добавление текста и изображений проще. Если документ должен регулярно заполняться пользователями, лучше подготовить полноценный шаблон и протестировать его в нескольких PDF-просмотрщиках.

Поиск, замена и удаление текста

PDF Find ищет строку и возвращает координаты совпадений. При включённом regexSearch можно использовать регулярные выражения, например для номеров счетов или дат. Регулярное выражение следует сначала проверить на коротком документе: слишком широкая маска найдёт лишние фрагменты, а сложное выражение увеличит время обработки и усложнит диагностику.

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

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

Кэширование входного URL может помочь при нестабильных ресурсах, которые отвечают ошибкой Too Many Requests или Access Denied. Однако кэш нужно применять только к неизменяемому файлу. Если по одному адресу публикуются разные версии документа, сохранённая копия способна привести к обработке старого содержимого.

PDF в JPG, PNG, TIFF и WEBP

Преобразование страниц в изображения используется для миниатюр, предпросмотра, контрольного просмотра и последующего компьютерного зрения. PDF.co предлагает отдельные методы для JPG, PNG, TIFF и WEBP. JPG подходит для фотографий и небольшого размера, PNG — для текста и прозрачности, TIFF — для некоторых документооборотных и полиграфических процессов, WEBP — для компактной публикации в современных веб-системах.

Параметр rect ограничивает вывод прямоугольной областью x, y, width и height. Это позволяет извлечь отдельную иллюстрацию или фрагмент страницы без последующей обрезки. Координаты удобно получить в PDF Inspector. При ошибке в порядке значений изображение окажется пустым, смещённым или обрезанным, поэтому прямоугольник сначала проверяют на одной странице.

Разрешение и качество нужно подбирать под назначение. Для OCR мелкого текста полезно более высокое разрешение, для списка миниатюр — умеренное. Увеличение DPI не восстанавливает детали, отсутствующие в исходном скане, но резко повышает размер файлов. Если в документе сотни страниц, нужно оценить общий объём до запуска и использовать асинхронный режим.

При пакетном выводе результат может включать несколько файлов или пакет. Приложение должно уметь сопоставить номер страницы и имя изображения. Надёжная схема именования содержит исходный идентификатор и индекс страницы с ведущими нулями, чтобы сортировка не ставила страницу 10 перед страницей 2.

Создание PDF из документов, изображений, HTML и URL

PDF.co создаёт PDF из изображений, офисных документов, таблиц, CSV, HTML, веб-страниц и электронной почты. Для изображений можно передать несколько URL через запятую; порядок ссылок определяет порядок страниц. Перед объединением нужно привести картинки к правильной ориентации и разумному разрешению, иначе итоговый PDF получится тяжёлым или с разными полями.

Конвертация DOC, DOCX, XLS и XLSX полезна в автоматизации, где исходные файлы поступают без участия человека. Электронные таблицы требуют особой проверки: область печати, переносы, ширина колонок, скрытые листы и масштаб могут отличаться от привычного открытия в Excel. Параметры autosize и worksheet index следует задавать явно, когда документ содержит несколько листов.

Преобразование URL создаёт PDF из доступной веб-страницы. Динамические элементы, авторизация, задержанная загрузка и всплывающие окна могут изменить результат. Для стабильного отчёта надёжнее передавать собственный HTML с известными стилями, чем печатать произвольную страницу, которая меняется без уведомления.

Конвертация MSG и EML умеет включать вложения и преобразовывать их. Внутренние изображения и ресурсы должны быть доступны обработчику; локальные ссылки и закрытые ресурсы не загрузятся. Перед долговременным хранением писем нужно проверить кодировку темы, имена отправителей, часовой пояс, отображение HTML-подписи и порядок вложений.

HTML to PDF и управление макетом

HTML to PDF принимает HTML-код, URL или сохранённый шаблон. Параметры paperSize и orientation задают бумагу и ориентацию, margins принимают размеры в пикселях, миллиметрах, сантиметрах или дюймах, а printBackground управляет печатью фонов. Media type переключает стили screen и print, поэтому один и тот же HTML может выглядеть по-разному в браузере и в PDF.

Для счетов и отчётов лучше использовать самостоятельный HTML с встроенными или надёжно доступными стилями. Относительные пути к изображениям и шрифтам часто становятся причиной пустых мест. Ресурсы следует размещать по доступным адресам или в хранилище, а важные размеры задавать явно. CSS-разрывы страниц нужно тестировать на длинных таблицах, чтобы заголовок не остался внизу страницы отдельно от данных.

HTML to PDF Template Manager позволяет хранить повторно используемые шаблоны. Данные подставляются в подготовленную структуру, что уменьшает объём запроса и упрощает контроль дизайна. При изменении шаблона следует вести собственную ревизию: новая верстка может повлиять на старые интеграции, даже если имена полей не изменились.

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

Объединение и разделение PDF

Merge объединяет несколько PDF и поддерживаемых файлов в заданном порядке. Перед запросом нужно убедиться, что все ссылки доступны и документы открываются. Если один файл защищён паролем или повреждён, вся операция может завершиться ошибкой. В рабочем процессе полезно предварительно проверять каждый файл через PDF Info Reader и объединять только прошедшие контроль.

Split делит документ по диапазонам страниц. Кроме обычного разбиения, доступны сценарии по найденному тексту или штрихкоду. Это удобно для пачки счетов, где каждая новая запись начинается с фразы Invoice Number, либо для сканов с разделительными штрихкодами. Условие разделения нужно проверять на страницах, где ключевая фраза повторяется внутри одного документа, иначе файл будет разрезан слишком часто.

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

Имена выходных файлов лучше формировать из бизнес-данных после извлечения, а не только из номера части. Например, документ можно сначала разделить, затем распознать номер счёта и переименовать результат. При ошибке OCR необходимо резервное имя с уникальным идентификатором, чтобы два файла не перезаписали друг друга.

Поворот, удаление и перестановка страниц

PDF Rotate изменяет ориентацию выбранных страниц. Угол и диапазон задаются явно. Для сканов с разной ориентацией доступен Auto Rotate, который анализирует текст и пытается определить правильное положение. Автоповорот зависит от языка OCR и наличия читаемого текста; страница с одной фотографией или чертежом может не дать достаточных признаков.

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

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

Сжатие и оптимизация

PDF Compress уменьшает размер за счёт оптимизации изображений и объектов. Результат зависит от состава документа: скан с фотографиями обычно сжимается заметнее, чем PDF с уже оптимизированным текстом и векторной графикой. Старый метод Optimize помечен как устаревший, поэтому новые процессы следует строить на Compress.

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

Для входящих документов разумно задавать порог. Маленький PDF не нужно сжимать повторно, а огромный скан стоит сначала привести к правильному разрешению. Повторное JPEG-сжатие каждого шага накапливает артефакты. Лучше хранить исходник и создавать отдельную оптимизированную копию для отправки.

Пароли, разрешения и шифрование

Для защищённого PDF пароль передаётся параметром password. Ошибка 441 означает неверный пароль. Ошибка 443 указывает, что операция запрещена разрешениями документа. Профиль CheckPermissions=false может отключить проверку, но применять его допустимо только владельцу документа или при наличии законного разрешения.

PDF Add/Remove Password добавляет и снимает защиту в разрешённых сценариях. Пароли нельзя записывать в журнал открытым текстом или включать в общие шаблоны. В интеграции их хранят в секретах платформы и подставляют во время выполнения. API-ключ также относится к секретам: его передают в заголовке x-api-key, не добавляют в публичный URL и не помещают в клиентский JavaScript, доступный посетителям сайта.

Параметр encrypt и пользовательское шифрование защищают выходные данные, но не отменяют необходимость контролировать доступ к временной ссылке. Ссылка может содержать подписанные параметры и действует ограниченное время. Её не следует отправлять в публичный чат или сохранять в журнал, доступный всем сотрудникам.

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

Сведения о PDF, поля и вложения

PDF Info Reader возвращает число страниц, автора, заголовок, тему, ключевые слова, даты создания и изменения, программу-создатель, размеры страниц, признаки шифрования и разрешения. Эти данные полезны для предварительной маршрутизации. Например, слишком большое число страниц переводит задачу в асинхронный режим, а защищённый документ отправляется на запрос пароля.

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

PDF Info Fields возвращает структуру интерактивных полей: имена, типы и значения. Это основа для автоматического заполнения. PDF Attachments Extract извлекает вложенные файлы; их нужно проверять отдельно, потому что PDF может содержать документы, не видимые на страницах. При антивирусной политике вложения следует считать недоверенными, даже если основной PDF выглядит безопасно.

Штрихкоды и электронная почта

Barcode Reader распознаёт штрихкоды и QR-коды в PDF и изображениях. Для многостраничных документов задают страницы и при необходимости область поиска. Ограничение области ускоряет обработку и уменьшает ложные совпадения, если известно, что код всегда находится в правом верхнем углу. При плохом скане полезно проверить разрешение и контраст до увеличения числа распознаваемых типов.

Barcode Generator создаёт код из заданного значения. Перед использованием в документах нужно проверить контрольные требования конкретного стандарта, размер тихой зоны и печатное разрешение. Код, который читается на экране, может не распознаться после уменьшения или факсимильной передачи.

Методы работы с электронной почтой конвертируют MSG и EML в PDF, извлекают вложения и могут отправлять сообщения. При автоматическом долговременном хранении нужно сохранять заголовки, время, отправителя, получателей и вложения так, чтобы связь между ними не потерялась. Если вложение преобразуется отдельно, в имени результата должен оставаться идентификатор письма.

Синхронный и асинхронный режим

Синхронный запрос удерживает соединение до завершения и удобен для небольших операций. Если обработка занимает больше примерно 30 секунд, возрастает риск тайм-аута. Асинхронный режим запускает фоновую задачу и сразу возвращает jobId. Затем приложение вызывает /v1/job/check или получает уведомление через webhook.

Для временных файлов до 2 ГБ и сложных задач документация рекомендует async=true. Проверять статус следует с разумным интервалом: небольшие задания можно опрашивать чаще, крупные — примерно раз в 10–15 секунд. Слишком частый polling расходует кредиты и создаёт лишнюю нагрузку. Статусы включают working, success, failed, aborted и unknown.

При success ответ содержит URL результата, срок действия ссылки, число страниц, длительность и расход кредитов. При failed нужно записать message и идентификатор задания, но не секреты. Повторять запрос без анализа причины опасно: повреждённый файл или неверный пароль будут снова расходовать ресурсы.

Webhook удобнее постоянного опроса. PDF.co отправляет callback после завершения, а принимающая сторона проверяет подпись или секретный путь, записывает событие и забирает результат. Обработчик должен быть идемпотентным: повторное уведомление не должно создавать второй платёжный документ или дублировать файл.

Интеграции с Zapier, Make, n8n и другими платформами

Готовые интеграции позволяют собрать процесс без собственного сервера. В Zapier или Make пользователь выбирает действие PDF.co, подключает API-ключ, связывает поля предыдущего шага с URL и параметрами, а результат передаёт в Google Drive, Dropbox, электронную почту, таблицу или CRM. Для редкой операции доступен Custom API Call, который принимает путь конечной точки и JSON.

n8n подходит для более сложных цепочек и самоуправляемой инфраструктуры. В процессе можно получить новый файл, загрузить его, запустить заполнение формы, дождаться jobId, проверить статус, скачать бинарный результат и сохранить его. Каждый узел должен обрабатывать ошибку отдельно; иначе сбой PDF.co может выглядеть как успешное завершение всего workflow.

При передаче данных между платформами важно понимать тип значения. URL результата — строка, бинарный файл — отдельный объект, JSON — структура, а file token нельзя использовать как обычный публичный адрес вне поддерживаемого контекста. Большинство ошибок файл не найден возникает из-за подстановки ссылки на страницу просмотра вместо прямой ссылки или из-за истечения временного URL до следующего шага.

Процесс стоит строить так, чтобы результат немедленно копировался в постоянное хранилище. Затем в CRM или таблицу записывают собственный адрес, идентификатор исходника, статус, расход кредитов и время. Это упрощает повторный запуск и аудит.

Перенос рабочего запроса в код

Документация содержит примеры cURL, JavaScript, Python, C#, Java и PHP. Начинать лучше с запроса, который уже успешно выполнен в API Tester. Из него переносят путь метода, заголовок x-api-key и JSON-параметры. Затем заменяют тестовые значения переменными и добавляют обработку кодов ответа.

Ключ нельзя хранить в репозитории. Его помещают в переменную окружения, менеджер секретов или защищённые настройки CI. Если ключ случайно опубликован, его нужно заменить, а не только удалить из последнего коммита: старое значение остаётся в истории.

Клиент должен задавать тайм-аут, проверять HTTP-статус, разбирать JSON только при подходящем Content-Type и сохранять сообщение об ошибке. Для загрузки результата нужно использовать поток, а не держать крупный PDF полностью в памяти. Имя файла из ответа следует очищать от опасных символов и не использовать как путь без проверки.

Повтор запросов допустим для временных ошибок 408 и 429, но с задержкой и ограничением числа попыток. Ошибки 400, 401, 402, 441 и 442 обычно требуют изменения данных, ключа, баланса, пароля или исходного файла; мгновенный повтор ничего не исправит. Для операций, создающих документы или отправляющих почту, нужно учитывать идемпотентность, чтобы повтор не произвёл дубль.

Кредиты и планирование расхода

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

В панели и ответах отображаются remainingCredits и credits. Эти значения стоит записывать в технический журнал. Для тестовой среды устанавливают ограничение на размер документов и число запусков, чтобы ошибочный цикл не исчерпал баланс. В производстве полезны уведомления о низком остатке и контролируемое пополнение, но автоматическое пополнение должно иметь месячный предел.

Экономия достигается выбором подходящего метода. PDF to Text Simple дешевле сложного OCR, если текстовый слой уже существует. Предварительная классификация не должна быть тяжелее всех последующих операций. Для известных цифровых PDF можно пропускать OCR, а для неизменяемого исходника использовать кэш или хранить полученный результат вместо повторной обработки.

Проверка job/check также может расходовать кредиты. Слишком частое опрашивание увеличивает стоимость без ускорения самой задачи. Webhook или увеличивающийся интервал между проверками обычно эффективнее.

Ошибки PDF.co и способы устранения

Код	Что означает	Что проверить
400	Неверный запрос или недоступный URL	JSON, обязательные поля, прямую ссылку на файл
401	Ошибка авторизации	Заголовок x-api-key и действительность ключа
402	Недостаточно кредитов	Баланс и расчёт стоимости операции
403	Запрещён доступ к исходному URL	Публичность ссылки и ограничения хранилища
408	Тайм-аут	Асинхронный режим и размер документа
415	Неподдерживаемый тип данных	Content-Type и реальный формат файла
429	Слишком много запросов	Ограничение частоты и задержку повторов
441	Неверный пароль PDF	Пароль без пробелов и правильный документ
442	Файл повреждён или не того типа	Открытие исходника и его сигнатуру
443	Операция запрещена разрешениями	Права владельца и настройки безопасности
444	Ошибка разбора profiles	Кавычки, вложенный JSON и поддерживаемые параметры

Ошибка 400 часто связана не с самим PDF, а со ссылкой. Если адрес требует cookies, перенаправляет на вход или возвращает HTML, PDF.co не получает файл. Скачайте ресурс тем же адресом в чистом приватном окне или используйте отдельную загрузку.

Ошибка profiles возникает из-за двойного уровня кавычек. Поле profiles обычно является строкой, внутри которой записана JSON-подобная конфигурация. Пример из документации следует копировать целиком, а затем менять один параметр. Автоматическое построение строки без корректного экранирования приводит к трудно читаемым ошибкам.

Контроль качества результата

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

Тестовый набор должен отражать реальные отклонения: скан под углом, бледный факс, пароль, пустая страница, разный формат даты, отрицательная сумма, многострочный адрес, две валюты, объединённые ячейки, документ без текста и повреждённый файл. Один образцовый счёт не показывает надёжность процесса.

Для критичных полей применяют независимые проверки. Итог счёта сравнивают с арифметикой строк, ИНН или другой идентификатор — с шаблоном, дату — с допустимым диапазоном, номер договора — со справочником. Если проверка не пройдена, документ отправляют человеку вместе с исходной страницей и координатами найденного значения.

После изменения шаблона, профиля OCR или версии внутреннего кода нужно повторно прогнать фиксированный набор документов и сравнить результаты. Автоматический diff JSON помогает увидеть пропавшие поля и изменение типов до публикации процесса.

Безопасная эксплуатация

API-ключ даёт доступ к кредитам и обработке документов, поэтому его права следует ограничивать организационными мерами: отдельные ключи для разработки и производства, регулярная замена, отсутствие в клиентском коде и журналирование использования. Сотруднику, который только проверяет результат, ключ не нужен.

Исходные и выходные файлы следует классифицировать по чувствительности. Для обычных маркетинговых PDF допустим один процесс, для паспортов, медицинских документов и банковских выписок — другой, с минимальными логами и ограниченным хранилищем. Временное удаление файлов через час не решает задачу, если копии остались в почте, интеграционной платформе или журнале ошибок.

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

При использовании webhooks принимающий адрес должен поддерживать HTTPS, проверять отправителя и ограничивать размер тела. Полученное уведомление нельзя считать основанием для доверия к URL без валидации структуры ответа. Результат скачивают в изолированное хранилище и проверяют ожидаемый Content-Type.

Параметр profiles и тонкая настройка

Profiles используется для параметров, которых нет в основной форме конечной точки. Значение передаётся строкой с JSON-подобной конфигурацией, поэтому здесь одновременно действуют правила внешнего JSON и внутренней строки. Типичная ошибка — убрать обязательные кавычки вокруг profiles или не экранировать кавычки внутри. Проще взять рабочий пример из API Tester, выполнить его без изменений и затем добавлять по одному свойству.

Через profiles настраиваются режим OCR, сохранение форматирования, фильтры изображений, уплощение формы, вывод Base64 и другие специализированные параметры. Нельзя переносить профиль из одного метода в другой без проверки: часть свойств относится только к конкретному преобразованию. Неподдерживаемая комбинация приводит к коду 444 или к результату, который отличается от ожидаемого.

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

Base64-вывод нужен, когда принимающая система не может скачать временный URL. Он увеличивает объём данных примерно на треть и быстро упирается в лимиты памяти и запроса, поэтому подходит для небольших файлов. Для многостраничных PDF надёжнее потоковая загрузка по URL и немедленное перемещение в собственное хранилище.

Имена файлов, сроки ссылок и постоянное хранение

Поле name задаёт имя результата, но его следует формировать безопасно. Удаляйте символы пути, управляющие знаки и слишком длинные фрагменты, добавляйте ожидаемое расширение и уникальный идентификатор. Название счёта, извлечённое OCR, может содержать косую черту или двоеточие, которые недопустимы в некоторых файловых системах.

Параметр expiration определяет срок действия выходной ссылки в пределах возможностей плана. Малый срок уменьшает окно доступа, но требует немедленного скачивания. Большой срок не превращает временное хранилище в постоянное. Надёжный процесс загружает результат в S3, Drive или внутреннее хранилище сразу после success и сохраняет уже постоянный идентификатор.

В ответах новых методов может присутствовать outputLinkValidTill. Это точнее, чем предполагать фиксированный час. Получатель должен учитывать время сервера и не откладывать скачивание до последней минуты. Если следующий шаг выполняется в очереди, срок ссылки сравнивают с ожидаемой задержкой; при риске истечения результат копируют раньше.

Для повторной обработки храните хеш исходного файла. Если тот же документ поступил снова, система может найти готовый результат или осознанно запустить новую версию процесса. Сравнивать только имя опасно: разные документы часто называются scan.pdf, invoice.pdf или document.pdf.

Региональные форматы чисел, дат и валют

Извлечённое значение является текстом, пока система не проверила формат. Запись 1 234,56 в русской локали и 1,234.56 в английской обозначают одну сумму, но простая замена знаков может исказить 1.234.567,89. Правило разбора должно учитывать язык документа, валюту и расположение разделителей.

Даты 03/04/2026 неоднозначны: это 3 апреля или 4 марта. Если документ не содержит названия месяца, формат определяют по стране поставщика, соседним датам и бизнес-контексту. Сохраняйте исходную строку вместе с нормализованным значением, чтобы спорный результат можно было проверить.

Валютный знак не всегда однозначен. Символ $ используется несколькими валютами, а код может находиться в другом месте страницы. Для автоматической проводки требуйте ISO-код, реквизиты контрагента или дополнительное правило. Не подставляйте валюту по умолчанию только потому, что OCR не распознал знак.

Числа в таблицах нужно очищать от неразрывных пробелов, скобок отрицательных значений и знаков процентов. После преобразования сумма строк, налог и итог должны сходиться в пределах заданного округления. Несоответствие является сигналом ручной проверки, а не поводом автоматически исправить одну цифру.

Работа с повреждёнными и нестандартными PDF

Код 442 означает повреждённый документ или неверный тип. Сначала убедитесь, что файл открывается обычным просмотрщиком и начинается с сигнатуры PDF, а не является HTML-страницей ошибки с расширением .pdf. Затем попробуйте пересохранить документ доверенным инструментом, если у вас есть право изменять его.

Некоторые PDF открываются визуально, но содержат повреждённую таблицу перекрёстных ссылок, ошибочные объекты или нестандартное шифрование. Разные методы могут реагировать по-разному: рендеринг страницы сработает, а извлечение текста — нет. Диагностика должна отдельно проверять информацию о документе, вывод изображения и текст.

PDF-портфели, вложения, формы XFA, слои и цифровые подписи требуют особой осторожности. Конвертация в изображение сохранит вид страницы, но потеряет интерактивность. Уплощение формы сделает поля обычным содержимым. Любое изменение подписанного документа может нарушить проверку подписи. Перед массовой операцией определите, какие свойства нужно сохранить.

Если исходник невозможно обработать, не заменяйте его пустым PDF и не продолжайте цепочку как успешную. Сохраните файл, код ошибки, сообщение и технический идентификатор, затем направьте в очередь исключений. Следующие системы должны видеть статус failure, а не отсутствие данных.

Ограничение частоты и управление очередью

Код 429 показывает, что запросов слишком много за короткий период. Правильная реакция — экспоненциальная задержка с небольшим случайным отклонением, а не немедленный повтор всеми работниками. Централизованная очередь позволяет ограничить параллелизм и распределить задачи равномерно.

Для разных операций полезны разные очереди. Быстрое получение PDF Info не должно ждать за тяжёлым OCR на сотнях страниц, а фоновые job/check не должны занимать все рабочие потоки. Приоритет можно задавать по сроку, размеру и типу документа.

Очередь хранит идентификатор исходника, выбранный метод, число попыток и следующий допустимый запуск. После постоянной ошибки задача переводится в исключения. Бесконечный повтор повреждённого файла расходует кредиты и скрывает реальную проблему.

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

Наблюдаемость и технический журнал

Для каждой операции сохраняйте собственный requestId, endpoint, время начала и завершения, jobId, PageCount, credits, remainingCredits, HTTP-код и итоговый статус. Эти данные позволяют отличить медленную обработку от зависшего workflow и посчитать фактическую стоимость по типам документов.

Полное тело запроса нельзя бездумно писать в журнал: оно может содержать API-ключ, пароль, персональные данные и подписанные URL. Записывайте безопасный набор параметров, маскируйте секреты, а исходный JSON храните только в защищённом режиме отладки с ограниченным сроком.

Метрики полезно группировать по конечной точке, поставщику и шаблону. Рост ошибок одного Template ID указывает на изменение формы документа. Рост времени OCR может означать увеличение размера сканов. Увеличение расхода при прежнем объёме показывает лишние повторы или переход на более дорогой метод.

API Logs в кабинете помогают проверить отдельные вызовы, но производственная система должна иметь собственную трассировку. Она связывает загрузку, обработку, webhook, сохранение и передачу данных в одну цепочку, даже если каждый этап выполняется разной платформой.

Изменение шаблонов без остановки процесса

Поставщик может передвинуть номер счёта, переименовать заголовок или добавить новую колонку. Старый шаблон начнёт возвращать пустые или неверные значения. Поэтому важные поля должны иметь проверку обязательности и формата, а шаблон — контрольный набор документов.

Не редактируйте рабочий шаблон без возможности отката. Создайте копию, внесите изменения, прогоните исторические и новые образцы, сравните JSON, затем переключите поток на новый Template ID. Старый идентификатор сохраните на период наблюдения.

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

При миграции записывайте, каким Template ID получен каждый результат. Если позже обнаружится ошибка, можно найти затронутые документы и повторить только их, а не всю историю.

Проверка производительности на реальной партии

Тест одного файла не показывает поведение на потоке. Подготовьте партию с распределением размеров и страниц, близким к реальному, и измерьте медианное и максимальное время, процент ошибок, расход кредитов и объём результата. Отдельно учитывайте загрузку, ожидание фоновой задачи и скачивание.

Большой PDF может обрабатываться дольше, чем несколько небольших файлов с тем же общим числом страниц. Решение о предварительном разделении зависит от метода и структуры. Разделение добавляет вызовы, но позволяет повторить только неудачную часть и параллельно обрабатывать независимые документы.

Параллелизм повышают постепенно. Начните с одного работника, затем увеличивайте число до появления 429, роста ошибок или ухудшения времени. Зафиксируйте безопасный предел ниже наблюдаемой границы. Внешние хранилища также имеют лимиты, поэтому узким местом может быть не PDF.co.

Результат нагрузочного теста должен включать план деградации: что происходит при нехватке кредитов, недоступности API, истечении ссылок и задержке webhook. Очередь сохраняет задания, пользователь получает понятный статус, а повтор начинается после восстановления без дублирования документов.

Сравнение PDF.co с аналогами

Программа	Лучше подходит для	Главное ограничение
PDF.co	API-автоматизации, OCR и структурированного извлечения	Нужны API-ключ и кредиты
PDF Commander	Ручного редактирования PDF в понятном русском интерфейсе	Нет облачного API-конвейера
Smallpdf	Быстрых разовых операций с файлами в браузере	Расширенные возможности зависят от плана
iLovePDF	Слияния, разделения, сжатия и массовых конвертаций	Автоматизация вынесена в отдельный API
Adobe Acrobat online	Редактирования, подписания и совместной работы в экосистеме Adobe	Многие функции требуют подписки

PDF.co выбирают, когда документ является частью автоматического процесса и результат нужен программе в виде данных или файла. PDF Commander удобнее для человека, который хочет визуально исправить текст, страницу или подпись без построения запроса. Smallpdf и iLovePDF подходят для эпизодических конвертаций и операций с несколькими файлами. Adobe Acrobat online логичен для команд, уже использующих инструменты Adobe и электронные подписи.

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

Практические сценарии

Счета из электронной почты в таблицу

Процесс начинается с получения EML или вложения, затем документ классифицируется. Счета известных поставщиков отправляются в соответствующий шаблон Document Parser, остальные — в AI Invoice Parser. Полученные номер, дата, валюта, налог и итог проходят арифметическую проверку. После успешной проверки строки записываются в базу, а исходный PDF и JSON сохраняются под общим идентификатором.

Поисковое хранилище сканов

Скан загружается временно, страницы автоматически поворачиваются, затем Make Text Searchable добавляет OCR-слой с нужным языком. Результат копируется в постоянное хранилище, а извлечённый текст отправляется в индекс. Контроль ищет несколько слов и сравнивает PageCount. Если OCR не прошёл, исходник сохраняется, а документ попадает в очередь повторной обработки с другим разрешением.

Автоматическое заполнение формы

PDF Inspector используется один раз для получения имён полей. Данные клиента сопоставляются с fieldName, отправляются в PDF Add, после чего форма уплощается. Итог проверяется по списку обязательных полей и сохраняется. Подпись добавляется как изображение только после подтверждения, а координаты берутся из шаблона, а не рассчитываются на глаз при каждом запуске.

Разделение пакета по штрихкодам

Многостраничный скан поступает в Split by Barcode. Каждая часть получает техническое имя и проходит Barcode Reader для извлечения идентификатора. Если код не найден, файл не теряется, а помещается в папку исключений. Сумма страниц всех частей сравнивается с исходным документом, затем файлы переименовываются и загружаются в карточки клиентов.

Частые практические вопросы

Почему ссылка на файл работает в браузере, но не в PDF.co?

Браузер может использовать cookies, сохранённый вход или JavaScript, а сервер PDF.co обращается к адресу без вашей сессии. Нужна прямая ссылка, доступная без интерактивной авторизации. Загрузите файл в Files или получите presigned URL.

Почему первая страница не обрабатывается при значении 1?

Во многих параметрах API страницы индексируются с нуля. Первая страница имеет индекс 0, вторая — 1. Проверяйте описание конкретной конечной точки и тестируйте диапазон на коротком PDF.

Почему OCR вернул странные символы?

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

Почему результат перестал скачиваться через некоторое время?

Выходные URL временные. Срок зависит от параметра expiration и плана. Скачивайте результат сразу и переносите его в собственное хранилище.

Почему заполненное поле осталось пустым?

Сверьте точное имя через PDF Inspector, индекс страницы, тип поля и допустимое значение. Для флажка обычно требуется true, для списка — один из вариантов формы. После заполнения откройте результат в другом просмотрщике для проверки совместимости.

Когда нужен async=true?

Он нужен для крупных файлов, OCR, сложных конвертаций и процессов, которые могут длиться больше синхронного тайм-аута. После запуска сохраните jobId, проверяйте статус с интервалом или используйте webhook.

Как построить устойчивый процесс

Сначала сформулируйте один измеримый результат: текст, таблицу, заполненный PDF, изображение или набор частей. Затем выберите минимальную конечную точку, которая его создаёт, и проверьте запрос в API Tester. Не начинайте с длинной цепочки, пока каждый шаг не работает отдельно.

После успешного теста добавьте контроль входа: тип файла, размер, PageCount, пароль и доступность URL. Затем настройте параметры страниц, языка и профиля. Выход проверяйте по структуре и бизнес-правилам, сохраняйте в постоянное хранилище и только после этого передавайте дальше.

Для повторяющихся документов используйте шаблоны и идентификаторы, для неоднородных — классификацию и AI-парсер, для долгих задач — асинхронный режим, для больших результатов — ссылки вместо inline. Ошибки разделяйте на временные и постоянные, ограничивайте повторные попытки и сохраняйте исходник для диагностики.

PDF.co даёт наибольшую пользу, когда запрос описан как воспроизводимая операция с проверяемым результатом. Координаты, имена полей, шаблоны, коды ответов и лимиты делают процесс формальным: его можно протестировать, измерить по кредитам, повторить на новой партии и безопасно остановить при исключении. Такой подход превращает обработку PDF из ручной последовательности действий в управляемый конвейер без потери контроля над документами.