L'API PaperOffice per gli sviluppatori: la guida completa

Dove risiede la specifica

La specifica degli endpoint viene generata in tempo reale dal catalogo API. Utilizzare questi file invece di copiare gli elenchi degli endpoint dagli articoli:

• Indice compatto per i client AI: https://api.paperoffice.ai/latest/docs/llms.txt
• Riferimento completo: https://api.paperoffice.ai/latest/docs/llms-full.txt
• OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
• Skill dell'agente: https://api.paperoffice.ai/latest/docs/skill.md
• Collezione Postman: https://api.paperoffice.ai/latest/docs/postman

I percorsi della documentazione sono pubblici e non richiedono alcun token. Importare l'URL di Postman in Postman, VS Code o Bruno, e scaricarlo nuovamente quando cambia la versione della documentazione. L'indirizzo base di produzione è https://api.paperoffice.ai/latest; utilizzare /dev solo per lo sviluppo.

Un avvio rapido con un assistente di codifica AI: fornire all'assistente l'indirizzo di llms-full.txt e descrivere la funzione necessaria, ad esempio una funzione che invia un'immagine e restituisce il testo riconosciuto.

Autenticazione e tipi di token

La maggior parte degli endpoint del prodotto richiede un token bearer nell'intestazione Authorization. I token vengono creati nell'app PaperOffice sotto Conto → API.

• Chiave di sistema (po_sk_): integrazione server-to-server con accesso completo all'API. Non utilizzarla mai in un browser.
• Token utente (po_ut_): l'ambito riguarda un singolo utente, ad esempio per MCP. I diritti seguono l'utente e la licenza.
• Token di gruppo (po_gt_): eredita i diritti e la whitelist degli spazi di lavoro di un gruppo di utenti.
• Chiave pubblicabile (po_pk_): per l'uso in un browser. Ogni richiesta richiede un'origine inserita dal proprietario della chiave, un budget complessivo sulla durata della chiave limita il consumo e le operazioni di eliminazione, amministrazione dell'account, gestione delle chiavi e modifiche ai pagamenti rimangono bloccate. Non è consentita per MCP.

Senza un token, sono raggiungibili solo gli endpoint infrastrutturali come la specifica, il controllo di integrità e il test di connettività. Una richiesta di prodotto senza token riceve la risposta HTTP 403 e il codice TIER_RESTRICTED, non con HTTP 401.

Job: attesa, polling e risultati

L'elaborazione avviene come job. I percorsi dei job seguono il pattern handler___command con tre underscore, ad esempio POST /job/add/paperoffice_aiocr___generate per il riconoscimento del testo. La notazione puntata viene rifiutata con JOB_CONFIG_INVALID.

• Per impostazione predefinita, la richiesta mantiene la connessione per un certo periodo. Se il job termina in tempo, si ottiene il risultato direttamente. In caso contrario, si riceve HTTP 202 con un ID job e un indirizzo di polling, e il job continua a essere elaborato.
• HTTP 202 è un successo, non un errore. Eseguire il polling su GET /job/get/{job_id} ogni 5 a 10 secondi fino a quando lo stato non diventa completato. Il risultato si trova quindi in job_result.
• Con client_wait=false, si ottiene l'ID job immediatamente e si esegue il polling fin dall'inizio.
• Tutte le risposte sono in JSON. I client dovrebbero leggere il campo codice stabile, non il testo del messaggio localizzato.

È possibile visualizzare i job API in coda, in esecuzione e completati nell'app sotto Conto → API → Coda dei job. L'elenco completo dei codici di errore si trova nella specifica; i casi tipici sono parametri mancanti o non validi (400), token mancante o non valido (401), Credits insufficienti (402), azione vietata (403) e troppe richieste (429, rispettare Retry-After).

SLA di avvio: quando inizia un job

Il campo opzionale processing_lane controlla quando un job inizia nella coda, non quando termina. client_wait controlla se la connessione attende il risultato; i due campi sono indipendenti.

Senza processing_lane, si applica il default dello spazio di lavoro, altrimenti best effort. Ogni piano include best effort senza sovrapprezzo. Corsie di avvio più veloci sono opzionali e costano di più. Le corsie attuali e i loro prezzi sono disponibili in tempo reale tramite l'elenco prezzi API; i dettagli si trovano nella documentazione API.

Webhook

Gli endpoint dei webhook ricevono eventi di job e account, ad esempio job.completed, job.failed, job.progress ed eventi per documenti, spazi di lavoro e attività. Le notifiche dell'account come un portafoglio vuoto o una chiave revocata non sono eventi webhook.

• I payload sono firmati con HMAC-SHA256 nell'intestazione X-Paperoffice-Signature. Calcolare la firma sul corpo della richiesta grezza utilizzando il segreto webhook e rifiutare la richiesta se non corrisponde.
• I webhook vengono registrati, elencati, aggiornati, testati ed eliminati tramite l'API.

Fatturazione e utilizzo

Le chiamate API consumano Credits dal pool condiviso dell'organizzazione, lo stesso pool dell'app. Alcune query di stato e di integrità non sono addebitate; i dettagli sono nella documentazione dell'API. Anche le chiamate rifiutate a causa di input non valido sono addebitate; le chiamate soggette a limitazione di frequenza non lo sono.

È possibile visualizzare le chiamate con i relativi Credits sotto API & Sviluppatore → Utilizzo API: il registro in tempo reale mostra ogni richiesta, la cronologia mostra l'utilizzo per data, handler e azione. Quando Credits si esauriscono, le chiamate vengono rifiutate fino al ricaricamento del saldo o all'attivazione della ricarica automatica. I limiti di frequenza dipendono dal piano; i limiti attuali e le intestazioni di risposta sono descritti nella documentazione dell'API. Maggiori informazioni su Credits: Fatturazione e Credits in PaperOffice AI.

MCP: connettere assistenti AI

MCP connette assistenti AI come Claude, ChatGPT, Grok e Cursor direttamente a PaperOffice. L'autenticazione avviene tramite OAuth 2.1 o un token utente o di gruppo; le chiavi di sistema e le chiavi pubblicabili sono bloccate per MCP. L'host di produzione è https://mcp.paperoffice.ai, con profili come /claude, /chatgpt, /grok, /cursor e /dms. Configurazione, autorizzazioni e flusso dei dati: Utilizzo di PaperOffice con Claude, ChatGPT, Grok e Cursor.

Domande frequenti

• Dove si trovano tutti gli endpoint? In llms.txt, llms-full.txt e nel file OpenAPI. Vengono generati in tempo reale.
• Quale token dovrebbe utilizzare il server? Una chiave di sistema, mai in un browser. Per un browser, utilizzare una chiave pubblicabile con un'origine e un budget.
• HTTP 202 è un errore? No. Il lavoro è ancora in corso; effettuare polling per il risultato.
• Le corsie di avvio più veloci costano di più? Sì. Il best effort non prevede sovrapprezzo; i prezzi attuali sono nella lista prezzi dell'API.
• Le chiamate rifiutate sono addebitate? Le chiamate rifiutate a causa di input non valido sono addebitate; le chiamate soggette a limitazione di frequenza non lo sono.