NextPDF — dokumentacja API Connect

W skrócie

Ta strona dokumentuje symbole serwera NextPDF Connect (nextpdf/server). Wymienia każde narzędzie z podaniem zarejestrowanej nazwy narzędzia i klasy implementującej oraz opisuje usługę gRPC NextPDFConnect, w tym jej metody Remote Procedure Call (RPC) oraz komunikaty żądań i odpowiedzi. Definiuje także wspólny dla wszystkich transportów kontrakt uwierzytelniania, obsługi błędów i limitów szybkości.

Serwer udostępnia jeden rejestr narzędzi za pośrednictwem trzech transportów: Model Context Protocol (MCP) przez standardowe wejście i wyjście, interfejs Application Programming Interface (API) typu Representational State Transfer (REST) oraz gRPC. Szczegóły formatu sieciowego każdego transportu są opisane na osobnej stronie: zobacz Transport MCP, Transport REST oraz Transport gRPC. Ta strona kataloguje symbole udostępniane przez te transporty.

Nazwy narzędzi, klasy i poziomy ryzyka są odczytywane z implementacji narzędzi w katalogu src/Tools/. Liczba narzędzi udostępnianych przez wdrożenie jest ustalana w czasie działania; zobacz Katalog narzędzi. Uruchamianie i wykrywanie wyjaśnia sposób rozstrzygania poziomów.

Dostępność transportów

Narzędzie jest dostępne za pośrednictwem każdego transportu uruchomionego w danym wdrożeniu. Transporty działają jako niezależne procesy; uruchomienie jednego nie uruchamia pozostałych.

Transport	Punkt wejścia	Format sieciowy	Uwierzytelnianie
MCP	bin/nextpdf-mcp	JavaScript Object Notation Remote Procedure Call (JSON-RPC) 2.0 przez stdio	Granica procesu systemu operacyjnego (bez klucza API)
REST	bin/nextpdf-server	HTTP, OpenAPI 3.1	Klucz API typu Bearer w nagłówku Authorization
gRPC	bin/nextpdf-grpc	Protocol Buffers, pakiet nextpdf.connect.v1	Token typu Bearer w metadanych wywołania authorization

W MCP wywołujesz narzędzie za pomocą tools/call i zarejestrowanej nazwy narzędzia. W REST i gRPC korzystasz z tych samych funkcji silnika przez powierzchnie renderowania, operacji i możliwości; zobacz tabelę tras w Transporcie REST oraz tabelę RPC w Transporcie gRPC.

Uwierzytelnianie i poziom ryzyka

Uwierzytelnianie kluczem API

Transporty REST i gRPC wymagają klucza API typu Bearer w każdym żądaniu z wyjątkiem sond stanu niewymagających uwierzytelnienia. Klucz ma postać npk_live_{kid}_{secret}: kid to ośmioznakowy identyfikator służący do wyszukania rekordu, a sekret zapewnia entropię. Serwer przechowuje wyłącznie skrót SHA-256 klucza i porównuje podany token w stałym czasie, więc nieprawidłowy klucz nie ujawnia niczego przez pomiar czasu. REST odczytuje token z nagłówka Authorization: Bearer …; gRPC odczytuje ten sam token z metadanych wywołania authorization. Transport stdio MCP nie ma klucza API, ponieważ jest lokalnym podprocesem, któremu ufa klient go uruchamiający. Bezpieczeństwo i operacje dokumentuje pełny model uwierzytelniania.

Cztery poziomy ryzyka

Każde narzędzie deklaruje jeden z czterech uporządkowanych poziomów ryzyka, zdefiniowanych przez wyliczenie RiskLevel w pliku src/Config/RiskLevel.php.

Poziom	Przypadek wyliczenia	Wartość	Efekt
Safe	RiskLevel::Safe	0	Tylko do odczytu, bez efektów ubocznych. Wykonuje się automatycznie.
Caution	RiskLevel::Caution	1	Tworzy lub modyfikuje stan w pamięci. Wykonuje się automatycznie, z zapisem w dzienniku audytu.
Review	RiskLevel::Review	2	Generuje wynik, który mógłby zostać niewłaściwie użyty. Wykonuje się automatycznie, z zapisem w dzienniku audytu.
ApprovalRequired	RiskLevel::ApprovalRequired	3	Destrukcyjne, prawnie istotne lub krytyczne dla prywatności. Wymaga potwierdzenia przez człowieka.

