Overview 1 Минимално време за четене

API на PaperOffice за разработчици: пълното ръководство

Къде се намира спецификацията

Спецификацията на крайните точки (endpoint) се генерира динамично от каталога на 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
  • Навык за агент (Agent skill): 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.

Без токен са достъпни само инфраструктурните крайни точки като спецификацията, проверката на здравето (health check) и теста за свързаност. Продуктова заявка без токен получава отговор HTTP 403 с кода TIER_RESTRICTED, а не HTTP 401.

Задачи: изчакване, поддържане на връзка (polling) и резултати

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

  • По подразбиране заявката задържа връзката за известно време. Ако задачата приключи навреме, получавате резултата директно. В противен случай получавате HTTP 202 с ID на задача и адрес за поддържане на връзка (poll address), а задачата продължава да работи.
  • HTTP 202 е успех, а не грешка. Извършвайте poll GET /job/get/{job_id} на всеки 5 до 10 секунди, докато статусът стане completed. Резултатът се намира в job_result.
  • С client_wait=false получавате ID на задачата веднага и започвате poll от самото начало.
  • Всички отговори са JSON. Клиентите трябва да четат стабилното поле code, а не локализираното текстово съобщение.

В приложението под Акаунт → 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. Заявките, които са отхвърлени поради невалидни входни данни, също се таксуват; тези, ограничени от честотата, не се таксуват.

Виждате извикванията с техните Credits под API и разработка → API използване: живият дневник показва всяка заявка, историята показва използването по дата, обработчик и действие. Когато Credits свършат, извикванията се отхвърлят до зареждането на баланса или до влизането в сила на автоматичното допълване. Ограниченията за честота зависят от вашия план; текущите граници и заглавките в отговорите са описани в документацията на API. Повече за Credits: Таксуване и Credits в PaperOffice AI.

MCP: свързване на AI асистенти

MCP свързва AI асистенти като 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 файла. Те се генерират в реално време.
  • Какъв токен трябва да използва сървърът ми? Системен ключ, никога в браузър. За браузър използвайте публикуем ключ с произход и бюджет.
  • Дали HTTP 202 е грешка? Не. Работата все още върви; правете заявки за резултата.
  • Дали по-бързите стартови ленти струват повече? Да. Най-добрите усилия нямат допълнително таксуване; текущите цени са в списъка с цени на API.
  • Таксуват ли се отхвърлените повиквания? Повикванията, отхвърлени поради невалидни входни данни, се таксуват; тези, ограничени от честота, не се таксуват.