Autenticazione e Chiavi

Un Token Bearer. Ogni endpoint.

Ogni endpoint del prodotto PaperOffice-API richiede l'intestazione Authorization: Bearer. Nessun flusso OAuth, nessun refresh.

Due tipi di token, dieci ambiti di autorizzazione, limiti di frequenza documentati.

Creare una chiave API Avviare la prima chiamata API

Un'intestazione Nessun flusso OAuth Revocabile in qualsiasi momento

app.paperoffice.ai/account/api

Richiesta 200 OK Token valido

Intestazione Authorization

Authorization: Bearer po_ut_YOUR_API_KEY

Autorizzazioni

ocr:read
documents:write
jobs:read

Risposta

{
  "status": "success",
  "job_id": "8f2c1a…",
  "result": { "pages": 3 }
}

Infrastruttura EU proprietaria I suoi dati rimangono in Europa.
ISO 27001 attivo Sicurezza certificata.
SOC 2 Type II attivo Standard internazionali per audit.
Oltre 24 anni di esperienza Collaudato. Stabile. Futuro garantito.

cURL

1curl -X POST "https://api.paperoffice.ai/latest/job/add/workflow" \2  -H "Authorization: Bearer po_ut_YOUR_API_KEY" \3  -F "[email protected]" \4  -F "idp_collection=invoice" \5  -F "model=basic-pro-max"

1import requests23response = requests.post(4    "https://api.paperoffice.ai/latest/job/add/workflow",5    headers={"Authorization": "Bearer po_ut_YOUR_API_KEY"},6    files={"file_1": open("invoice.pdf", "rb")},7    data={"idp_collection": "invoice", "model": "basic-pro-max"},8)9print(response.json())

1const form = new FormData();2form.append("file_1", new Blob([await readFile("invoice.pdf")]), "invoice.pdf");3form.append("idp_collection", "invoice");4form.append("model", "basic-pro-max");56const response = await fetch("https://api.paperoffice.ai/latest/job/add/workflow", {7  method: "POST",8  headers: { Authorization: "Bearer po_ut_YOUR_API_KEY" },9  body: form,10});11console.log(await response.json());

Primo avvio

Imposti l'intestazione, scelga la pipeline, invii

Il percorso verso /latest/job/add/ è il nome del job della coda: solitamente nella forma handler___command (ad esempio paperoffice_aiocr___generate); per IDP strutturato si utilizza il workflow della propria pipeline.

Un'intestazione
Authorization: Bearer po_ut_… — un endpoint di prodotto non ha bisogno di altro. po_sk_ e po_ut_ non inviano l'intestazione Origin.
Pipeline nel percorso
handler___command con tre trattini bassi; workflow è l'eccezione con uno slug dedicato. La notazione puntata risponde a API con HTTP 400 JOB_CONFIG_INVALID.
Risultato o job_id
client_wait è true per impostazione predefinita: API mantiene la connessione e restituisce il risultato inline. Se la finestra temporale non è sufficiente, viene restituito HTTP 202 con job_id e poll_url per GET /latest/job/get/{job_id}.

Visualizza il catalogo API llms-full.txt per la sua IDE

Per idp_collection=invoice, basic-pro-max è il modello consigliato: l'OCR-first limita comunque le raccolte stampate con posizioni a basic-pro-max; un model=premium inviato verrà restituito come model: basic-pro-max.

Tipi di token

Due tipi di token, chiaramente separati

Entrambi devono essere inviati al server. Vengono creati, ruotati e revocati nell'app sotto Account → API.

po_sk_ Server a server

Chiave segreta

Accesso completo nell'ambito dell'account
Non consegnare mai nel codice del browser
Nessun header Origin necessario
Bloccato per MCP

Gestire la chiave segreta

po_ut_ Utente

User Token

Limitabile a singole aree
Non consegnare mai nel codice del browser
Nessun header Origin necessario
Consentito per MCP

Creare un token utente

Le chiamate dirette dal browser non passano attraverso questi due token, ma utilizzano la chiave pubblicabile po_pk_ — vincolata alla provenienza, con budget e limiti di frequenza. Visualizzare le chiavi pubblicabili

Autorizzazioni

Dieci aree per ogni token utente

Un token utente include esattamente le aree che gli vengono assegnate al momento della creazione. Se manca un'area, la risposta sarà API con HTTP 403.

