OverviewОбновлено 27 октября 2026 г. 1 мин. чтения

API PaperOffice для разработчиков: полное руководство

Где находится спецификация

Спецификация эндпоинтов генерируется в реальном времени из каталога API. Используйте эти файлы вместо копирования списков эндпоинтов из статей:

Компактный индекс для AI-клиентов: https://api.paperoffice.ai/latest/docs/llms.txt
Полная справка: https://api.paperoffice.ai/latest/docs/llms-full.txt
OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
Навык агента: https://api.paperoffice.ai/latest/docs/skill.md
Коллекция Postman: https://api.paperoffice.ai/latest/docs/postman

Маршруты документации являются общедоступными и не требуют токена. Импортируйте URL Postman в Postman, VS Code или Bruno и обновляйте его при изменении релиза документации. Базовый адрес производства: https://api.paperoffice.ai/latest; используйте /dev только для разработки.

Быстрый старт с AI-ассистентом по кодированию: передайте ему адрес файла llms-full.txt и опишите необходимую функцию, например, функцию, которая отправляет изображение и возвращает распознанный текст.

Аутентификация и типы токенов

Большинство эндпоинтов продукта требуют bearer-токен в заголовке Authorization. Вы создаете токены в приложении PaperOffice в разделе Аккаунт → API.

Системный ключ (po_sk_): интеграция сервер-сервер с полным доступом к API. Никогда не используйте его в браузере.
Токен пользователя (po_ut_): область действия одного пользователя, например для MCP. Права следуют за пользователем и лицензией.
Групповой токен (po_gt_): наследует права и белый список рабочих пространств группы пользователей.
Публикуемый ключ (po_pk_): для использования в браузере. Каждый запрос требует источника (origin), указанного владельцем ключа; общий лимит бюджета ключа ограничивает потребление; удаление, администрирование аккаунта, управление ключами и изменения платежей остаются заблокированными. Использование для MCP запрещено.

Без токена доступны только инфраструктурные эндпоинты, такие как спецификация, проверка состояния и тест подключения. Запрос к продукту без токена получает ответ HTTP 403 с кодом TIER_RESTRICTED, а не HTTP 401.

Задания: ожидание, опрос и результаты

Обработка выполняется в виде заданий. Пути заданий используют шаблон handler___command с тремя подчеркиваниями, например POST /job/add/paperoffice_aiocr___generate для распознавания текста. Точечная нотация отклоняется с ошибкой JOB_CONFIG_INVALID.

По умолчанию запрос удерживает соединение в течение некоторого времени. Если задание завершается вовремя, вы получаете результат напрямую. В противном случае вы получаете HTTP 202 с идентификатором задания и адресом для опроса, и задание продолжает выполняться.
HTTP 202 — это успех, а не ошибка. Опросите GET /job/get/{job_id} каждые 5–10 секунд до тех пор, пока статус не станет completed. Результат затем находится в job_result.
С client_wait=false вы получаете идентификатор задания немедленно и начинаете опрос с самого начала.
Все ответы имеют формат JSON. Клиенты должны читать стабильное поле кода, а не локализованный текст сообщения.

В приложении в разделе Аккаунт → API → Очередь заданий вы видите API-задания в очереди, выполняющиеся и завершенные. Полный список кодов ошибок находится в спецификации; типичные случаи: отсутствующие или недействительные параметры (400), отсутствующий или недействительный токен (401), недостаточно Credits (402), запрещенное действие (403) и слишком много запросов (429, уважайте Retry-After).

Начальный SLA: когда начинается задание

Необязательное поле processing_lane управляет тем, когда задание начинается в очереди, а не когда оно завершается. client_wait управляет тем, ожидает ли соединение результата; эти два поля независимы.

Без processing_lane применяется значение по умолчанию рабочего пространства, иначе — best effort. Каждый план включает best effort без дополнительной платы. Более быстрые полосы запуска являются опциональными и стоят дороже. Текущие полосы и их цены доступны в реальном времени через список цен API; подробности находятся в документации API.

Вебхуки

Эндпоинты вебхуков получают события заданий и аккаунтов, например job.completed, job.failed, job.progress и события для документов, рабочих пространств и задач. Уведомления об аккаунтах, такие как пустой кошелек или отозванный ключ, не являются событиями вебхуков.

Пейлоды подписываются с помощью HMAC-SHA256 в заголовке X-Paperoffice-Signature. Вычислите подпись для необработанного тела запроса, используя свой секретный ключ вебхука, и отклоните запрос, если он не совпадает.
Вебхуки регистрируются, просматриваются, обновляются, тестируются и удаляются через API.

Биллинг и использование

Вызовы API потребляют Credits из общего пула организации, того же пула, что и приложение. Некоторые запросы статуса и здоровья не тарифицируются; подробности приведены в документации API. Вызовы, отклоненные из-за недействительных входных данных, также тарифицируются; вызовы, ограниченные частотой запросов (rate-limited), не тарифицируются.

Вы видите вызовы с их Credits в разделе API и разработка → Использование API: журнал в реальном времени показывает каждый запрос, история показывает использование по дате, обработчику и действию. Когда Credits исчерпаны, вызовы отклоняются до пополнения баланса или срабатывания автопополнения. Лимиты частоты запросов зависят от вашего тарифного плана; текущие лимиты и заголовки ответов описаны в документации API. Подробнее о Credits: Биллинг и Credits в PaperOffice AI.

MCP: подключение ИИ-ассистентов

MCP подключает ИИ-ассистентов, таких как Claude, ChatGPT, Grok и Cursor, напрямую к PaperOffice. Аутентификация осуществляется по OAuth 2.1 или с помощью токена пользователя или группы; системные ключи и публикуемые ключи для MCP заблокированы. Хост производства: https://mcp.paperoffice.ai, с профилями, такими как /claude, /chatgpt, /grok, /cursor и /dms. Настройка, разрешения и поток данных: Использование PaperOffice с Claude, ChatGPT, Grok и Cursor.

Часто задаваемые вопросы

Где найти все конечные точки? В файлах llms.txt, llms-full.txt и OpenAPI. Они генерируются в реальном времени.
Какой токен должен использовать мой сервер? Системный ключ, никогда не в браузере. Для браузера используйте публикуемый ключ с указанием источника (origin) и бюджета.
Является ли HTTP 202 ошибкой? Нет. Задача все еще выполняется; опрашивайте результат.
Стоят ли более быстрые полосы запуска дороже? Да. Режим Best effort не имеет дополнительной наценки; текущие цены указаны в прайс-листе API.
Тарифицируются ли отклоненные вызовы? Вызовы, отклоненные из-за недействительных входных данных, тарифицируются; вызовы, ограниченные частотой запросов (rate-limited), не тарифицируются.