Riferimento API di NextPDF Connect

In breve

Questa pagina è il riferimento a livello di simboli per il server NextPDF Connect (nextpdf/server). Elenca ciascuno strumento con il nome registrato e la classe che lo implementa, e documenta il servizio gRPC NextPDFConnect con i relativi metodi Remote Procedure Call (RPC) e messaggi di richiesta e risposta. Definisce il contratto condiviso da ogni trasporto per autenticazione, errori e limiti di frequenza.

Il server espone un unico registro degli strumenti tramite tre trasporti: il Model Context Protocol (MCP) su standard input e output, un’interfaccia di programmazione delle applicazioni (API) Representational State Transfer (REST) e gRPC. I dettagli di trasmissione di ciascun trasporto sono descritti nella rispettiva pagina: vedere Trasporto MCP, Trasporto REST e Trasporto gRPC. Questa pagina funge da catalogo dei simboli veicolati da tali trasporti.

I nomi degli strumenti, le classi e i livelli di rischio riportati di seguito sono ricavati dalle implementazioni degli strumenti in src/Tools/. Il numero di strumenti effettivamente esposti da una distribuzione è una proprietà di runtime; vedere Catalogo degli strumenti. La logica di risoluzione dei livelli è descritta in Avvio e individuazione.

Disponibilità dei trasporti

Uno strumento è raggiungibile tramite il trasporto in esecuzione nella distribuzione. I trasporti sono processi indipendenti: avviarne uno non avvia gli altri.

Trasporto	Punto di ingresso	Formato di trasmissione	Autenticazione
MCP	bin/nextpdf-mcp	JavaScript Object Notation Remote Procedure Call (JSON-RPC) 2.0 su stdio	Confine del processo del sistema operativo (nessuna chiave API)
REST	bin/nextpdf-server	HTTP, OpenAPI 3.1	Chiave API Bearer nel campo Authorization dell’intestazione
gRPC	bin/nextpdf-grpc	Protocol Buffers, pacchetto nextpdf.connect.v1	Token Bearer nel campo authorization dei metadati di chiamata

Con MCP, uno strumento viene chiamato tramite tools/call con il nome registrato. Con REST e gRPC, le stesse funzionalità del motore sono raggiungibili tramite le superfici di rendering, operazione e funzionalità; vedere la tabella delle route in Trasporto REST e la tabella degli RPC in Trasporto gRPC.

Autenticazione e livello di rischio

Autenticazione tramite chiave API

I trasporti REST e gRPC richiedono una chiave API Bearer per ogni richiesta, eccetto i probe di integrità non autenticati. Una chiave ha la forma npk_live_{kid}_{secret}: il valore kid è un identificatore di otto caratteri per la ricerca dei record e la parte segreta contiene l’entropia. Il server memorizza solo un digest SHA-256 della chiave e confronta il token presentato con un confronto a tempo costante, in modo che una chiave errata non riveli informazioni tramite i tempi di risposta. REST legge il token dall’intestazione Authorization: Bearer …; gRPC legge lo stesso token dai metadati di chiamata authorization. Il trasporto stdio MCP non ha alcuna chiave API perché è un sottoprocesso locale che il client di avvio considera attendibile. Il modello di autenticazione è documentato integralmente in Sicurezza e operazioni.

I quattro livelli di rischio

Ogni strumento dichiara uno dei quattro livelli di rischio ordinati, definiti dall’enumerazione RiskLevel in src/Config/RiskLevel.php.

Livello	Caso dell’enumerazione	Valore	Effetto
Safe	RiskLevel::Safe	0	Sola lettura, nessun effetto collaterale. Esecuzione automatica.
Caution	RiskLevel::Caution	1	Crea o modifica lo stato in memoria. Esecuzione automatica, registrata a fini di audit.
Review	RiskLevel::Review	2	Produce output che potrebbe essere usato impropriamente. Esecuzione automatica, registrata a fini di audit.
ApprovalRequired	RiskLevel::ApprovalRequired	3	Distruttivo, legale o critico per la privacy. Richiede la conferma umana.

Il rischio effettivo di uno strumento è determinato esattamente da due elementi: la dichiarazione riskLevel() dello strumento stesso e un override facoltativo della configurazione dell’operatore che può solo aumentare il rischio, senza mai abbassare quello di uno strumento ApprovalRequired. Vedere Livelli di rischio HITL e Configurazione.

Flusso dei token di approvazione