Efektywne ryzyko narzędzia pochodzi dokładnie z dwóch miejsc: z własnej deklaracji riskLevel() narzędzia oraz z opcjonalnego nadpisania w konfiguracji operatora, które może jedynie podnieść ryzyko, nigdy nie obniżyć poziomu narzędzia ApprovalRequired. Zobacz Poziomy ryzyka HITL oraz Konfigurację.

Jak przepływają tokeny zatwierdzenia

Gdy wywołasz narzędzie ApprovalRequired bez prawidłowego tokenu, ConfirmationGate (src/Mcp/ConfirmationGate.php) zwraca jednorazowy token wyzwania zamiast uruchomić narzędzie. Agent przekazuje wyzwanie człowiekowi, a następnie ponownie wywołuje to samo narzędzie z wydanym tokenem w argumencie _confirmation_token. Token wiąże nazwę narzędzia, losowy nonce oraz 300-sekundowy czas życia (TTL). Nie wiąże argumentów i nie jest poświadczeniem uwierzytelniającym. W REST klucz API typu Bearer nadal uwierzytelnia żądanie, a ta sama bramka działa we wspólnym module wykonawczym narzędzi przed operacją objętą bramką. W gRPC ta sama bramka działa przed zleconą operacją. Mechanizm wyzwania i tokenu jest identyczny we wszystkich transportach.

Narzędzia i punkty końcowe

Tabela dokumentuje każde narzędzie według zarejestrowanej nazwy narzędzia (kolumna Symbol) i klasy implementującej. Narzędzia są pogrupowane według poziomu i kategorii. Wszystkie klasy Abstract Syntax Tree (AST) oraz klasy mutacji znajdują się w src/Tools/Ast i src/Tools/Ast/Mutation; klasa ekstrakcji znajduje się w src/Tools/Extraction; pozostałe klasy znajdują się w src/Tools/Core.

Podstawowe narzędzia dokumentowe

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza albo kończy się niepowodzeniem, gdy	Uwagi
create_pdf	page_size (domyślnie A4), orientation (portrait/landscape), title, author; żaden nie jest wymagany.	Tworzy dokument w pamięci i jedną stronę; ustawia metadane, gdy są podane.	JSON z document_id, page_count, page_size, orientation.	Zwraca wynik błędu z komunikatem silnika w razie niepowodzenia.	Klasa CreatePdfTool. Ryzyko RiskLevel::Caution. Poziom core. Zwrócony document_id zasila każdą kolejną operację.
add_page	document_id (wymagany), opcjonalny rozmiar i orientacja strony.	Dołącza stronę do dokumentu.	JSON z nową liczbą stron.	Wynik błędu, gdy document_id jest nieznany.	Klasa AddPageTool. Ryzyko RiskLevel::Caution. Poziom core.
add_text	document_id (wymagany), text (wymagany), opcjonalna pozycja i styl.	Dodaje tekst do dokumentu.	Podsumowanie stanu dokumentu w formacie JSON.	Wynik błędu, gdy document_id jest nieznany.	Klasa AddTextTool. Ryzyko RiskLevel::Caution. Poziom core.
add_image	document_id (wymagany), source (wymagany: ścieżka pliku lub base64), opcjonalne umiejscowienie.	Dodaje obraz ze ścieżki lub danych base64.	Podsumowanie stanu dokumentu w formacie JSON.	Wynik błędu przy nieczytelnym źródle lub nieznanym document_id.	Klasa AddImageTool. Ryzyko RiskLevel::Caution. Poziom core.
add_table	document_id (wymagany), html (wymagany).	Renderuje tabelę Hypertext Markup Language (HTML) do dokumentu.	Podsumowanie stanu dokumentu w formacie JSON.	Wynik błędu przy nieprawidłowych znacznikach lub nieznanym document_id.	Klasa AddTableTool. Ryzyko RiskLevel::Caution. Poziom core.
set_font	document_id (wymagany), family (wymagany), opcjonalny rozmiar i styl.	Ustawia czcionkę dla kolejnych operacji na tekście.	Potwierdzenie aktywnej czcionki w formacie JSON.	Wynik błędu przy nieznanej czcionce lub document_id.	Klasa SetFontTool. Ryzyko RiskLevel::Caution. Poziom core.
output_pdf	document_id (wymagany), file_path (opcjonalny), destroy (domyślnie true).	Finalizuje dokument; zapisuje do file_path lub zwraca base64, gdy ścieżkę pominięto; domyślnie niszczy dokument.	JSON z file_path i file_size albo base64 i file_size.	Wynik błędu, gdy document_id jest nieznany; niepowodzenie kontroli zawierania ścieżki przy zapisie poza katalogiem bazowym.	Klasa OutputPdfTool. Ryzyko RiskLevel::ApprovalRequired. Poziom core. Zapis pliku przechodzi przez bramkę potwierdzenia; tryb base64 nie.
preview_layout	document_id (wymagany).	Zwraca podsumowanie układu bez renderowania końcowego PDF.	Podsumowanie układu w formacie JSON.	Wynik błędu, gdy document_id jest nieznany.	Klasa PreviewLayoutTool. Ryzyko RiskLevel::Safe. Poziom core.
parse_pdf	document_id (wymagany).	Sprawdza metadane strukturalne: liczbę stron, czcionki, obrazy, szyfrowanie oraz słownik Info.	Metadane strukturalne w formacie JSON.	Wynik błędu przy uszkodzonym dokumencie.	Klasa ParsePdfTool. Ryzyko RiskLevel::Safe. Poziom core. Rejestruje się tylko wtedy, gdy NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED ma wartość true lub 1.

