Overview 5 Min. leestijd

De PaperOffice API voor ontwikkelaars: de complete gids

Waar de specificatie te vinden is

De endpoint-specificatie wordt live gegenereerd vanuit de API-catalogus. Gebruik deze bestanden in plaats van endpoint-lijsten uit artikelen te kopiëren:

  • Compact index voor AI-clients: https://api.paperoffice.ai/latest/docs/llms.txt
  • Volledige referentie: https://api.paperoffice.ai/latest/docs/llms-full.txt
  • OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
  • Agentvaardigheid: https://api.paperoffice.ai/latest/docs/skill.md
  • Postman-collectie: https://api.paperoffice.ai/latest/docs/postman

De documentatieroutes zijn publiek en vereisen geen token. Importeer de Postman-URL in Postman, VS Code of Bruno, en download deze opnieuw wanneer de documentatierelease verandert. Het productiebasisadres is https://api.paperoffice.ai/latest; gebruik /dev alleen voor ontwikkeling.

Een snelle start met een AI-codingassistant: geef deze het adres van llms-full.txt en beschrijf de functie die u nodig heeft, bijvoorbeeld een functie die een afbeelding verzendt en de herkende tekst retourneert.

Authenticatie en tokensoorten

De meeste productendpoints vereisen een bearer-token in de Authorization-header. U maakt tokens aan in de PaperOffice app onder Account → API.

  • Systeemkey (po_sk_): server-naar-serverintegratie met volledige API-toegang. Gebruik deze nooit in een browser.
  • Gebruikerstoken (po_ut_): de reikwijdte van één gebruiker, bijvoorbeeld voor MCP. Rechten volgen de gebruiker en de licentie.
  • Groepstoken (po_gt_): erft de rechten en de werkruimte-witlijst van een gebruikersgroep.
  • Publiceerbare key (po_pk_): voor gebruik in een browser. Elk verzoek vereist een oorsprong die de key-eigenaar heeft ingevoerd, een levensduurbudget beperkt het verbruik, en verwijderen, accountadministratie, keybeheer en betalingswijzigingen blijven geblokkeerd. Het is niet toegestaan voor MCP.

Zonder token zijn alleen infrastructuurendpoints zoals de specificatie, de healthcheck en de connectiviteitstest bereikbaar. Een productverzoek zonder token wordt beantwoord met HTTP 403 en de code TIER_RESTRICTED, niet met HTTP 401.

Taken: wachten, polling en resultaten

Verwerking verloopt via taken. Taakpaden gebruiken het patroon handler___command met drie underscores, bijvoorbeeld POST /job/add/paperoffice_aiocr___generate voor tekstherkenning. Puntnotatie wordt afgewezen met JOB_CONFIG_INVALID.

  • Standaard houdt het verzoek de verbinding een tijdje vast. Als de taak op tijd klaar is, ontvangt u het resultaat direct. Anders ontvangt u HTTP 202 met een taak-ID en een poll-adres, en blijft de taak draaien.
  • HTTP 202 is een succes, geen fout. Poll GET /job/get/{job_id} elke 5 tot 10 seconden totdat de status 'completed' is. Het resultaat bevindt zich dan in job_result.
  • Met client_wait=false ontvangt u de taak-ID direct en pollt u vanaf het begin.
  • Alle antwoorden zijn JSON. Clients moeten het stabiele codeveld lezen, niet de gelokaliseerde berichttekst.

U ziet wachtende, lopende en voltooide API-taken in de app onder Account → API → Jobwachtrij. De volledige lijst met foutcodes staat in de specificatie; typische gevallen zijn ontbrekende of ongeldige parameters (400), een ontbrekend of ongeldig token (401), onvoldoende Credits (402), een verboden actie (403) en te veel verzoeken (429, respecteer Retry-After).

Start SLA: wanneer een taak start

Het optionele veld processing_lane bepaalt wanneer een taak in de wachtrij start, niet wanneer deze klaar is. client_wait bepaalt of de verbinding wacht op het resultaat; de twee velden zijn onafhankelijk.

Zonder processing_lane geldt de standaard van de werkruimte, anders best effort. Elk plan bevat best effort zonder toeslag. Snellere startlanen zijn optioneel en kosten meer. De huidige lanen en hun prijzen zijn live beschikbaar via de API-prijzenlijst; details staan in de API-documentatie.

Webhooks

Webhook-endpoints ontvangen taak- en accountgebeurtenissen, bijvoorbeeld job.completed, job.failed, job.progress en gebeurtenissen voor documenten, werkruimtes en taken. Accountmeldingen zoals een lege portemonnee of een ingetrokken key zijn geen webhook-gebeurtenissen.

  • Payloads worden ondertekend met HMAC-SHA256 in de X-Paperoffice-Signature-header. Bereken de handtekening over de ruwe aanvraagbody met uw webhook-geheim en wijs de aanvraag af als deze niet overeenkomt.
  • Webhooks worden geregistreerd, opgesomd, bijgewerkt, getest en verwijderd via de API.

Facturatie en gebruik

API-aanroepen verbruiken Credits uit het gedeelde pool van de organisatie, dezelfde pool als de app. Sommige status- en gezondheidsqueries worden niet in rekening gebracht; details staan in de API-documentatie. Aanroepen die worden afgewezen vanwege ongeldige invoer worden wel in rekening gebracht; aanroepen die door rate limiting zijn geweigerd, niet.

U ziet de aanroepen met hun Credits onder API & Ontwikkelaars → API-gebruik: het live-logboek toont elk verzoek, de geschiedenis toont het gebruik per datum, handler en actie. Wanneer Credits opraken, worden aanroepen afgewezen totdat het saldo is aangevuld of automatische navulling plaatsvindt. Rate limits zijn afhankelijk van uw abonnement; de huidige limieten en de response headers worden beschreven in de API-documentatie. Meer over Credits: Facturatie en Credits in PaperOffice AI.

MCP: AI-assistenten verbinden

MCP verbindt AI-assistenten zoals Claude, ChatGPT, Grok en Cursor direct met PaperOffice. Authenticatie is OAuth 2.1 of een gebruikers- of groeps-token; systeemkeys en publishable keys zijn geblokkeerd voor MCP. De productiehost is https://mcp.paperoffice.ai, met profielen zoals /claude, /chatgpt, /grok, /cursor en /dms. Instellen, machtigingen en gegevensstroom: PaperOffice gebruiken met Claude, ChatGPT, Grok en Cursor.

Veelgestelde vragen

  • Waar vind ik alle endpoints? In llms.txt, llms-full.txt en het OpenAPI-bestand. Ze worden live gegenereerd.
  • Welk token moet mijn server gebruiken? Een systeemkey, nooit in een browser. Voor een browser gebruikt u een publishable key met een origin en een budget.
  • Is HTTP 202 een fout? Nee. De taak is nog bezig; poll voor het resultaat.
  • Kosten snellere startlanen meer? Ja. Best effort heeft geen toeslag; de huidige prijzen staan in de API-prijzenlijst.
  • Worden afgewezen aanroepen in rekening gebracht? Aanroepen die worden afgewezen vanwege ongeldige invoer worden in rekening gebracht; aanroepen die door rate limiting zijn geweigerd, niet.