PaperOffice API kehittäjille: täydellinen opas

Missä specifikaatio sijaitsee

Päätepisteen specifikaatio generoidaan live-tilassa API-katalogista. Käytä näitä tiedostoja päätepisteiden listojen kopioimisen sijaan artikkeleista:

• Tiivis indeksi tekoälyasiakkaille: https://api.paperoffice.ai/latest/docs/llms.txt
• Täysi viite: https://api.paperoffice.ai/latest/docs/llms-full.txt
• OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
• Agentin taitopaketti: https://api.paperoffice.ai/latest/docs/skill.md
• Postman-kokoelma: https://api.paperoffice.ai/latest/docs/postman

Dokumentointireitit ovat julkisia eivätkä vaadi tokenia. Tuo Postman URL Postmaniin, VS Codeen tai Brunoon ja lataa se uudelleen, kun dokumentaation julkaisu muuttuu. Tuotannon periosoite on https://api.paperoffice.ai/latest; käytä /dev vain kehitykseen.

Pika-aloitus tekoälykoodausavustajan kanssa: anna sille osoite tiedostolle llms-full.txt ja kuvaa tarvittava funktio, esimerkiksi funktio, joka lähettää kuvan ja palauttaa tunnistetun tekstin.

Autentikointi ja token-tyypit

Useimmat tuotepäätepisteet vaativat bearer-tokenin Authorization-otsakkeessa. Tokenit luodaan PaperOffice -sovelluksessa kohdasta Tili → API.

• Järjestelmän avain (po_sk_): palvelimelta palvelimelle -integraatio täydellä API-käytöllä. Älä koskaan käytä sitä selaimessa.
• Käyttäjän token (po_ut_): yhden käyttäjän laajuus, esimerkiksi MCP:tä varten. Oikeudet seuraavat käyttäjää ja lisenssiä.
• Ryhmän token (po_gt_): perii käyttäjäryhmän oikeudet ja työtilan valkolistan.
• Julkaistava avain (po_pk_): käytettäväksi selaimessa. Jokaisessa pyynnössä on oltava alkuperä, jonka avaimen omistaja on syöttänyt, elinikäinen budjetti rajoittaa kulutusta ja poisto, tilinhallinta, avainten hallinta ja maksutapamuutokset pysyvät estettyinä. Sitä ei sallita MCP:ssä.

Ilman tokenia vain infrastruktuuripäätepisteet kuten specifikaatio, terveydentilan tarkistus ja yhteystestaus ovat saavutettavissa. Tuotepyyntö ilman tokenia palautetaan HTTP 403 -virheellä ja koodilla TIER_RESTRICTED, ei HTTP 401.

Työt: odotus, polling ja tulokset

Käsittelu suoritetaan töinä. Työpolut käyttävät kaavaa handler___command kolmella alaviivalla, esimerkiksi POST /job/add/paperoffice_aiocr___generate tekstin tunnistusta varten. Pistenotaatio hylätään virheellä JOB_CONFIG_INVALID.

• Oletuksena pyyntö pitää yhteyden auki hetken. Jos työ valmistuu ajassa, tulos saadaan suoraan. Muuten saat HTTP 202 -vastauksen, jossa on työtunniste ja polling-osoite, ja työ jatkaa suoritusta.
• HTTP 202 on menestys, ei virhe. Pollaa GET /job/get/{job_id} joka 5–10 sekunti kunnes tila on completed. Tulos löytyy kentästä job_result.
• Arvolla client_wait=false työtunniste saadaan välittömästi ja polling aloitetaan alusta asti.
• Kaikki vastaukset ovat JSON-muodossa. Asiakkaiden tulee lukea vakaa koodikenttä, ei lokalisoitu viestiteksti.

Jonossa olevat, suoritettavat ja valmiit API-työt näkyvät sovelluksessa kohdassa Tili → API → Työjono. Virhekoodien täysi lista on specifikaatiossa; tyypillisiä tapauksia ovat puuttuvat tai virheelliset parametrit (400), puuttuva tai virheellinen token (401), riittämättömät Credits (402), kielletty toiminto (403) ja liian monta pyyntöä (429, nouda Retry-After).