Podstawowe narzędzia diagnostyczne

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza albo kończy się niepowodzeniem, gdy	Uwagi
diagnostic.doctor	brak.	Uruchamia kontrolę stanu i zwraca uporządkowaną diagnostykę środowiska.	Raport środowiska w formacie JSON.	Wynik błędu przy niepowodzeniu wewnętrznej kontroli.	Klasa DiagnosticDoctorTool. Ryzyko RiskLevel::Safe. Poziom core. Nie wymaga dokumentu ani potwierdzenia.
diagnostic.capabilities	brak.	Wymienia funkcje wraz z informacjami o poziomie i stanie.	Lista funkcji w formacie JSON.	Wynik błędu przy wewnętrznym niepowodzeniu.	Klasa DiagnosticCapabilitiesTool. Ryzyko RiskLevel::Safe. Poziom core.
diagnostic.inspect	document_id (wymagany).	Sprawdza PDF i zwraca metadane strukturalne.	Metadane strukturalne w formacie JSON.	Wynik błędu, gdy document_id jest nieznany.	Klasa DiagnosticInspectTool. Ryzyko RiskLevel::Safe. Poziom core.
diagnostic.verify	document_id (wymagany), opcjonalny profil PDF/A lub PDF/UA.	Weryfikuje integralność strukturalną; opcjonalnie sprawdza zgodność z PDF/A lub PDF/UA, uruchamiając podproces VeraPDF.	Raport weryfikacji w formacie JSON.	Wynik błędu przy niepowodzeniu podprocesu, przekroczeniu limitu czasu lub zbyt dużym wejściu.	Klasa DiagnosticVerifyTool. Ryzyko RiskLevel::Caution. Poziom core. Wejście jest ograniczone do 50 mebibajtów (MiB).

Podstawowe narzędzie kodów kreskowych

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza albo kończy się niepowodzeniem, gdy	Uwagi
generate_barcode	payload (wymagany), format (na przykład QR Code, DataMatrix).	Generuje dwuwymiarową macierz modułów kodu kreskowego dla ładunku.	Macierz modułów w formacie JSON.	Wynik błędu przy nieobsługiwanym format lub nieprawidłowym ładunku.	Klasa BarcodeTool. Ryzyko RiskLevel::Caution. Poziom core. BarcodeTool rejestruje się tylko wtedy, gdy podstawowy rejestr koderów barcode jest obecny w zainstalowanym nextpdf/core; zarejestrowana nazwa narzędzia to generate_barcode.

Narzędzia prywatności Enterprise

