Справочник по REST API Connect

Краткий обзор

NextPDF Connect предоставляет реестр инструментов по HTTP через транспорт REST, описанный контрактом OpenAPI 3.1. Эта страница — справочник по этому интерфейсу: базовый URL, способ аутентификации, группы операций и модель ошибок. Полная машиночитаемая спецификация опубликована, поэтому вы можете загрузить её в интерактивный обозреватель, генератор клиентов или клиент для отправки запросов без ручного копирования.

Транспортно-независимый каталог инструментов (те же операции через Model Context Protocol, gRPC и REST) см. в разделе Справочник по Connect API. О конвейере RoadRunner, развёртывании и настройке аутентификации см. в разделе Руководство по транспорту REST.

Базовый URL и аутентификация

Транспорт REST слушает хост и порт, заданные для вашего развёртывания. При локальном запуске это http://localhost:8080; в рабочей среде — адрес сервиса перед пулом рабочих процессов.

Аутентификация выполняется с помощью bearer-токена. Передавайте ключ API в заголовке Authorization в каждом запросе к маршруту, доступ к которому зависит от тарифа:

curl --request POST \
  --url http://localhost:8080/api/v1/render \
  --header "Authorization: Bearer $NEXTPDF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"operations":[{"op":"add_text","text":"Hello from NextPDF Connect"}]}'

Пробы доступности и готовности не изменяют состояние и не требуют токена.

Операции

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

Работоспособность и жизненный цикл

Метод	Путь	Назначение
GET	/healthz	Проба доступности. Без аутентификации.
GET	/readyz	Проба готовности (зависимости и пул рабочих процессов готовы). Без аутентификации.
GET	/api/v1/capabilities	Инструменты и тарифы, фактически доступные в этом развёртывании. Запрашивайте её в первую очередь.

Отрисовка и документы

Метод	Путь	Назначение
POST	/api/v1/render	Отрисовать документ по упорядоченному списку операций и вернуть PDF.
POST	/api/v1/extract-text	Извлечь текстовое содержимое из PDF.
POST	/api/v1/merge	Объединить несколько входных PDF в один документ.
POST	/api/v1/split	Разделить PDF на несколько документов.

Асинхронные задания

Метод	Путь	Назначение
POST	/api/v1/jobs	Запустить длительную операцию как задание.
GET	/api/v1/jobs/{id}	Опросить статус задания.
GET	/api/v1/jobs/{id}/result	Получить результат завершённого задания.

Сессии

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

Метод	Путь	Назначение
POST	/api/v1/sessions	Открыть сессию.
GET / DELETE	/api/v1/sessions/{sessionId}	Проверить или закрыть сессию.
POST	/api/v1/sessions/{sessionId}/pages	Добавить страницу.
POST	/api/v1/sessions/{sessionId}/text	Добавить текст.
POST	/api/v1/sessions/{sessionId}/images	Добавить изображение.
POST	/api/v1/sessions/{sessionId}/tables	Добавить таблицу.
POST	/api/v1/sessions/{sessionId}/html	Добавить отрисованный HTML.
POST	/api/v1/sessions/{sessionId}/font	Задать активный шрифт.
POST	/api/v1/sessions/{sessionId}/render	Отрисовать документ сессии.

Операции коммерческой редакции

Эти маршруты регистрируются, только если установлена соответствующая коммерческая редакция. Некоторые требуют подтверждения с участием человека (human-in-the-loop); см. уровни риска.

Метод	Путь	Назначение
POST	/api/v1/sign	Применить цифровую подпись.
POST	/api/v1/fill-form	Заполнить интерактивную форму.
POST	/api/v1/redact	Безвозвратно удалить содержимое.
POST	/api/v1/compare	Сравнить два PDF-документа.
POST	/api/v1/check-accessibility	Выполнить структурную проверку доступности.
POST	/api/v1/optimize	Оптимизировать и уменьшить размер документа.

Модель ошибок

Транспорт REST использует коды состояния HTTP в семантике RFC 9110: 2xx — успешный результат, 4xx — запрос, который вызывающая сторона должна исправить (400 — некорректное тело, 401 — отсутствующий или недействительный токен, 403 — отказ по тарифу или подтверждению, 404 — неизвестный маршрут или задание, 409 — конфликт идемпотентности, 422 — корректно сформированный запрос, который движок не может обработать), а 5xx — сбой на стороне сервера. Ответ 401 включает заголовок WWW-Authenticate.

Тела ошибок — это документы application/problem+json согласно RFC 9457 (Problem Details for HTTP APIs): стабильный type, краткий title, числовой status и понятный человеку detail. Сопоставляйте по type, а не по строке detail. Нормативные определения см. также в RFC 9110 (HTTP Semantics) и RFC 9457.

Передавайте заголовок Idempotency-Key в запросах, изменяющих состояние, чтобы повторно отправленный запрос обрабатывался один раз.

Машиночитаемая спецификация

Полный контракт опубликован в виде статического документа OpenAPI 3.1:

https://nextpdf.dev/docs/openapi/nextpdf-connect.yaml

Используйте его как единый источник истины для интерфейса REST:

1. Откройте интерактивный обозреватель API — браузерный справочник Scalar, который можно разместить у себя и который сгенерирован из этого контракта, — чтобы читать и пробовать каждую операцию с её схемами запроса и ответа.
2. Импортируйте контракт в клиент для отправки запросов, например Postman или Insomnia.
3. Сгенерируйте типизированный клиент для вашего языка с помощью генератора OpenAPI.

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

См. также

• Справочник по Connect API — полный каталог инструментов для MCP, REST и gRPC.
• Руководство по транспорту REST — конвейер RoadRunner, аутентификация по bearer-токену и маршрутизация по тарифам.
• Обзор NextPDF Connect — что представляет собой сервер и как его запустить.