Aloitus SLA: milloin työ aloitetaan

Valinnainen kenttä processing_lane ohjaa, milloin työ aloitetaan jonossa, ei milloin se valmistuu. client_wait ohjaa, odottaako yhteys tulosta; nämä kaksi kenttää ovat riippumattomia.

Ilman processing_lanea työtilan oletus pätee, muuten best effort. Jokainen suunnitelma sisältää best effortin ilman lisämaksua. Nopeammat aloitusvuorot ovat valinnaisia ja maksavat enemmän. Nykyiset vuorot ja niiden hinnat ovat saatavilla live-tilassa API-hintalistasta; yksityiskohdat löytyvät API-dokumentaatiossa.

Webhookit

Webhook-päätepisteet vastaanottavat työ- ja tilitapahtumia, esimerkiksi job.completed, job.failed, job.progress sekä tapahtumia asiakirjoille, työtiloille ja tehtäville. Tili-ilmoitukset kuten tyhjä lompakko tai peruutettu avain eivät ole webhook-tapahtumia.

• Payloadit allekirjoitetaan HMAC-SHA256:lla X-Paperoffice-Signature -otsakkeessa. Laske allekirjoitus pyynnön raakakehikon avulla webhook-salaisuudella ja hylkää pyyntö, jos se ei täsmää.
• Webhookit rekisteröidään, listataan, päivitetään, testataan ja poistetaan API:n kautta.

Laskutus ja käyttö

API-kutsut kuluttavat Credits:n organisaation jaettua poolia, samaa poolia kuin sovellus. Jotkin tila- ja terveyskyselyt eivät aiheuta kustannuksia; tarkemmat tiedot ovat API-dokumentaatiossa. Virheellisen syötteen vuoksi hylätyt kutsut laskutetaan myös; nopeusrajoitusten vuoksi hylätyt kutsut eivät.

Kutsut ja niiden Credits-kulutus näkyvät kohdassa API ja kehittäjä → API-käyttö: live-loki näyttää jokaisen pyynnön, historia näyttää käytön päivämäärän, käsittelijän ja toiminnon mukaan. Kun Credits:t loppuvat, kutsut hylätään, kunnes saldo täytetään tai automaattinen uudelleenlataus astuu voimaan. Nopeusrajoitukset riippuvat suunnitelmasta; nykyiset rajoitukset ja vastausotsakkeet on kuvattu API-dokumentaatiossa. Lisää aiheesta Credits: Laskutus ja Credits PaperOffice AI:ssa.

MCP: yhdistä tekoälyavustajat

MCP yhdistää tekoälyavustajat kuten Claude, ChatGPT, Grok ja Cursor suoraan PaperOffice:hen. Todennus on OAuth 2.1 tai käyttäjä- tai ryhmätoken; järjestelmän avaimet ja julkaistavat avaimet on estetty MCP:ltä. Tuotannon isäntä on https://mcp.paperoffice.ai, profiileina esimerkiksi /claude, /chatgpt, /grok, /cursor ja /dms. Määritys, käyttöoikeudet ja datavirta: PaperOffice:n käyttäminen Claude-, ChatGPT-, Grok- ja Cursor-avustajien kanssa.

Usein kysytyt kysymykset

• Mistä löydän kaikki päätepisteet? llms.txt, llms-full.txt ja OpenAPI-tiedostosta. Ne generoidaan reaaliajassa.
• Mikä token palvelimen tulisi käyttää? Järjestelmän avain, ei koskaan selaimessa. Selaimelle käytä julkaistavaa avainta, jolla on alkuperä ja budjetti.
• Onko HTTP 202 virhe? Ei. Työ on vielä käynnissä; tarkista tulos kysymällä toistuvasti.
• Maksavatko nopeammat aloituskaistat enemmän? Kyllä. Best effort -toiminnolle ei peritä lisämaksua; nykyiset hinnat ovat API-hintalistassa.
• Laskutetaanko hylätyt kutsut? Virheellisen syötteen vuoksi hylätyt kutsut laskutetaan; nopeusrajoitusten vuoksi hylätyt kutsut eivät.