Te narzędzia opakowują klasy prywatności Enterprise i rejestrują się na poziomie Enterprise tylko wtedy, gdy te klasy są dostępne przez autoładowanie. Działają na treści w postaci zwykłego tekstu.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza albo kończy się niepowodzeniem, gdy	Uwagi
redact_pdf	content (wymagany), opcjonalne opcje wykrywania.	Destrukcyjnie usuwa dane umożliwiające identyfikację osoby (PII) z treści w postaci zwykłego tekstu, korzystając z silnika redagowania Enterprise.	JSON z zredagowaną treścią i skrótem SHA-256.	Wynik błędu, gdy klasy Enterprise są nieobecne lub wykrywanie zakończy się niepowodzeniem.	Klasa RedactPdfTool. Ryzyko RiskLevel::Review. Poziom enterprise.
deidentify_pdf	content (wymagany), strategy (redact lub suppress).	Stosuje systematyczną strategię deidentyfikacji do treści w postaci zwykłego tekstu, korzystając z deidentyfikatora Enterprise.	JSON ze zdeidentyfikowaną treścią.	Wynik błędu, gdy klasy Enterprise są nieobecne.	Klasa DeIdentifyPdfTool. Ryzyko RiskLevel::Review. Poziom enterprise.
zone_redact_pdf	content (wymagany), zones (strona oraz lista znormalizowanych prostokątów).	Stosuje redagowanie strefowe oparte na współrzędnych, korzystając z silnika redagowania Enterprise.	JSON ze zredagowaną treścią.	Wynik błędu przy nieprawidłowej strefie lub nieobecnych klasach Enterprise.	Klasa ZoneRedactionTool. Ryzyko RiskLevel::Review. Poziom enterprise.

Narzędzia odczytu drzewa składni abstrakcyjnej (AST)

Te narzędzia są dostarczane wraz z serwerem, rejestrują się na poziomie Pro i są bramkowane przez NEXTPDF_AST_TOOLS_ENABLED (domyślnie włączone). Działają wyłącznie do odczytu.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza albo kończy się niepowodzeniem, gdy	Uwagi
get_document_ast	pdf_data (wymagany).	Buduje semantyczne AST: pełne drzewo węzłów z kotwicami cytowań dla każdego elementu strukturalnego.	Drzewo węzłów w formacie JSON wraz z wartością ETag do kontroli współbieżności.	Wynik błędu przy uszkodzonym dokumencie.	Klasa GetDocumentAstTool. Ryzyko RiskLevel::Safe. Poziom pro.
get_ast_node	pdf_data (wymagany), node_id (wymagany).	Pobiera pojedynczy węzeł AST i wszystkie jego węzły potomne.	Węzeł z węzłami potomnymi w formacie JSON.	Wynik błędu przy nieznanym node_id.	Klasa GetAstNodeTool. Ryzyko RiskLevel::Safe. Poziom pro.
get_ast_diff	original_pdf_data (wymagany), modified_pdf_data (wymagany).	Strukturalnie porównuje dwa dokumenty, zestawiając ich semantyczne AST.	Węzły dodane, usunięte i zmienione w formacie JSON.	Wynik błędu przy uszkodzonym dokumencie wejściowym.	Klasa GetAstDiffTool. Ryzyko RiskLevel::Safe. Poziom pro.
search_ast_nodes	pdf_data (wymagany), opcjonalne filtry typu, indeksu strony i tekstu.	Wyszukuje węzły AST według typu, indeksu strony lub zawartości tekstowej.	Płaska lista pasujących węzłów z płytkimi węzłami potomnymi w formacie JSON.	Wynik błędu przy uszkodzonym dokumencie.	Klasa SearchAstNodesTool. Ryzyko RiskLevel::Safe. Poziom pro.
extract_cited_text	pdf_data (wymagany), opcjonalny headings_only.	Wyodrębnia bloki tekstu z kotwicami cytowań (strona, prostokąt ograniczający, pewność).	Cytowane bloki tekstu w formacie JSON.	Wynik błędu przy uszkodzonym dokumencie.	Klasa ExtractCitedTextTool. Ryzyko RiskLevel::Safe. Poziom pro. Kategoria ast.
extract_cited_tables	pdf_data (wymagany).	Wyodrębnia bloki tabel z kotwicami cytowań; zwraca macierz komórek w kolejności wierszy dla każdego węzła Table.	Macierze tabel z kotwicami w formacie JSON.	Wynik błędu przy uszkodzonym dokumencie.	Klasa ExtractCitedTablesTool. Ryzyko RiskLevel::Safe. Poziom pro. Kategoria extraction.