Quando uno strumento ApprovalRequired viene invocato senza un token valido, il ConfirmationGate (src/Mcp/ConfirmationGate.php) restituisce un token di verifica monouso anziché eseguire lo strumento. L’agente inoltra la verifica a una persona, quindi richiama lo stesso strumento con il token emesso nell’argomento _confirmation_token. Il token vincola il nome dello strumento, un nonce casuale e un time-to-live (TTL) di 300 secondi. Non vincola gli argomenti e non è una credenziale di autenticazione. Su REST, la chiave API Bearer autentica comunque la richiesta e lo stesso gate viene eseguito nell’esecutore di strumenti condiviso prima dell’operazione protetta. Su gRPC, lo stesso gate viene eseguito prima dell’operazione richiesta. Il meccanismo di verifica e token è identico tra i trasporti.

Strumenti ed endpoint

Le tabelle documentano ciascuno strumento con il nome registrato (colonna Simbolo) e la classe che lo implementa. Gli strumenti sono raggruppati per livello e categoria. Tutte le classi AST e di mutazione si trovano in src/Tools/Ast e src/Tools/Ast/Mutation; la classe di estrazione si trova in src/Tools/Extraction; le classi rimanenti si trovano in src/Tools/Core.

Strumenti di base per documenti

Simbolo	Parametri	Comportamento predefinito	Restituisce	Fallisce con	Note
create_pdf	page_size (impostazione predefinita A4), orientation (portrait/landscape), title, author; nessuno obbligatorio.	Crea un documento in memoria con una pagina; imposta i metadati quando forniti.	JSON con document_id, page_count, page_size, orientation.	Risultato di errore con il messaggio del motore se l’operazione non riesce.	Classe CreatePdfTool. Rischio RiskLevel::Caution. Livello core. Il valore document_id restituito viene usato da ogni operazione successiva.
add_page	document_id (obbligatorio), dimensione della pagina e orientamento facoltativi.	Aggiunge una pagina al documento.	JSON con il nuovo conteggio delle pagine.	Risultato di errore quando document_id è sconosciuto.	Classe AddPageTool. Rischio RiskLevel::Caution. Livello core.
add_text	document_id (obbligatorio), text (obbligatorio), posizione e stile facoltativi.	Aggiunge testo al documento.	Riepilogo JSON dello stato del documento.	Risultato di errore quando document_id è sconosciuto.	Classe AddTextTool. Rischio RiskLevel::Caution. Livello core.
add_image	document_id (obbligatorio), source (obbligatorio: percorso file o base64), posizionamento facoltativo.	Aggiunge un’immagine da un percorso o da dati base64.	Riepilogo JSON dello stato del documento.	Risultato di errore in caso di origine illeggibile o document_id sconosciuto.	Classe AddImageTool. Rischio RiskLevel::Caution. Livello core.
add_table	document_id (obbligatorio), html (obbligatorio).	Esegue il rendering di una tabella Hypertext Markup Language (HTML) nel documento.	Riepilogo JSON dello stato del documento.	Risultato di errore in caso di markup non valido o document_id sconosciuto.	Classe AddTableTool. Rischio RiskLevel::Caution. Livello core.
set_font	document_id (obbligatorio), family (obbligatorio), dimensione e stile facoltativi.	Imposta il font per le operazioni di testo successive.	Conferma JSON del font attivo.	Risultato di errore in caso di font o document_id sconosciuto.	Classe SetFontTool. Rischio RiskLevel::Caution. Livello core.
output_pdf	document_id (obbligatorio), file_path (facoltativo), destroy (impostazione predefinita true).	Finalizza il documento; scrive in file_path oppure restituisce base64 quando omesso; per impostazione predefinita elimina il documento.	JSON con file_path e file_size, oppure base64 e file_size.	Risultato di errore quando document_id è sconosciuto; errore di contenimento del percorso in caso di scrittura al di fuori della directory di base.	Classe OutputPdfTool. Rischio RiskLevel::ApprovalRequired. Livello core. La scrittura di un file passa attraverso il gate di conferma; la modalità base64 no.
preview_layout	document_id (obbligatorio).	Restituisce un riepilogo dell’impaginazione senza eseguire il rendering del PDF finale.	Riepilogo JSON dell’impaginazione.	Risultato di errore quando document_id è sconosciuto.	Classe PreviewLayoutTool. Rischio RiskLevel::Safe. Livello core.
parse_pdf	document_id (obbligatorio).	Ispeziona i metadati strutturali: conteggio delle pagine, font, immagini, cifratura e Info Dictionary.	Metadati strutturali JSON.	Risultato di errore in caso di documento non valido.	Classe ParsePdfTool. Rischio RiskLevel::Safe. Livello core. Registrato solo quando NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED è true o 1.

