Overview 5 Min. læsetid

Den PaperOffice API til udviklere: den komplette guide

Hvor specifikationen findes

Endpoint-specifikationen genereres live fra API-kataloget. Brug disse filer i stedet for at kopiere endpoint-lister fra artikler:

  • Kompakt indeks til AI-klienter: https://api.paperoffice.ai/latest/docs/llms.txt
  • Fuld reference: https://api.paperoffice.ai/latest/docs/llms-full.txt
  • OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
  • Agent-færdighed: https://api.paperoffice.ai/latest/docs/skill.md
  • Postman-samling: https://api.paperoffice.ai/latest/docs/postman

Dokumentationsruterne er offentlige og kræver ingen token. Importér Postman-URL'en i Postman, VS Code eller Bruno, og hent den igen, når dokumentationsudgivelsen ændres. Produktionsbasen er https://api.paperoffice.ai/latest; brug kun /dev til udvikling.

En hurtig start med en AI-kodeassistent: giv den adressen til llms-full.txt og beskriv den funktion, du har brug for, f.eks. en funktion, der sender et billede og returnerer den genkendte tekst.

Godkendelse og token-typer

De fleste produktendpunkter kræver et bearer-token i Authorization-headeren. Du opretter tokens i PaperOffice-appen under Konto → API.

  • Systemnøgle (po_sk_): server-til-server-integration med fuld API-adgang. Brug den aldrig i en browser.
  • Brugertoken (po_ut_): omfatter én brugers scope, f.eks. til MCP. Rettigheder følger brugeren og licensen.
  • Gruppetoken (po_gt_): arver rettighederne og workspace-hvidlisten for en brugergruppe.
  • Publicerbar nøgle (po_pk_): til brug i en browser. Hver anmodning kræver en oprindelse, som nøgleejeren har angivet, et samlet budget begrænser forbruget, og sletning, kontoadministration, nøglehåndtering og betalingsændringer forbliver blokeret. Den er ikke tilladt til MCP.

Uden et token kan kun infrastrukturendpunkter som specifikationen, health check og forbindelsestest nås. En produktanmodning uden token besvares med HTTP 403 og koden TIER_RESTRICTED, ikke med HTTP 401.

Jobs: ventning, polling og resultater

Behandling kører som jobs. Job-stier bruger mønsteret handler___command med tre understreger, f.eks. POST /job/add/paperoffice_aiocr___generate til tekstgenkendelse. Punktnotation afvises med JOB_CONFIG_INVALID.

  • Som standard holder anmodningen forbindelsen åben et stykke tid. Hvis jobbet er færdigt i tide, får du resultatet direkte. Ellers får du HTTP 202 med et job-ID og en poll-adresse, og jobbet kører videre.
  • HTTP 202 er en succes, ikke en fejl. Poll GET /job/get/{job_id} hvert 5. til 10. sekund, indtil statussen er completed. Resultatet findes derefter i job_result.
  • Med client_wait=false får du job-ID'et med det samme og starter polling fra starten.
  • Alle svar er JSON. Klienter bør læse det stabile code-felt, ikke den lokaliserede tekst.

Du ser køende, kørende og færdige API-jobs i appen under Konto → API → Jobkø. Den fulde liste over fejlkoder findes i specifikationen; typiske tilfælde er manglende eller ugyldige parametre (400), et manglende eller ugyldigt token (401), utilstrækkelige Credits (402), en forbudt handling (403) og for mange anmodninger (429, overhold Retry-After).

Start-SLA: hvornår et job starter

Det valgfrie felt processing_lane styrer, hvornår et job starter i køen, ikke hvornår det er færdigt. client_wait styrer, om forbindelsen venter på resultatet; de to felter er uafhængige.

Uden processing_lane gælder workspace-standard, ellers best effort. Alle planer inkluderer best effort uden tillæg. Hurtigere start-lanes er valgfrie og koster mere. De aktuelle lanes og deres priser findes live via API-prislisten; detaljer findes i API-dokumentationen.

Webhooks

Webhook-endpunkter modtager job- og kontoevents, f.eks. job.completed, job.failed, job.progress og events for dokumenter, workspaces og opgaver. Konto-meddelelser som en tom tegnebog eller en tilbagekaldt nøgle er ikke webhook-events.

  • Payloads er signeret med HMAC-SHA256 i X-Paperoffice-Signature-headeren. Beregn signaturen over den rå anmodningsbody med din webhook-hemmelighed og afvis anmodningen, hvis den ikke matcher.
  • Webhooks registreres, listes, opdateres, testes og slettes via API'et.

Fakturering og forbrug

API-kald forbruger Credits fra organisationens fælles pulje, som er den samme pulje som appen. Nogle status- og sundhedsforespørgsler opkræves ikke; detaljer findes i API-dokumentationen. Kald, der afvises på grund af ugyldige input, opkræves også; kald, der er begrænset af rate limits, opkræves ikke.

Du ser kaldene med deres Credits under API & Udvikler → API-brug: live-loggen viser hver anmodning, historikken viser forbruget efter dato, handler og handling. Når Credits løber tør, afvises kald, indtil saldoen er genopladet, eller auto-refill træder i kraft. Rate limits afhænger af din plan; de aktuelle grænser og responsheaderne beskrives i API-dokumentationen. Mere om Credits: Fakturering og Credits i PaperOffice AI.

MCP: Tilslut AI-assistenter

MCP tilslutter AI-assistenter såsom Claude, ChatGPT, Grok og Cursor direkte til PaperOffice. Godkendelse sker via OAuth 2.1 eller et bruger- eller gruppetoken; systemnøgler og publicerbare nøgler er blokeret for MCP. Produktionsværten er https://mcp.paperoffice.ai, med profiler såsom /claude, /chatgpt, /grok, /cursor og /dms. Opsætning, tilladelser og dataflow: Brug af PaperOffice med Claude, ChatGPT, Grok og Cursor.

Ofte stillede spørgsmål

  • Hvor finder jeg alle endpoints? I llms.txt, llms-full.txt og OpenAPI-filen. De genereres i realtid.
  • Hvilket token skal min server bruge? En systemnøgle, aldrig i en browser. Til en browser skal du bruge en publicerbar nøgle med et oprindelsessted (origin) og et budget.
  • Er HTTP 202 en fejl? Nej. Jobbet kører stadig; poll for resultatet.
  • Koster hurtigere startlaner mere? Ja. Best effort har ingen tillæg; de aktuelle priser findes i API-prislisten.
  • Bliver afviste kald opkrævet? Kald, der afvises på grund af ugyldige input, opkræves; kald, der er begrænset af rate limits, opkræves ikke.