Narzędzia mutacji AST

Te narzędzia są dostarczane wraz z serwerem, rejestrują się na poziomie Pro i są bramkowane przez NEXTPDF_MUTATION_TOOLS_ENABLED (domyślnie włączone). Wszystkie cztery są typu ApprovalRequired i stosują optymistyczną kontrolę współbieżności (OCC) za pomocą wartości ETag.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza albo kończy się niepowodzeniem, gdy	Uwagi
apply_ast_mutations	pdf_data, etag, idempotency_key, mutations (wszystkie wymagane).	Atomowo stosuje wsad mutacji; zwraca wynik zapisany w pamięci podręcznej dla powtórzonego idempotency_key.	JSON ze zmutowanym PDF i nowym ETag.	Konflikt OCC, gdy ETag jest nieaktualny; błąd walidacji przy nieprawidłowej mutacji.	Klasa ApplyAstMutationsTool. Ryzyko RiskLevel::ApprovalRequired. Poziom pro.
delete_ast_node	pdf_data, node_id, etag (wszystkie wymagane).	Usuwa węzeł w trybie nakładki (oryginalna treść jest przykryta, a nie fizycznie usunięta).	JSON ze zmodyfikowanym PDF i nowym ETag.	Konflikt OCC, gdy ETag jest nieaktualny; błąd przy nieznanym node_id.	Klasa DeleteAstNodeTool. Ryzyko RiskLevel::ApprovalRequired. Poziom pro.
insert_ast_node	pdf_data, parent_node_id, position, etag, node (wszystkie wymagane).	Wstawia nowy węzeł jako potomny węzła nadrzędnego w określonej pozycji.	JSON ze zmodyfikowanym PDF i nowym ETag.	Konflikt OCC, gdy ETag jest nieaktualny; błąd walidacji przy nieprawidłowym węźle.	Klasa InsertAstNodeTool. Ryzyko RiskLevel::ApprovalRequired. Poziom pro.
update_ast_node	pdf_data, node_id, etag, updates (wszystkie wymagane).	Aktualizuje zawartość tekstową węzła.	JSON ze zmodyfikowanym PDF i nowym ETag.	Konflikt OCC, gdy ETag jest nieaktualny; błąd przy nieznanym node_id.	Klasa UpdateAstNodeTool. Ryzyko RiskLevel::ApprovalRequired. Poziom pro.

Schemat żądania i odpowiedzi

