Overview 6 Czas czytania min.

API PaperOffice dla deweloperów: kompletny przewodnik

Gdzie znajduje się specyfikacja

Specyfikacja endpointów jest generowana na żywo z katalogu API. Należy korzystać z tych plików zamiast kopiowania list endpointów z artykułów:

  • Kompaktowy indeks dla klientów AI: https://api.paperoffice.ai/latest/docs/llms.txt
  • Pełna dokumentacja: https://api.paperoffice.ai/latest/docs/llms-full.txt
  • OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
  • Umiejętność agenta: https://api.paperoffice.ai/latest/docs/skill.md
  • Kolekcja Postman: https://api.paperoffice.ai/latest/docs/postman

Ścieżki dokumentacji są publiczne i nie wymagają tokena. Należy zaimportować adres URL Postman do aplikacji Postman, VS Code lub Bruno i pobrać go ponownie po zmianie wersji dokumentacji. Podstawowy adres produkcyjny to https://api.paperoffice.ai/latest; ścieżki /dev należy używać wyłącznie w celu rozwoju.

Szybki start z asystentem kodowania AI: należy podać mu adres pliku llms-full.txt i opisać potrzebną funkcję, na przykład funkcję wysyłającą obraz i zwracającą rozpoznany tekst.

Uwierzytelnianie i typy tokenów

Większość endpointów produktu wymaga tokena bearer w nagłówku Authorization. Tokeny tworzy się w aplikacji PaperOffice w sekcji Konto → API.

  • Klucz systemowy (po_sk_): integracja serwer-serwer z pełnym dostępem do API. Nigdy nie należy go używać w przeglądarce.
  • Token użytkownika (po_ut_): zakres jednego użytkownika, na przykład dla MCP. Prawa zależą od użytkownika i licencji.
  • Token grupy (po_gt_): dziedziczy prawa i białą listę przestrzeni roboczych grupy użytkowników.
  • Klucz publikowalny (po_pk_): do użycia w przeglądarce. Każde żądanie wymaga źródła, które wpisał właściciel klucza; budżet na cały okres życia klucza ogranicza zużycie, a usuwanie, administracja kontem, zarządzanie kluczami i zmiany płatności pozostają zablokowane. Nie jest dozwolony dla MCP.

Bez tokena osiągalne są wyłącznie endpointy infrastruktury, takie jak specyfikacja, kontrola stanu i test łączności. Żądanie produktu bez tokena odpowiada kodem HTTP 403 i kodem TIER_RESTRICTED, a nie HTTP 401.

Zadania: oczekiwanie, polling i wyniki

Przetwarzanie odbywa się jako zadania. Ścieżki zadań używają wzorca handler___command z trzema podkreśleniami, na przykład POST /job/add/paperoffice_aiocr___generate dla rozpoznawania tekstu. Notacja kropek jest odrzucana z kodem JOB_CONFIG_INVALID.

  • Domyślnie żądanie utrzymuje połączenie przez pewien czas. Jeśli zadanie zakończy się w czasie, wynik otrzymuje się bezpośrednio. W przeciwnym razie otrzymuje się HTTP 202 z identyfikatorem zadania i adresem do pollingu, a zadanie kontynuuje działanie.
  • HTTP 202 to sukces, a nie błąd. Należy wykonywać polling GET /job/get/{job_id} co 5 do 10 sekund, aż status wyniesie completed. Wynik znajduje się wówczas w job_result.
  • Z client_wait=false identyfikator zadania otrzymuje się natychmiast i polling rozpoczyna się od początku.
  • Wszystkie odpowiedzi są w formacie JSON. Klienci powinni czytać pole kodu, a nie zlokalizowany tekst komunikatu.

Zadania API w kolejce, w trakcie wykonywania i ukończone widoczne są w aplikacji pod Konto → API → Kolejka zadań. Pełna lista kodów błędów znajduje się w specyfikacji; typowe przypadki to brakujące lub nieprawidłowe parametry (400), brakujący lub nieprawidłowy token (401), niewystarczające Credits (402), zabroniona akcja (403) i zbyt wiele żądań (429, należy honorować Retry-After).

