Overview 6 Timp minim de citire

API-ul PaperOffice pentru dezvoltatori: ghidul complet

Unde se află specificația

Specificația endpoint-ului este generată live din catalogul API. Utilizați aceste fișiere în loc să copiați listele de endpoint-uri din articole:

  • Index compact pentru clienții AI: https://api.paperoffice.ai/latest/docs/llms.txt
  • Referință completă: https://api.paperoffice.ai/latest/docs/llms-full.txt
  • OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
  • Abilitate agent: https://api.paperoffice.ai/latest/docs/skill.md
  • Colecție Postman: https://api.paperoffice.ai/latest/docs/postman

Rutele de documentație sunt publice și nu necesită token. Importați URL-ul Postman în Postman, VS Code sau Bruno și descărcați-l din nou când se schimbă versiunea documentației. Adresa de bază pentru producție este https://api.paperoffice.ai/latest; utilizați /dev doar pentru dezvoltare.

Un început rapid cu un asistent AI de scriere cod: dați-i adresa fișierului llms-full.txt și descrieți funcția de care aveți nevoie, de exemplu o funcție care trimite o imagine și returnează textul recunoscut.

Autentificare și tipuri de token-uri

Majoritatea endpoint-urilor de produs necesită un token bearer în antetul Authorization. Puteți crea token-uri în aplicația PaperOffice la Cont → API.

  • Cheie de sistem (po_sk_): integrare server-la-server cu acces complet la API. Nu o utilizați niciodată într-un browser.
  • Token de utilizator (po_ut_): aria de acces a unui singur utilizator, de exemplu pentru MCP. Drepturile urmează utilizatorul și licența.
  • Token de grup (po_gt_): moștenește drepturile și lista albă a spațiului de lucru al unui grup de utilizatori.
  • Cheie publicabilă (po_pk_): pentru utilizare într-un browser. Fiecare cerere necesită o sursă pe care proprietarul cheii a introdus-o, un buget de viață limitează consumul, iar ștergerea, administrarea contului, gestionarea cheilor și modificările de plată rămân blocate. Nu este permis pentru MCP.

Fără un token, sunt accesibile doar endpoint-urile de infrastructură precum specificația, verificarea sănătății (health check) și testul de conectivitate. O cerere de produs fără un token este răspunsă cu HTTP 403 și codul TIER_RESTRICTED, nu cu HTTP 401.

Sarcini de lucru: așteptare, sondare (polling) și rezultate

Procesarea rulează ca sarcini de lucru. Căile sarcinilor de lucru folosesc modelul handler___command cu trei underscore-uri, de exemplu POST /job/add/paperoffice_aiocr___generate pentru recunoașterea textului. Notația cu puncte este respinsă cu JOB_CONFIG_INVALID.

  • Implicit, cererea menține conexiunea activă pentru o perioadă. Dacă sarcina de lucru se finalizează la timp, primiți rezultatul direct. În caz contrar, primiți HTTP 202 cu un ID de sarcină de lucru și o adresă de sondare (poll address), iar sarcina de lucru continuă să ruleze.
  • HTTP 202 este un succes, nu o eroare. Sondați GET /job/get/{job_id} la fiecare 5 până la 10 secunde până când statusul este completat. Rezultatul se află apoi în job_result.
  • Cu client_wait=false, primiți ID-ul sarcinii de lucru imediat și sondați de la început.
  • Toate răspunsurile sunt JSON. Clienții ar trebui să citească câmpul cod stabil, nu textul mesajului localizat.

Puteți vedea sarcinile de lucru API în așteptare, în curs și completate în aplicație la Cont → API → Coada de joburi. Lista completă a codurilor de eroare se află în specificație; cazurile tipice sunt parametrii lipsă sau invalizi (400), un token lipsă sau invalid (401), Credits insuficient (402), o acțiune interzisă (403) și prea multe cereri (429, respectați Retry-After).

SLA de start: când începe o sarcină de lucru

Câmpul opțional processing_lane controlează când începe o sarcină de lucru în coadă, nu când se finalizează. client_wait controlează dacă conexiunea așteaptă rezultatul; cele două câmpuri sunt independente.

Fără processing_lane, se aplică implicitul spațiului de lucru, altfel best effort. Fiecare plan include best effort fără cost suplimentar. Lane-urile de start mai rapide sunt opționale și costă mai mult. Lane-urile curente și prețurile lor sunt disponibile live prin lista de prețuri API; detaliile se găsesc în documentația API.

Webhook-uri

Endpoint-urile webhook primesc evenimente legate de sarcini de lucru și cont, de exemplu job.completed, job.failed, job.progress și evenimente pentru documente, spații de lucru și sarcini. Notificările cont precum un portofel gol sau o cheie revocată nu sunt evenimente webhook.

  • Payload-urile sunt semnate cu HMAC-SHA256 în antetul X-Paperoffice-Signature. Calculați semnătura pe corpul brut al solicitării cu secretul webhook-ului dumneavoastră și respingeți solicitarea dacă nu se potrivește.
  • Webhook-urile sunt înregistrate, listate, actualizate, testate și șterse prin intermediul API-ului.

Facturare și utilizare

Solicitările API consumă Credits din pool-ul partajat al organizației, același pool ca și aplicația. Unele interogări de stare și sănătate nu sunt taxate; detaliile se găsesc în documentația API. Solicitările respinse din cauza intrării nevalide sunt taxate la rândul lor; solicitările limitate de rată nu sunt.

Vedeți apelurile cu Credits aferente sub API și dezvoltatori → Utilizare API: jurnalul live arată fiecare solicitare, istoricul arată utilizarea pe dată, handler și acțiune. Când Credits se epuizează, apelurile sunt respinse până la reîncărcarea soldului sau activarea reîncărcării automate. Limitele de rată depind de planul dumneavoastră; limitele curente și anteturile de răspuns sunt descrise în documentația API. Mai multe despre Credits: Facturare și Credits în PaperOffice AI.

MCP: conectarea asistenților AI

MCP conectează asistenții AI, cum ar fi Claude, ChatGPT, Grok și Cursor, direct la PaperOffice. Autentificarea este OAuth 2.1 sau un token de utilizator sau grup; cheile de sistem și cheile publicabile sunt blocate pentru MCP. Gazda de producție este https://mcp.paperoffice.ai, cu profiluri precum /claude, /chatgpt, /grok, /cursor și /dms. Configurare, permisiuni și flux de date: Utilizarea PaperOffice cu Claude, ChatGPT, Grok și Cursor.

Întrebări frecvente

  • Unde găsesc toate endpoint-urile? În llms.txt, llms-full.txt și fișierul OpenAPI. Acestea sunt generate în timp real.
  • Ce token ar trebui să folosească serverul dumneavoastră? O cheie de sistem, niciodată într-un browser. Pentru un browser, utilizați o cheie publicabilă cu o sursă și un buget.
  • Este HTTP 202 o eroare? Nu. Job-ul este încă în curs; interogați rezultatul.
  • Lane-urile de start mai rapide costă mai mult? Da. Best effort nu are taxă suplimentară; prețurile curente se găsesc în lista de prețuri API.
  • Sunt taxate apelurile respinse? Apelurile respinse din cauza intrării nevalide sunt taxate; apelurile limitate de rată nu sunt.