Transport gRPC definiuje typowany schemat serwera w pakiecie Protocol Buffers nextpdf.connect.v1, w proto/nextpdf/connect/v1/*.proto. Usługa i jej komunikaty są kanonicznymi symbolami schematu.

Usługa NextPDFConnect

Usługa NextPDFConnect udostępnia unarne RPC oraz RPC strumieniowane po stronie serwera. Symbolami schematu są nazwy metod RPC oraz przenoszone przez nie komunikaty żądań i odpowiedzi.

RPC	Komunikat żądania	Komunikat odpowiedzi	Postać
Render	RenderRequest	RenderResponse	Unarne. Synchroniczne renderowanie bezstanowe.
RenderStream	RenderRequest	RenderChunk (strumień)	Strumieniowane po stronie serwera. Renderowanie dostarczane jako uporządkowane fragmenty.
SubmitJob	SubmitJobRequest	JobResponse	Unarne. Przesłanie asynchronicznego zadania renderowania.
GetJobStatus	GetJobStatusRequest	JobResponse	Unarne. Sprawdzenie stanu zadania.
GetJobResult	GetJobResultRequest	RenderResponse	Unarne. Pobranie ukończonego wyniku.
GetJobResultStream	GetJobResultRequest	RenderChunk (strumień)	Strumieniowane po stronie serwera. Pobranie ukończonego wyniku jako fragmentów.
CancelJob	CancelJobRequest	JobResponse	Unarne. Anulowanie lub usunięcie zadania.
CreateSession	CreateSessionRequest	SessionResponse	Unarne. Utworzenie sesji budowania dokumentu.
GetSession	GetSessionRequest	SessionResponse	Unarne. Pobranie metadanych sesji.
DestroySession	DestroySessionRequest	DestroySessionResponse	Unarne. Zniszczenie sesji i jej dokumentu.
SessionOperation	SessionOperationRequest	SessionResponse	Unarne. Wykonanie operacji na dokumencie sesji.
SessionRender	SessionRenderRequest	RenderResponse	Unarne. Renderowanie dokumentu sesji do PDF.
SessionRenderStream	SessionRenderRequest	RenderChunk (strumień)	Strumieniowane po stronie serwera. Renderowanie dokumentu sesji jako fragmentów.
ExecuteCapability	CapabilityRequest	CapabilityResponse	Unarne. Wykonanie operacji możliwości bramkowanej poziomem.
GetCapabilities	GetCapabilitiesRequest	GetCapabilitiesResponse	Unarne. Wypisanie możliwości dla uwierzytelnionego klienta.
HealthCheck	HealthCheckRequest	HealthCheckResponse	Unarne. Sonda żywotności.
ReadinessCheck	ReadinessCheckRequest	ReadinessCheckResponse	Unarne. Sonda gotowości.

Symbole komunikatów

Komunikaty żądań i odpowiedzi są strukturalnymi symbolami schematu. Komunikaty renderowania, RenderRequest, RenderResponse oraz strumieniowy RenderChunk, przenoszą rozmiar strony, orientację, uporządkowane operacje oraz wynikowe bajty PDF. Komunikaty zadań, SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest oraz JobResponse, modelują asynchroniczny cykl życia zadania, z metadanymi zadania przechowywanymi w komunikacie JobData. Komunikaty sesji, CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest oraz SessionRenderRequest, modelują stanowy cykl życia sesji, z metadanymi sesji przechowywanymi w komunikacie SessionData. Komunikaty możliwości, CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest oraz GetCapabilitiesResponse, przenoszą wywołanie i introspekcję operacji bramkowanych poziomem. Komunikaty systemowe, HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest oraz ReadinessCheckResponse, przenoszą stan żywotności i gotowości.

Dostarczone pliki .proto są obowiązującym kontraktem sieciowym; zobacz dokumentację transportu gRPC w Transporcie gRPC.

Model błędów

Serwer raportuje niepowodzenia za pomocą natywnego mechanizmu błędów każdego transportu. Każdy transport zachowuje tę samą logikę warunku; różni się tylko kodowanie.

MCP

Błędy MCP to obiekty błędu JSON-RPC 2.0. Nieznana metoda zwraca method-not-found (-32601); komunikat, który nie jest prawidłowym JSON-RPC, zwraca invalid-request (-32600); niemożliwe do sparsowania wejście zwraca parse-error (-32700). Gdy narzędzie kończy się niepowodzeniem, zwraca pomyślną odpowiedź JSON-RPC, której treść sygnalizuje błąd, zamiast błędu na poziomie transportu, dzięki czemu agent może odczytać komunikat. Wyzwanie potwierdzenia dla narzędzia ApprovalRequired jest również pomyślną odpowiedzią, a nie błędem.

REST

REST stosuje kody stanu Hypertext Transfer Protocol (HTTP) z semantyką zdefiniowaną w RFC 9110. 200 przenosi wynik; 400 jest zwracany, gdy pole żądania nie przejdzie walidacji formatu; 401 jest zwracany, gdy nie przedstawiono prawidłowego klucza API, i zawiera nagłówek wyzwania WWW-Authenticate: Bearer; 403 jest zwracany, gdy poziom prawidłowego klucza nie uprawnia do operacji; 404 jest zwracany, gdy trasa bramkowana poziomem nie jest zarejestrowana, ponieważ jej pakiet jest nieobecny. Treści błędów czytelne maszynowo to dokumenty Problem Details zgodne z RFC 9457, dostarczane z typem nośnika application/problem+json oraz stabilnym Uniform Resource Identifier (URI) type dla każdego warunku. Niepowodzenia walidacji na poziomie pól są wymienione w treści. W ramach zabezpieczenia przed przechodzeniem ścieżki document_id, który nie pasuje do wzorca doc_[a-f0-9]{24}, jest odrzucany z 400 przed uruchomieniem narzędzia. Transport REST dokumentuje potok oprogramowania pośredniczącego REST i tabelę tras.

gRPC

gRPC stosuje standardowe kody stanu gRPC. Brakujący, zniekształcony, nieznany, wyłączony lub wygasły token kończy wywołanie statusem UNAUTHENTICATED, a nie statusem HTTP. Rozszerzone szczegóły błędu odzwierciedlają postać Problem Details z REST i są przenoszone w szczegółach stanu gRPC, więc URI type błędu jest spójny we wszystkich transportach.

Zobacz także RFC 9110 (HTTP Semantics) w sprawie semantyki kodów stanu oraz RFC 9457 (Problem Details for HTTP APIs) w sprawie formatu treści błędu.

• RFC 9110: https://www.rfc-editor.org/rfc/rfc9110
• RFC 9457: https://www.rfc-editor.org/rfc/rfc9457

Limity szybkości i kwoty

Transport REST stosuje ograniczanie szybkości według adresu protokołu internetowego (adresu IP) i klienta w swoim potoku oprogramowania pośredniczącego, a także limity rozmiaru treści i ładunku zależne od poziomu oraz limit czasu na żądanie. Te górne granice są wartościami konfiguracyjnymi, a nie stałymi zakodowanymi na stałe:

• Górne granice ładunku zależne od poziomu (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit) oraz odpowiadające im limity czasu obowiązują w REST zgodnie z poziomem uwierzytelnionego klucza. Zobacz Konfigurację.
• Magazyn dokumentów w pamięci jest ograniczony przez max_documents (domyślnie 50) oraz document_ttl (domyślnie 1800 sekund).
• Stan limitów szybkości i idempotencji ma zakres procesu roboczego, chyba że dla wspólnego magazynu skonfigurowano NEXTPDF_REDIS_HOST. Zobacz Wdrożenie.

Gdy magazyny limitów szybkości i idempotencji są współdzielone, powtórzone identyczne asynchroniczne zgłoszenia zadań są deduplikowane na podstawie idempotency_key. Transport MCP obsługuje jedno żądanie naraz za pośrednictwem potoków i deduplikuje powtórzony id żądania z 64-elementowego bufora zamiast stosować sieciowe ograniczanie szybkości.

Uwagi dla deweloperów

• Odczytuj nazwy narzędzi, klasy i poziomy ryzyka ze źródła w src/Tools/; nie zakładaj stałej liczby całkowitej. Odpytaj działający serwer o miarodajną liczbę, jak pokazano w Katalogu narzędzi.
• Wygeneruj ponownie stuby klienta gRPC z dostarczonych plików proto/nextpdf/connect/v1/*.proto; pakiet i przestrzeń nazw to nextpdf.connect.v1. Nie edytuj ręcznie wygenerowanych klas komunikatów.
• Narzędzie o poziomie ApprovalRequired odpowiada wyzwaniem potwierdzenia przy pierwszym wywołaniu. Zaimplementuj ścieżkę ponowienia — przekaż wyzwanie, a następnie wywołaj ponownie z _confirmation_token — zanim wdrożysz integrację wywołującą output_pdf lub dowolne narzędzie mutacji.
• Trasa lub możliwość bramkowana poziomem, która nie jest zainstalowana, nie jest niepowodzeniem uwierzytelniania: REST zwraca 404 dla nieobecnej trasy, a gRPC ExecuteCapability zgłasza operację jako niedostępną. Traktuj brak poziomu Pro lub Enterprise jako oczekiwane działanie, a nie usterkę.
• Trzymaj klucze API poza systemem kontroli wersji; montuj je z pliku z sekretami i preferuj plikowy magazyn kluczy z przeładowaniem na gorąco, aby rotacja nie wymagała ponownego uruchomienia. Zobacz Bezpieczeństwo i operacje.

Zobacz także

• Przewodnik dla deweloperów — architektura, cykl życia, punkty rozszerzeń oraz lista kontrolna testów
• Katalog narzędzi — zweryfikowany zestaw podstawowych narzędzi oraz liczba ustalana w czasie działania
• Poziomy ryzyka HITL — model ryzyka oraz wyzwanie potwierdzenia
• Transport MCP · Transport REST · Transport gRPC — szczegóły formatu sieciowego dla poszczególnych transportów
• Bezpieczeństwo i operacje — uwierzytelnianie, bezpieczeństwo transportu oraz model zagrożeń