SLA startu: kiedy zadanie się rozpoczyna

Opcjonalne pole processing_lane kontroluje, kiedy zadanie rozpocznie się w kolejce, a nie kiedy się zakończy. client_wait kontroluje, czy połączenie czeka na wynik; oba pola są niezależne.

Bez processing_lane stosuje się domyślną wartość przestrzeni roboczej, w przeciwnym razie best effort. Każdy plan obejmuje best effort bez dopłaty. Szybsze pasma startu są opcjonalne i kosztują więcej. Aktualne pasma i ich ceny dostępne są na żywo poprzez listę cen API; szczegóły znajdują się w dokumentacji API.

Webhooki

Endpointy webhooków odbierają zdarzenia zadań i konta, na przykład job.completed, job.failed, job.progress oraz zdarzenia dla dokumentów, przestrzeni roboczych i zadań. Powiadomienia o koncie, takie jak pusty portfel lub unieważniony klucz, nie są zdarzeniami webhook.

  • Ładunki są podpisywane za pomocą HMAC-SHA256 w nagłówku X-Paperoffice-Signature. Należy obliczyć podpis na podstawie surowej treści żądania przy użyciu sekretu webhooka i odrzucić żądanie, jeśli nie pasuje.
  • Webhooki są rejestrowane, wyświetlane, aktualizowane, testowane i usuwane za pośrednictwem interfejsu API.

Rozliczenia i wykorzystanie

Wywołania API pobierają Credits ze wspólnej puli organizacji, tej samej co aplikacja. Niektóre zapytania dotyczące statusu i zdrowia nie są rozliczane; szczegóły znajdują się w dokumentacji API. Wywołania odrzucone z powodu nieprawidłowych danych wejściowych są również rozliczane; wywołania ograniczone limitami nie są.

Wywołania wraz z ich Credits są widoczne w sekcji API i deweloperzy → Użycie API: dziennik na żywo pokazuje każde żądanie, historia pokazuje użycie według daty, handlera i akcji. Gdy Credits się wyczerpią, wywołania są odrzucane do momentu uzupełnienia salda lub aktywacji automatycznego doładowania. Limity szybkości zależą od planu; aktualne limity i nagłówki odpowiedzi opisano w dokumentacji API. Więcej na temat Credits: Rozliczenia i Credits w PaperOffice AI.

MCP: łączenie asystentów AI

MCP łączy asystentów AI, takich jak Claude, ChatGPT, Grok i Cursor, bezpośrednio z PaperOffice. Uwierzytelnianie odbywa się za pomocą OAuth 2.1 lub tokena użytkownika/grupy; klucze systemowe i klucze publikowalne są zablokowane dla MCP. Host produkcyjny to https://mcp.paperoffice.ai, z profilami takimi jak /claude, /chatgpt, /grok, /cursor i /dms. Konfiguracja, uprawnienia i przepływ danych: Korzystanie z PaperOffice z Claude, ChatGPT, Grok i Cursor.

Najczęściej zadawane pytania

  • Gdzie znaleźć wszystkie punkty końcowe? W plikach llms.txt, llms-full.txt oraz pliku OpenAPI. Są one generowane w czasie rzeczywistym.
  • Jaki token powinien używać serwer? Klucz systemowy, nigdy w przeglądarce. Dla przeglądarki należy użyć klucza publikowalnego z określonym źródłem i budżetem.
  • Czy HTTP 202 to błąd? Nie. Zadanie nadal działa; należy sprawdzać wynik.
  • Czy szybsze pasma startu kosztują więcej? Tak. Tryb best effort nie wymaga dopłaty; aktualne ceny znajdują się na liście cenowej API.
  • Czy odrzucone wywołania są rozliczane? Wywołania odrzucone z powodu nieprawidłowych danych wejściowych są rozliczane; wywołania ograniczone limitami nie są.