Strumenti di diagnostica di base

Simbolo	Parametri	Comportamento predefinito	Restituisce	Fallisce con	Note
diagnostic.doctor	nessuno.	Esegue un controllo di integrità e restituisce diagnostica strutturata dell’ambiente.	Report JSON dell’ambiente.	Risultato di errore se un controllo interno non riesce.	Classe DiagnosticDoctorTool. Rischio RiskLevel::Safe. Livello core. Non richiede alcun documento né conferma.
diagnostic.capabilities	nessuno.	Elenca le funzionalità, includendo livello e stato.	Elenco JSON delle funzionalità.	Risultato di errore in caso di esito negativo interno.	Classe DiagnosticCapabilitiesTool. Rischio RiskLevel::Safe. Livello core.
diagnostic.inspect	document_id (obbligatorio).	Ispeziona un PDF e restituisce i metadati strutturali.	Metadati strutturali JSON.	Risultato di errore quando document_id è sconosciuto.	Classe DiagnosticInspectTool. Rischio RiskLevel::Safe. Livello core.
diagnostic.verify	document_id (obbligatorio), profilo PDF/A o PDF/UA facoltativo.	Verifica l’integrità strutturale; facoltativamente convalida PDF/A o PDF/UA avviando un sottoprocesso VeraPDF.	Report JSON di verifica.	Risultato di errore in caso di esito negativo del sottoprocesso, timeout o input di dimensioni eccessive.	Classe DiagnosticVerifyTool. Rischio RiskLevel::Caution. Livello core. L’input è limitato a 50 mebibyte (MiB).

Strumento di base per codici a barre

Simbolo	Parametri	Comportamento predefinito	Restituisce	Fallisce con	Note
generate_barcode	payload (obbligatorio), format (ad esempio QR Code, DataMatrix).	Genera una matrice di moduli per codice a barre bidimensionale per il payload.	Matrice di moduli JSON.	Risultato di errore in caso di format non supportato o payload non valido.	Classe BarcodeTool. Rischio RiskLevel::Caution. Livello core. Il BarcodeTool si registra solo quando il registro di codificatori barcode di base è presente nel pacchetto nextpdf/core installato; il nome registrato dello strumento è generate_barcode.

Strumenti Enterprise per la privacy

Questi strumenti incapsulano le classi Enterprise per la privacy e vengono registrati nel livello Enterprise solo quando tali classi possono essere caricate automaticamente. Operano su contenuto in testo normale.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Fallisce con	Note
redact_pdf	content (obbligatorio), opzioni di rilevamento facoltative.	Espunge in modo distruttivo le informazioni personali (PII) nel contenuto in testo normale tramite il motore di espunzione Enterprise.	JSON con il contenuto espunto e un hash SHA-256.	Risultato di errore quando le classi Enterprise sono assenti o il rilevamento non riesce.	Classe RedactPdfTool. Rischio RiskLevel::Review. Livello enterprise.
deidentify_pdf	content (obbligatorio), strategy (espungere o eliminare).	Applica una strategia sistematica di anonimizzazione al contenuto in testo normale tramite l’anonimizzatore Enterprise.	JSON con il contenuto anonimizzato.	Risultato di errore quando le classi Enterprise sono assenti.	Classe DeIdentifyPdfTool. Rischio RiskLevel::Review. Livello enterprise.
zone_redact_pdf	content (obbligatorio), zones (pagina più elenco di rettangoli normalizzati).	Applica espunzioni per zone basate su coordinate tramite il motore di espunzione Enterprise.	JSON con il contenuto espunto.	Risultato di errore in caso di zona non valida o classi Enterprise assenti.	Classe ZoneRedactionTool. Rischio RiskLevel::Review. Livello enterprise.

Strumenti di lettura dell’albero della sintassi astratta (AST)

