Overview 6 Min. čas na přečtení

API PaperOffice pro vývojáře: kompletní průvodce

Kde se specifikace nachází

Specifikace endpointů je generována živě z katalogu API. Používejte tyto soubory místo kopírování seznamů endpointů z článků:

  • Kompaktní index pro AI klienty: https://api.paperoffice.ai/latest/docs/llms.txt
  • Plný referenční přehled: https://api.paperoffice.ai/latest/docs/llms-full.txt
  • OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
  • Dovednost agenta: https://api.paperoffice.ai/latest/docs/skill.md
  • Kolekce Postman: https://api.paperoffice.ai/latest/docs/postman

Trasy dokumentace jsou veřejné a nevyžadují token. Naimportujte URL adresu Postman do aplikace Postman, VS Code nebo Bruno a znovu ji stáhněte při změně vydání dokumentace. Výchozí adresa produkčního prostředí je https://api.paperoffice.ai/latest; použijte /dev pouze pro vývoj.

Rychlý start s AI asistentem pro kódování: poskytněte mu adresu souboru llms-full.txt a popište funkci, kterou potřebujete, například funkci, která odešle obrázek a vrátí rozpoznaný text.

Ověřování a typy tokenů

Většina produktových endpointů vyžaduje bearer token v hlavičce Authorization. Tokeny vytváříte v aplikaci PaperOffice pod Účet → API.

  • Systémový klíč (po_sk_): integrace server-to-server s plným přístupem k API. Nikdy jej nepoužívejte v prohlížeči.
  • Uživatelský token (po_ut_): rozsah jednoho uživatele, například pro MCP. Práva vycházejí z uživatele a licence.
  • Skupinový token (po_gt_): dědí práva a bílý seznam pracovních prostorů uživatelské skupiny.
  • Veřejný klíč (po_pk_): určený pro použití v prohlížeči. Každý požadavek vyžaduje původ, který vlastník klíče zadal, rozpočet životnosti omezuje spotřebu a mazání, správa účtu, správa klíčů a změny plateb zůstávají blokovány. Pro MCP není povolen.

Bez tokenu jsou dostupné pouze infrastrukturní endpointy, jako je specifikace, kontrola stavu a test připojení. Produktový požadavek bez tokenu je odpovězen kódem HTTP 403 a kódem TIER_RESTRICTED, nikoliv HTTP 401.

Úlohy: čekání, dotazování a výsledky

Zpracování probíhá jako úlohy. Cesty k úlohám používají vzor handler___command se třemi podtržítky, například POST /job/add/paperoffice_aiocr___generate pro rozpoznávání textu. Tečková notace je zamítnuta s chybou JOB_CONFIG_INVALID.

  • Ve výchozím nastavení požadavek drží spojení po určitou dobu. Pokud úloha dokončí zpracování včas, získáte výsledek přímo. V opačném případě obdržíte HTTP 202 s ID úlohy a adresou pro dotazování a úloha pokračuje ve zpracování.
  • HTTP 202 je úspěch, nikoliv chyba. Dotazujte GET /job/get/{job_id} každých 5 až 10 sekund, dokud není stav dokončen. Výsledek se poté nachází v job_result.
  • S nastavením client_wait=false získáte ID úlohy okamžitě a dotazujete se od začátku.
  • Všechny odpovědi jsou ve formátu JSON. Klienti by měli číst stabilní pole kódu, nikoliv lokalizovaný text zprávy.

Uvidíte zařazené, běžící a dokončené API úlohy v aplikaci pod Účet → API → Fronta úloh. Plný seznam chybových kódů je ve specifikaci; typické případy jsou chybějící nebo neplatné parametry (400), chybějící nebo neplatný token (401), nedostatečné Credits (402), zakázaná akce (403) a příliš mnoho požadavků (429, respektujte Retry-After).

Počáteční SLA: kdy úloha začíná

Volitelné pole processing_lane řídí, kdy úloha začne ve frontě, nikoliv kdy skončí. client_wait řídí, zda spojení čeká na výsledek; obě pole jsou nezávislá.

Bez nastavení processing_lane se použije výchozí hodnota pracovního prostoru, jinak best effort. Každý plán zahrnuje best effort bez příplatku. Rychlejší startovací pásy jsou volitelné a stojí více. Aktuální pásy a jejich ceny jsou dostupné živě prostřednictvím ceníku API; podrobnosti naleznete v dokumentaci API.

Webhooky

Endpointy webhooků přijímají události úloh a účtů, například job.completed, job.failed, job.progress a události pro dokumenty, pracovní prostory a úkoly. Upozornění na účtech, jako je prázdná peněženka nebo odvolaný klíč, nejsou webhookovými událostmi.

  • Payloady jsou podepisovány pomocí HMAC-SHA256 v hlavičce X-Paperoffice-Signature. Vypočítejte podpis pro surové tělo požadavku pomocí vašeho tajného klíče webhooku a požadavek zamítněte, pokud se neshoduje.
  • Webhooky jsou registrovány, vypisovány, aktualizovány, testovány a odstraňovány prostřednictvím API.

Fakturace a využití

Volání API spotřebovávají Credits ze sdíleného fondu organizace, který je stejný jako fond aplikace. Některé dotazy na stav a zdraví nejsou účtovány; podrobnosti naleznete v dokumentaci API. Volání, která jsou zamítnuta kvůli neplatnému vstupu, jsou také účtována; volání omezená rychlostí (rate-limited) však ne.

Volání s jejich Credits vidíte pod API a vývojáři → Využití API: živý protokol zobrazuje každý požadavek, historie zobrazuje využití podle data, handleru a akce. Když se Credits vyčerpají, volání jsou zamítána, dokud není zůstatek doplněn nebo neplatí automatické dobíjení. Limity rychlosti závisí na vašem plánu; aktuální limity a odpovědní hlavičky jsou popsány v dokumentaci API. Více o Credits: Fakturace a Credits v PaperOffice AI.

MCP: připojení asistentů AI

MCP připojuje asistenty AI, jako jsou Claude, ChatGPT, Grok a Cursor, přímo k PaperOffice. Autentizace probíhá pomocí OAuth 2.1 nebo tokenu uživatele/skupiny; systémové klíče a publikovatelné klíče jsou pro MCP blokovány. Produkční hostitel je https://mcp.paperoffice.ai s profily, jako jsou /claude, /chatgpt, /grok, /cursor a /dms. Nastavení, oprávnění a tok dat: Použití PaperOffice s Claude, ChatGPT, Grok a Cursor.

Často kladené otázky

  • Kde najdu všechny koncové body? V souborech llms.txt, llms-full.txt a OpenAPI. Jsou generovány v reálném čase.
  • Jaký token by měl můj server používat? Systémový klíč, nikdy v prohlížeči. Pro prohlížeč použijte publikovatelný klíč s původem (origin) a rozpočtem.
  • Je HTTP 202 chybou? Ne. Úloha stále běží; dotazujte se na výsledek.
  • Stojí rychlejší startní pruhy více? Ano. Best effort nemá příplatek; aktuální ceny jsou v ceníku API.
  • Jsou zamítnutá volání účtována? Volání zamítnutá kvůli neplatnému vstupu jsou účtována; volání omezená rychlostí však ne.