Documenti documenti
Caricamento, Download, elaborazione
Workspaces spazi_di_lavoro
Gestione cartelle e struttura
Lavori AI lavori_ai
OCR, IDP, estrazione
Fatturazione fatturazione
Lettura utilizzo e saldo conto
Utenti utenti
Gestisci i membri del team
Webhook webhook
Ricevi eventi
Base di conoscenza knowledge_base
Database delle conoscenze e FAQ
Agenti agenti
Configurare gli agenti IDP
Flussi di lavoro workflow
Creare automazioni
Conformità conformità
Audit, GDPR, archiviazione

Limiti di frequenza

Cosa conta per API

Il conteggio avviene per token; senza Bearer per indirizzo IP. I valori seguenti sono i minimi documentati che si applicano a ogni tariffa.

5: Richieste al secondo
30: Richieste al minuto
100: Richieste all'ora
500: Richieste al giorno

I valori residui sono nell'intestazione della risposta
Gli header RateLimit-* e X-RateLimit-* di ogni risposta indicano quanto rimane disponibile nella finestra corrente.
Superamento del limite: HTTP 429
La API risponde con RATE_LIMIT_EXCEEDED. Ripetere la chiamata dopo il tempo indicato nell'header Retry-After.
Tariffe superiori aumentano i valori
Le tariffe a pagamento si trovano al di sopra di questi valori minimi. Quale tariffa ha quale ambito è indicato nella pagina dei prezzi.

Visualizzare tariffe e ambiti

Sicurezza

Cosa protegge una chiave

Sei meccanismi che entrano in azione durante l'esercizio — ciascuno con un codice di stato verificabile o una posizione nell'app.

Rotazione e revoca
Le chiavi vengono create, elencate, ruotate e revocate nell'app sotto Account → API. Un token revocato risponde con HTTP 401 TOKEN_NOT_FOUND.
Scadenza e validità
I token scaduti o errati restituiscono HTTP 401 INVALID_TOKEN. Le chiavi pubblicabili scadono al più tardi dopo 365 giorni.
Limiti per token
I limiti di frequenza sono calcolati per token, non per account. Una chiave compromessa non influisce sull'intera attività.
Vincolo dell'origine nel browser
Le chiavi pubblicabili richiedono ad ogni richiesta un Origin dalla allowlist; altrimenti l'API risponde con 403 ORIGIN_HEADER_REQUIRED o DOMAIN_NOT_ALLOWED.
Tracciabilità dell'utilizzo
Ogni risposta fatturata include un blocco _billing; la valutazione per chiamata fornisce GET /latest/billing/usage-detail.
Blocchi rigidi
Il login all'account, la gestione delle chiavi, OAuth, l'amministrazione dei partner, le modifiche ai pagamenti e il cracking delle password sono bloccati per le chiavi del browser. Il prodotto APIs con lettura della fatturazione e webhook è consentito. Eliminare Workspace, svuotare il cestino e revocare la Legal Hold è possibile solo nell'app (403 UI_ONLY_ENDPOINT).

Video

Autenticazione in azione

Guardi come funziona una chiamata con token Bearer nella pratica — nel video.

Approfondimenti

Cosa c'è accanto

Le pagine che coprono l'operatività intorno all'autenticazione.

Publishable Keys Chiamate dirette dal browser con po_pk_. Webhook Ricevi eventi invece di effettuare polling. Postman-Collezione Tutti gli endpoint da esplorare. API-Catalogo Quale endpoint svolge quale funzione. llms-full.txt Tutta la documentazione per la sua IDE. Tariffe Quale tariffa copre quale ambito.

Iniziare ora

Crei la chiave, imposti l'intestazione, invii

Nell'app, crei la chiave in Account → API. La prima chiamata è descritta passo per passo nella Prima chiamata API.

Creare una chiave API Avviare la prima chiamata API

Operazioni e fiducia

Cosa i team enterprise verificano prima della prima chiamata

Contratti, sicurezza, supporto e limiti, tutti linkati in un unico luogo.

Prossima fermata

Come procedere

Il prossimo passo consigliato nel funnel degli sviluppatori e due diramazioni pertinenti.

Webhooks & EventsEventi in tempo reale, HMAC firmato Primo API callOttenga la chiave, invii la richiesta, verifichi la risposta Postman CollectionImporta, testa, debugga in Postman

Tornare all'ingresso per sviluppatori

Capire PaperOffice AI in 14 minuti.

Come desidera utilizzare PaperOffice?