Questi strumenti sono forniti con il server, vengono registrati nel livello Pro e sono protetti da NEXTPDF_AST_TOOLS_ENABLED (abilitati per impostazione predefinita). Sono di sola lettura.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Fallisce con	Note
get_document_ast	pdf_data (obbligatorio).	Crea un AST semantico: un albero completo di nodi con ancore di citazione per ogni elemento strutturale.	Albero JSON di nodi più un ETag per il controllo della concorrenza.	Risultato di errore in caso di documento non valido.	Classe GetDocumentAstTool. Rischio RiskLevel::Safe. Livello pro.
get_ast_node	pdf_data (obbligatorio), node_id (obbligatorio).	Recupera un singolo nodo AST e tutti i relativi figli.	Nodo JSON con figli.	Risultato di errore in caso di node_id sconosciuto.	Classe GetAstNodeTool. Rischio RiskLevel::Safe. Livello pro.
get_ast_diff	original_pdf_data (obbligatorio), modified_pdf_data (obbligatorio).	Confronta strutturalmente due documenti confrontandone gli AST semantici.	Nodi JSON aggiunti, rimossi e modificati.	Risultato di errore in caso di documento di input non valido.	Classe GetAstDiffTool. Rischio RiskLevel::Safe. Livello pro.
search_ast_nodes	pdf_data (obbligatorio), tipo, indice di pagina e filtri di testo facoltativi.	Cerca nodi AST per tipo, indice di pagina o contenuto di testo.	Elenco JSON piatto di nodi corrispondenti con figli superficiali.	Risultato di errore in caso di documento non valido.	Classe SearchAstNodesTool. Rischio RiskLevel::Safe. Livello pro.
extract_cited_text	pdf_data (obbligatorio), headings_only facoltativo.	Estrae blocchi di testo con ancore di citazione (pagina, rettangolo di delimitazione, attendibilità).	Blocchi JSON di testo citato.	Risultato di errore in caso di documento non valido.	Classe ExtractCitedTextTool. Rischio RiskLevel::Safe. Livello pro. Categoria ast.
extract_cited_tables	pdf_data (obbligatorio).	Estrae blocchi di tabella con ancore di citazione; restituisce una matrice di celle ordinata per righe per ogni nodo Table.	Matrici JSON di tabella con ancore.	Risultato di errore in caso di documento non valido.	Classe ExtractCitedTablesTool. Rischio RiskLevel::Safe. Livello pro. Categoria extraction.

Strumenti di mutazione AST

Questi strumenti sono forniti con il server, vengono registrati nel livello Pro e sono protetti da NEXTPDF_MUTATION_TOOLS_ENABLED (abilitati per impostazione predefinita). Tutti e quattro sono ApprovalRequired e usano il controllo della concorrenza ottimistico (OCC) tramite un ETag.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Fallisce con	Note
apply_ast_mutations	pdf_data, etag, idempotency_key, mutations (tutti obbligatori).	Applica un batch di mutazioni in modo atomico; riutilizza il risultato memorizzato nella cache per un idempotency_key ripetuto.	JSON con il PDF mutato e un nuovo ETag.	Conflitto OCC quando l’ETag è obsoleto; errore di convalida in caso di mutazione non valida.	Classe ApplyAstMutationsTool. Rischio RiskLevel::ApprovalRequired. Livello pro.
delete_ast_node	pdf_data, node_id, etag (tutti obbligatori).	Rimuove un nodo in modalità overlay (il contenuto originale viene coperto, non eliminato fisicamente).	JSON con il PDF modificato e un nuovo ETag.	Conflitto OCC quando l’ETag è obsoleto; errore in caso di node_id sconosciuto.	Classe DeleteAstNodeTool. Rischio RiskLevel::ApprovalRequired. Livello pro.
insert_ast_node	pdf_data, parent_node_id, position, etag, node (tutti obbligatori).	Inserisce un nuovo nodo come figlio del nodo padre nella posizione indicata.	JSON con il PDF modificato e un nuovo ETag.	Conflitto OCC quando l’ETag è obsoleto; errore di convalida in caso di nodo non valido.	Classe InsertAstNodeTool. Rischio RiskLevel::ApprovalRequired. Livello pro.
update_ast_node	pdf_data, node_id, etag, updates (tutti obbligatori).	Aggiorna il contenuto di testo di un nodo.	JSON con il PDF modificato e un nuovo ETag.	Conflitto OCC quando l’ETag è obsoleto; errore in caso di node_id sconosciuto.	Classe UpdateAstNodeTool. Rischio RiskLevel::ApprovalRequired. Livello pro.

Schema di richiesta e risposta

