Overview 5 Min. vreme čitanja

API za PaperOffice za developere: kompletni vodič

Gde se nalazi specifikacija

Specifikacija endpointa se generiše u realnom vremenu iz kataloga API-ja. Koristite ove fajlove umesto kopiranja lista endpointa iz članaka:

  • Kompaktan indeks za AI klijente: https://api.paperoffice.ai/latest/docs/llms.txt
  • Puna referenca: https://api.paperoffice.ai/latest/docs/llms-full.txt
  • OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
  • Veština agenta: https://api.paperoffice.ai/latest/docs/skill.md
  • Postman kolekcija: https://api.paperoffice.ai/latest/docs/postman

Rute dokumentacije su javne i ne zahtevaju token. Uvezite URL Postmana u Postman, VS Code ili Bruno i ponovo ga preuzmite kada se promeni izdanje dokumentacije. Osnovna adresa produkcije je https://api.paperoffice.ai/latest; koristite /dev samo za razvoj.

Brzi start sa AI asistentom za kodiranje: dajte mu adresu llms-full.txt i opišite funkciju koja vam je potrebna, na primer funkciju koja šalje sliku i vraća prepoznat tekst.

Autentifikacija i vrste tokena

Većina produktnih endpointa zahteva bearer token u zaglavlju Authorization. Tokenove kreirate u aplikaciji PaperOffice pod Račun → API.

  • Sistemski ključ (po_sk_): server-to-server integracija sa punim pristupom API-ju. Nikada ga ne koristite u pregledaču (browseru).
  • Korisnički token (po_ut_): opseg jednog korisnika, na primer za MCP. Prava prate korisnika i licencu.
  • Grupni token (po_gt_): nasleđuje prava i belu listu radnih prostora grupe korisnika.
  • Objavljivi ključ (po_pk_): za korišćenje u pregledaču. Svaki zahtev mora imati poreklo koje je vlasnik ključa uneo, budžet životnog veka ograničava potrošnju, a brisanje, administracija naloga, upravljanje ključevima i promene plaćanja ostaju blokirane. Nije dozvoljeno za MCP.

Bez tokena dostupni su samo infrastrukturni endpointi kao što su specifikacija, provera zdravlja i test povezanosti. Zahtev za proizvod bez tokena odgovara se sa HTTP 403 i kodom TIER_RESTRICTED, a ne sa HTTP 401.

Poslovi: čekanje, proveravanje (polling) i rezultati

Procesiranje se odvija kao poslovi. Putanje poslova koriste obrazac handler___command sa tri donje crte, na primer POST /job/add/paperoffice_aiocr___generate za prepoznavanje teksta. Tačkasta notacija je odbijena sa JOB_CONFIG_INVALID.

  • Podrazumevano, zahtev zadržava vezu neko vreme. Ako se posao završi na vreme, dobijate rezultat direktno. U suprotnom dobijate HTTP 202 sa ID-jem posla i adresom za proveravanje (poll), a posao nastavlja da radi.
  • HTTP 202 je uspeh, a ne greška. Proveravajte GET /job/get/{job_id} svakih 5 do 10 sekundi dok status ne bude completed. Rezultat se tada nalazi u job_result.
  • Sa client_wait=false, dobijate ID posla odmah i proveravate od početka.
  • Svi odgovori su JSON. Klijenti treba da čitaju stabilno polje koda, a ne lokalizovani tekst poruke.

Prikazujete poslove na čekanju, u toku i završene API poslove u aplikaciji pod Račun → API → Red poslova. Potpuna lista kodova grešaka je u specifikaciji; tipični slučajevi su nedostajući ili nevalidni parametri (400), nedostajući ili nevalidan token (401), nedovoljno Credits (402), zabranjena radnja (403) i previše zahteva (429, poštujte Retry-After).

Početni SLA: kada posao počinje

Opciono polje processing_lane kontroliše kada posao počinje u redu, a ne kada se završi. client_wait kontroliše da li veza čeka rezultat; ova dva polja su nezavisna.

Bez processing_lane, podrazumevana vrednost radnog prostora se primenjuje, inače best effort. Svaki plan uključuje best effort bez doplate. Brže trake za početak su opcione i koštaju više. Trenutne trake i njihove cene dostupne su u realnom vremenu kroz listu cena API-ja; detalji su u dokumentaciji API-ja.

Webhookovi

Webhook endpointi primaju događaje poslova i naloga, na primer job.completed, job.failed, job.progress i događaje za dokumente, radne prostore i zadatke. Obaveštenja o nalogu kao što je prazan novčanik ili opozvani ključ nisu webhook događaji.

  • Payloads su potpisani HMAC-SHA256 u zaglavlju X-Paperoffice-Signature. Izračunajte potpis preko sirovog tela zahteva sa svojim tajnim ključem za webhook i odbacite zahtev ako se ne poklapa.
  • Webhookovi se registruju, prikazuju, ažuriraju, testiraju i brišu putem API-ja.

Naplaćivanje i korišćenje

Pozivi API-ja troše Credits iz zajedničkog fonda organizacije, isti fond kao i aplikacija. Neki upiti za status i proveru stanja sistema nisu naplaćeni; detalji su u dokumentaciji API-ja. Pozivi koji su odbijeni zbog nevalidnog unosa se takođe naplaćuju; pozivi ograničeni brzinom se ne naplaćuju.

Pozive sa njihovim Credits vidite pod API i programeri → API korišćenje: dnevnik uživo prikazuje svaki zahtev, istorija prikazuje korišćenje po datumu, handleru i akciji. Kada se Credits potroše, pozivi se odbijaju dok se stanje ne dopuni ili ne stupi na snagu automatsko dopunjavanje. Granice brzine zavise od vašeg plana; trenutne granice i zaglavlja odgovora su opisane u dokumentaciji API-ja. Više o Credits: Naplaćivanje i Credits u PaperOffice AI.

MCP: povezivanje AI asistenta

MCP povezuje AI asistente kao što su Claude, ChatGPT, Grok i Cursor direktno sa PaperOffice. Autentifikacija je OAuth 2.1 ili token korisnika ili grupe; sistemski ključevi i javni ključevi su blokirani za MCP. Proizvodni host je https://mcp.paperoffice.ai, sa profilima kao što su /claude, /chatgpt, /grok, /cursor i /dms. Postavke, dozvole i tok podataka: Korišćenje PaperOffice sa Claude, ChatGPT, Grok i Cursor.

Često postavljana pitanja

  • Gde mogu pronaći sve krajnje tačke? U llms.txt, llms-full.txt i OpenAPI fajlu. Oni se generišu u realnom vremenu.
  • Koji token treba da koristi moj server? Sistemski ključ, nikada u pregledaču. Za pregledač koristite javni ključ sa poreklom i budžetom.
  • Da li je HTTP 202 greška? Ne. Posao je još uvek u toku; proveravajte rezultat.
  • Da li brže trake starta koštaju više? Da. Najbolji napor nema doplatu; trenutne cene su u cenovniku API-ja.
  • Da li se odbijeni pozivi naplaćuju? Pozivi odbijeni zbog nevalidnog unosa se naplaćuju; pozivi ograničeni brzinom se ne naplaćuju.