Il trasporto gRPC definisce lo schema tipizzato del server nel pacchetto Protocol Buffers nextpdf.connect.v1, in proto/nextpdf/connect/v1/*.proto. Il servizio e i relativi messaggi sono i simboli canonici dello schema.

Servizio NextPDFConnect

Il servizio NextPDFConnect espone RPC unari e RPC con streaming dal server. I simboli dello schema sono i nomi dei metodi RPC e i messaggi di richiesta e risposta che essi veicolano.

RPC	Messaggio di richiesta	Messaggio di risposta	Forma
Render	RenderRequest	RenderResponse	Unario. Rendering sincrono senza stato.
RenderStream	RenderRequest	RenderChunk (stream)	Streaming dal server. Rendering consegnato come blocchi ordinati.
SubmitJob	SubmitJobRequest	JobResponse	Unario. Invia un processo di rendering asincrono.
GetJobStatus	GetJobStatusRequest	JobResponse	Unario. Esegue il polling dello stato del processo.
GetJobResult	GetJobResultRequest	RenderResponse	Unario. Scarica un risultato completato.
GetJobResultStream	GetJobResultRequest	RenderChunk (stream)	Streaming dal server. Scarica un risultato completato come blocchi.
CancelJob	CancelJobRequest	JobResponse	Unario. Annulla o elimina un processo.
CreateSession	CreateSessionRequest	SessionResponse	Unario. Crea una sessione di creazione documenti.
GetSession	GetSessionRequest	SessionResponse	Unario. Ottiene i metadati della sessione.
DestroySession	DestroySessionRequest	DestroySessionResponse	Unario. Elimina una sessione e il relativo documento.
SessionOperation	SessionOperationRequest	SessionResponse	Unario. Esegue un’operazione su un documento di sessione.
SessionRender	SessionRenderRequest	RenderResponse	Unario. Esegue il rendering di un documento di sessione in PDF.
SessionRenderStream	SessionRenderRequest	RenderChunk (stream)	Streaming dal server. Esegue il rendering di un documento di sessione come blocchi.
ExecuteCapability	CapabilityRequest	CapabilityResponse	Unario. Esegue un’operazione di funzionalità protetta per livello.
GetCapabilities	GetCapabilitiesRequest	GetCapabilitiesResponse	Unario. Elenca le funzionalità per il client autenticato.
HealthCheck	HealthCheckRequest	HealthCheckResponse	Unario. Probe di attività.
ReadinessCheck	ReadinessCheckRequest	ReadinessCheckResponse	Unario. Probe di idoneità.

Simboli dei messaggi

I messaggi di richiesta e risposta sono i simboli strutturali dello schema. I messaggi di rendering (RenderRequest, RenderResponse e lo streaming RenderChunk) veicolano la dimensione della pagina, l’orientamento, le operazioni ordinate e i byte PDF risultanti. I messaggi di processo (SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest e JobResponse) modellano il ciclo di vita del processo asincrono, con i metadati del processo contenuti nel messaggio JobData. I messaggi di sessione (CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest e SessionRenderRequest) modellano il ciclo di vita della sessione con stato, con i metadati della sessione contenuti nel messaggio SessionData. I messaggi di funzionalità (CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest e GetCapabilitiesResponse) veicolano l’invio e l’introspezione delle operazioni protette per livello. I messaggi di sistema (HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest e ReadinessCheckResponse) veicolano lo stato di attività e idoneità.

I file .proto forniti sono il contratto di trasmissione di riferimento; il riferimento del trasporto gRPC è in Trasporto gRPC.

Modello di errore

Il server segnala gli esiti negativi con il meccanismo di errore nativo di ciascun trasporto. Ogni trasporto mantiene la stessa condizione logica; cambia solo la codifica.

MCP

Gli errori MCP sono oggetti di errore JSON-RPC 2.0. Un metodo sconosciuto restituisce method-not-found (-32601); un messaggio non valido come JSON-RPC restituisce invalid-request (-32600); un input non analizzabile restituisce parse-error (-32700). Uno strumento che fallisce restituisce una risposta JSON-RPC riuscita con contenuto che segnala l’errore, anziché un errore a livello di trasporto, in modo che l’agente possa leggere il messaggio. Una verifica di conferma per uno strumento ApprovalRequired è anch’essa una risposta riuscita, non un errore.

REST

REST usa codici di stato Hypertext Transfer Protocol (HTTP) con la semantica definita da RFC 9110. Un 200 veicola il risultato; un 400 viene restituito quando un campo della richiesta non supera la convalida del formato; un 401 viene restituito quando non viene presentata alcuna chiave API valida e veicola l’intestazione WWW-Authenticate: Bearer; un 403 viene restituito quando il livello di una chiave valida non è autorizzato per l’operazione; un 404 viene restituito quando una route protetta per livello non è registrata perché il relativo pacchetto è assente. I corpi di errore leggibili dalla macchina sono documenti Problem Details secondo RFC 9457, serviti con il tipo di supporto application/problem+json e un type Uniform Resource Identifier (URI) stabile per ogni condizione. Gli esiti negativi della convalida a livello di campo sono elencati nel corpo. Come misura di protezione contro il path traversal, un document_id che non corrisponde al pattern doc_[a-f0-9]{24} viene rifiutato con 400 prima dell’esecuzione dello strumento. La pipeline middleware REST e la tabella delle route sono documentate in Trasporto REST.

gRPC

gRPC usa codici di stato gRPC standard. Un token mancante, non valido, sconosciuto, disabilitato o scaduto fa fallire la chiamata con UNAUTHENTICATED anziché con uno stato HTTP. Il dettaglio avanzato dell’errore rispecchia la forma Problem Details di REST ed è veicolato nei dettagli di stato gRPC, in modo che l’URI type dell’errore sia coerente tra i trasporti.

Vedere anche: RFC 9110 (HTTP Semantics) per la semantica dei codici di stato e RFC 9457 (Problem Details for HTTP APIs) per il formato del corpo di errore.

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

Limiti di frequenza e quote

Il trasporto REST applica la limitazione di frequenza per indirizzo Internet Protocol (per-IP) e per client nella sua pipeline middleware, oltre ai limiti di dimensione del corpo e di payload per livello e a un timeout per richiesta. I limiti massimi pertinenti sono valori di configurazione, non costanti hardcoded:

• I limiti massimi di payload per livello (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit) e i timeout corrispondenti si applicano a REST in base al livello della chiave autenticata. Vedere Configurazione.
• L’archivio in memoria dei documenti è limitato da max_documents (impostazione predefinita 50) e document_ttl (impostazione predefinita 1800 secondi).
• Lo stato di limite di frequenza e di idempotenza è per worker, a meno che NEXTPDF_REDIS_HOST non sia configurato per un archivio condiviso. Vedere Distribuzione.

Quando gli archivi di limite di frequenza e idempotenza sono condivisi, gli invii ripetuti e identici di processi asincroni vengono deduplicati in base a idempotency_key. Il trasporto MCP gestisce una richiesta alla volta sulle pipe e deduplica un id di richiesta ripetuto usando un buffer di 64 voci anziché applicare limiti di frequenza di rete.

Note di sviluppo

• Leggere i nomi degli strumenti, le classi e i livelli di rischio dal codice sorgente in src/Tools/; non presupporre un totale fisso. Interrogare il server in esecuzione per il conteggio autorevole, come illustrato in Catalogo degli strumenti.
• Rigenerare gli stub client gRPC dai file proto/nextpdf/connect/v1/*.proto forniti; il pacchetto e il namespace sono nextpdf.connect.v1. Non modificare manualmente le classi di messaggio generate.
• Uno strumento ApprovalRequired risponde con una verifica di conferma alla prima chiamata. Creare il percorso di nuovo tentativo (inoltrare la verifica, quindi richiamare nuovamente con _confirmation_token) prima di distribuire un’integrazione che usa output_pdf o qualsiasi strumento di mutazione.
• Una route o funzionalità protetta per livello che non è installata non indica un errore di autenticazione: REST restituisce 404 per una route assente e gRPC ExecuteCapability segnala l’operazione come non disponibile. Considerare un livello Pro o Enterprise assente come caso previsto, non come errore.
• Tenere le chiavi API fuori dal controllo del codice sorgente; montarle da un file di segreti e preferire l’archivio di chiavi su file con ricaricamento a caldo, in modo che la rotazione non richieda alcun riavvio. Vedere Sicurezza e operazioni.

Vedere anche

• Guida per gli sviluppatori: architettura, ciclo di vita, punti di estensione e checklist di test
• Catalogo degli strumenti: l’insieme verificato di strumenti di base e il conteggio di runtime
• Livelli di rischio HITL: il modello di rischio e la verifica di conferma
• Trasporto MCP · Trasporto REST · Trasporto gRPC: dettagli di trasmissione per ciascun trasporto
• Sicurezza e operazioni: il modello di minaccia, la sicurezza dei trasporti e l’autenticazione