NextPDF Connect API başvurusu

Genel bakış

Bu sayfa, NextPDF Connect sunucusu (nextpdf/server) için simge düzeyinde başvuru niteliğindedir. Her aracı kayıtlı araç adı ve uygulayan sınıfıyla listeler; ayrıca NextPDFConnect gRPC hizmetini, uzaktan yordam çağrısı (RPC) yöntemleri ile istek ve yanıt mesajları dahil olmak üzere belgeler. Her aktarım katmanının paylaştığı kimlik doğrulama, hata ve hız sınırı sözleşmesini de tanımlar.

Sunucu, tek bir araç kayıt defterini üç aktarım katmanı üzerinden sunar: standart giriş/çıkış üzerinden Model Context Protocol (MCP), Representational State Transfer (REST) tabanlı bir uygulama programlama arayüzü (API) ve gRPC. Her aktarım katmanının ağ ayrıntıları ayrı bir sayfada belgelenir: bk. MCP aktarımı, REST aktarımı ve gRPC aktarımı. Bu sayfa, söz konusu aktarım katmanlarının taşıdığı simgeleri kataloglar.

Araç adları, sınıflar ve risk katmanları, src/Tools/ içindeki araç uygulamalarından okunur. Bir dağıtımın sunduğu araç sayısı çalışma zamanında belirlenir; bk. Araç kataloğu. Başlatma ve keşif katman çözümlemesini açıklar.

Aktarım katmanı kullanılabilirliği

Bir araç, dağıtımın çalıştırdığı her aktarım katmanında kullanılabilir. Aktarım katmanları bağımsız işlemler olarak çalışır; birini başlatmak diğerlerini başlatmaz.

Aktarım katmanı	Giriş noktası	Ağ biçimi	Kimlik doğrulama
MCP	bin/nextpdf-mcp	Standart giriş/çıkış üzerinden JavaScript Object Notation uzaktan yordam çağrısı (JSON-RPC) 2.0	İşletim sistemi işlem sınırı (API anahtarı yok)
REST	bin/nextpdf-server	HTTP, OpenAPI 3.1	Bearer API anahtarı, Authorization üst bilgisinde
gRPC	bin/nextpdf-grpc	Protocol Buffers, nextpdf.connect.v1 paketi	authorization çağrı meta verisinde Bearer belirteci

MCP üzerinden bir aracı tools/call ve kayıtlı araç adıyla çağırırsınız. REST ve gRPC üzerinden aynı motor yeteneklerine işleme, işlem ve yetenek yüzeyleri aracılığıyla erişirsiniz; bk. REST aktarımı rota tablosu ve gRPC aktarımı RPC tablosu.

Kimlik doğrulama ve risk katmanı

API anahtarıyla kimlik doğrulama

REST ve gRPC aktarım katmanları, kimlik doğrulaması yapılmamış sağlık yoklamaları dışında her istekte bir Bearer API anahtarı gerektirir. Bir anahtar npk_live_{kid}_{secret} biçimindedir: kid, kayıt aramaya yönelik sekiz karakterlik bir tanımlayıcıdır; gizli bölüm ise entropiyi taşır. Sunucu, anahtarın yalnızca bir SHA-256 özetini saklar ve sunulan belirteci sabit sürede karşılaştırır; böylece geçersiz bir anahtar zamanlama üzerinden hiçbir şey açığa çıkarmaz. REST, belirteci Authorization: Bearer … üst bilgisinden okur; gRPC aynı belirteci authorization çağrı meta verisinden okur. MCP’nin standart giriş/çıkış aktarım katmanında API anahtarı yoktur; çünkü bu katman, kendisini başlatan istemci tarafından güvenilen yerel bir alt süreçtir. Güvenlik ve operasyonlar tam kimlik doğrulama modelini belgeler.

Dört risk katmanı

Her araç, RiskLevel sabit listesinde (src/Config/RiskLevel.php) tanımlanan, sıralı dört risk düzeyinden birini bildirir.

Katman	Sabit liste değeri	Değer	Etki
Safe	RiskLevel::Safe	0	Salt okunurdur; yan etkisi yoktur. Otomatik çalışır.
Caution	RiskLevel::Caution	1	Bellek içi durum oluşturur veya değiştirir. Otomatik çalışır ve denetim günlüğüne kaydedilir.
Review	RiskLevel::Review	2	Kötüye kullanılabilecek çıktı üretir. Otomatik çalışır ve denetim günlüğüne kaydedilir.
ApprovalRequired	RiskLevel::ApprovalRequired	3	Yıkıcı, hukuki açıdan önemli veya gizlilik açısından kritiktir. İnsan onayı gerektirir.

Bir aracın etkin riskini yalnızca iki kaynak belirler: aracın kendi riskLevel() bildirimi ve operatör yapılandırmasındaki isteğe bağlı geçersiz kılma. Bu geçersiz kılma riski yalnızca yükseltebilir; bir ApprovalRequired aracının riskini asla düşüremez. HITL risk katmanları ve Yapılandırma bölümlerine bakın.

Onay belirteçleri nasıl işler

Geçerli bir belirteç olmadan bir ApprovalRequired aracını çağırdığınızda, ConfirmationGate (src/Mcp/ConfirmationGate.php) aracı çalıştırmak yerine tek kullanımlık bir doğrulama belirteci döndürür. Çağıran taraf doğrulama isteğini bir insana iletir, ardından verilen belirteci _confirmation_token bağımsız değişkeninde geçirerek aynı aracı yeniden çağırır. Belirteç, araç adını, rastgele bir tek seferlik değeri (nonce) ve 300 saniyelik yaşam süresini (TTL) bağlar. Bağımsız değişkenleri bağlamaz ve bir kimlik doğrulama kimlik bilgisi değildir. REST’te isteği yine de Bearer API anahtarı doğrular ve aynı geçit, korunan işlemden önce paylaşılan araç yürütücüsünde çalışır. gRPC’de aynı geçit, sevk edilen işlemden önce çalışır. Doğrulama isteği ve belirteç mekanizması tüm aktarım katmanlarında aynıdır.

Araçlar ve uç noktalar

Tablo, her aracı kayıtlı araç adı (Simge sütunu) ve uygulayan sınıfıyla birlikte belgeler. Araçlar katman ve kategoriye göre gruplanır. Tüm soyut sözdizimi ağacı (AST) ve mutasyon sınıfları src/Tools/Ast ve src/Tools/Ast/Mutation altında yer alır; ayıklama sınıfı src/Tools/Extraction altında bulunur; kalan sınıflar src/Tools/Core altında yer alır.

Çekirdek belge araçları

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
create_pdf	page_size (varsayılan A4), orientation (portrait/landscape), title, author; hiçbiri zorunlu değil.	Bellek içinde bir belge ve sayfa oluşturur; sağlandığında meta verileri ayarlar.	Şunları içeren JSON: document_id, page_count, page_size, orientation.	Başarısızlık durumunda motor mesajını içeren hata sonucu döndürür.	Sınıf CreatePdfTool. Risk RiskLevel::Caution. Katman: core. Döndürülen document_id sonraki her işlemi besler.
add_page	document_id (zorunlu), isteğe bağlı sayfa boyutu ve yönü.	Belgeye bir sayfa ekler.	Yeni sayfa sayısını içeren JSON.	Bilinmeyen bir document_id olduğunda hata sonucu.	Sınıf AddPageTool. Risk RiskLevel::Caution. Katman: core.
add_text	document_id (zorunlu), text (zorunlu), isteğe bağlı konum ve stil.	Belgeye metin ekler.	JSON belge durumu özeti.	Bilinmeyen bir document_id olduğunda hata sonucu.	Sınıf AddTextTool. Risk RiskLevel::Caution. Katman: core.
add_image	document_id (zorunlu), source (zorunlu: dosya yolu veya base64), isteğe bağlı yerleşim.	Bir dosya yolundan veya base64 verisinden görüntü ekler.	JSON belge durumu özeti.	Kaynak okunamıyorsa veya document_id bilinmiyorsa hata sonucu.	Sınıf AddImageTool. Risk RiskLevel::Caution. Katman: core.
add_table	document_id (zorunlu), html (zorunlu).	Bir Hyper Text Markup Language (HTML) tablosunu belgeye işler.	JSON belge durumu özeti.	Biçimlendirme geçersizse veya document_id bilinmiyorsa hata sonucu.	Sınıf AddTableTool. Risk RiskLevel::Caution. Katman: core.
set_font	document_id (zorunlu), family (zorunlu), isteğe bağlı boyut ve stil.	Sonraki metin işlemleri için yazı tipini ayarlar.	Etkin yazı tipinin JSON onayı.	Yazı tipi veya document_id bilinmiyorsa hata sonucu.	Sınıf SetFontTool. Risk RiskLevel::Caution. Katman: core.
output_pdf	document_id (zorunlu), file_path (isteğe bağlı), destroy (varsayılan true).	Belgeyi sonlandırır; file_path yoluna yazar veya bu atlandığında base64 döndürür; varsayılan olarak belgeyi yok eder.	Şunları içeren JSON: file_path ve file_size ya da base64 ve file_size.	Bilinmeyen bir document_id olduğunda hata sonucu; temel dizinin dışına yazılırken yol kapsama hatası.	Sınıf OutputPdfTool. Risk RiskLevel::ApprovalRequired. Katman: core. Dosya yazma işlemi doğrulama geçidinden geçer; base64 modu geçmez.
preview_layout	document_id (zorunlu).	Son PDF’i işlemeden bir yerleşim özeti döndürür.	JSON yerleşim özeti.	Bilinmeyen bir document_id olduğunda hata sonucu.	Sınıf PreviewLayoutTool. Risk RiskLevel::Safe. Katman: core.
parse_pdf	document_id (zorunlu).	Yapısal meta verileri inceler: sayfa sayısı, yazı tipleri, görüntüler, şifreleme ve Bilgi sözlüğü.	JSON yapısal meta veri.	Belge bozuksa hata sonucu.	Sınıf ParsePdfTool. Risk RiskLevel::Safe. Katman: core. Yalnızca NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED değeri true veya 1 olduğunda kaydolur.

Çekirdek tanılama araçları

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
diagnostic.doctor	yok.	Bir sağlık denetimi çalıştırır ve yapılandırılmış ortam tanılamalarını döndürür.	JSON ortam raporu.	Dahili bir denetim hatasında hata sonucu.	Sınıf DiagnosticDoctorTool. Risk RiskLevel::Safe. Katman: core. Belge veya doğrulama gerektirmez.
diagnostic.capabilities	yok.	Yetenekleri katman ve durum bilgisiyle listeler.	JSON yetenek listesi.	Dahili bir hatada hata sonucu.	Sınıf DiagnosticCapabilitiesTool. Risk RiskLevel::Safe. Katman: core.
diagnostic.inspect	document_id (zorunlu).	Bir PDF’i inceler ve yapısal meta veriler döndürür.	JSON yapısal meta veri.	Bilinmeyen bir document_id olduğunda hata sonucu.	Sınıf DiagnosticInspectTool. Risk RiskLevel::Safe. Katman: core.
diagnostic.verify	document_id (zorunlu), isteğe bağlı PDF/A veya PDF/UA profili.	Yapısal bütünlüğü doğrular; isteğe bağlı olarak bir VeraPDF alt süreci başlatarak PDF/A veya PDF/UA doğrulaması yapar.	JSON doğrulama raporu.	Alt süreç hatasında, zaman aşımında veya aşırı boyutlu girişte hata sonucu.	Sınıf DiagnosticVerifyTool. Risk RiskLevel::Caution. Katman: core. Giriş 50 mebibayt (MiB) ile sınırlandırılmıştır.

Çekirdek barkod aracı

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
generate_barcode	payload (zorunlu), format (örneğin QR Code, DataMatrix).	Yükten iki boyutlu bir barkod modül matrisi oluşturur.	JSON modül matrisi.	Desteklenmeyen bir format değeri veya geçersiz yük olduğunda hata sonucu.	Sınıf BarcodeTool. Risk RiskLevel::Caution. Katman: core. BarcodeTool, yalnızca çekirdek barcode kodlayıcı kayıt defteri, kurulu nextpdf/core içinde mevcut olduğunda kaydolur; kayıtlı araç adı generate_barcode şeklindedir.

Enterprise gizlilik araçları

Bu araçlar, Enterprise gizlilik sınıflarını sarmalar ve yalnızca bu sınıflar otomatik yüklenebilir olduğunda Enterprise katmanı altında kaydolur. Düz metin içeriği üzerinde çalışırlar.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
redact_pdf	content (zorunlu), isteğe bağlı algılama seçenekleri.	Enterprise redaksiyon motorunu kullanarak düz metin içeriğindeki kişisel olarak tanımlanabilir bilgileri (PII) geri alınamaz biçimde redakte eder.	Redakte edilmiş içeriği ve bir SHA-256 karmasını içeren JSON.	Enterprise sınıfları yoksa veya algılama başarısız olursa hata sonucu.	Sınıf RedactPdfTool. Risk RiskLevel::Review. Katman: enterprise.
deidentify_pdf	content (zorunlu), strategy (redact veya suppress).	Enterprise kimliksizleştiricisini kullanarak düz metin içeriğine sistematik bir kimliksizleştirme stratejisi uygular.	Kimliksizleştirilmiş içeriği içeren JSON.	Enterprise sınıfları yoksa hata sonucu.	Sınıf DeIdentifyPdfTool. Risk RiskLevel::Review. Katman: enterprise.
zone_redact_pdf	content (zorunlu), zones (sayfaya göre normalleştirilmiş dikdörtgen listesi).	Enterprise redaksiyon motorunu kullanarak koordinat tabanlı bölge redaksiyonları uygular.	Redakte edilmiş içeriği içeren JSON.	Bir bölge geçersizse veya Enterprise sınıfları yoksa hata sonucu.	Sınıf ZoneRedactionTool. Risk RiskLevel::Review. Katman: enterprise.

Soyut sözdizimi ağacı (AST) okuma araçları

Bu araçlar sunucuyla birlikte gelir, Pro katmanı altında kaydolur ve NEXTPDF_AST_TOOLS_ENABLED ile denetlenir (varsayılan olarak etkin). Salt okunurdur.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
get_document_ast	pdf_data (zorunlu).	Anlamsal bir AST oluşturur: her yapısal öğe için alıntı bağlantı noktaları içeren eksiksiz bir düğüm ağacı.	Eşzamanlılık denetimi için bir ETag ile birlikte JSON düğüm ağacı.	Belge bozuksa hata sonucu.	Sınıf GetDocumentAstTool. Risk RiskLevel::Safe. Katman: pro.
get_ast_node	pdf_data (zorunlu), node_id (zorunlu).	Tek bir AST düğümünü tüm alt düğümleriyle birlikte alır.	Alt düğümleriyle birlikte JSON düğümü.	Bilinmeyen bir node_id olduğunda hata sonucu.	Sınıf GetAstNodeTool. Risk RiskLevel::Safe. Katman: pro.
get_ast_diff	original_pdf_data (zorunlu), modified_pdf_data (zorunlu).	İki belgenin anlamsal AST’lerini karşılaştırarak yapısal farkı alır.	Eklenen, kaldırılan ve değiştirilen düğümleri içeren JSON.	Giriş belgesi bozuksa hata sonucu.	Sınıf GetAstDiffTool. Risk RiskLevel::Safe. Katman: pro.
search_ast_nodes	pdf_data (zorunlu), isteğe bağlı tür, sayfa dizini ve metin filtreleri.	AST düğümlerini tür, sayfa dizini veya metin içeriğine göre arar.	Eşleşen düğümlerin sığ alt düğümleriyle birlikte düz JSON listesi.	Belge bozuksa hata sonucu.	Sınıf SearchAstNodesTool. Risk RiskLevel::Safe. Katman: pro.
extract_cited_text	pdf_data (zorunlu), isteğe bağlı headings_only.	Metin bloklarını alıntı bağlantı noktalarıyla (sayfa, sınırlayıcı kutu, güven) ayıklar.	JSON alıntılı metin blokları.	Belge bozuksa hata sonucu.	Sınıf ExtractCitedTextTool. Risk RiskLevel::Safe. Katman: pro. Kategori: ast.
extract_cited_tables	pdf_data (zorunlu).	Tablo bloklarını alıntı bağlantı noktalarıyla ayıklar; her Table düğümü için satır öncelikli bir hücre matrisi döndürür.	Bağlantı noktalarıyla JSON tablo matrisleri.	Belge bozuksa hata sonucu.	Sınıf ExtractCitedTablesTool. Risk RiskLevel::Safe. Katman: pro. Kategori: extraction.

AST mutasyon araçları

Bu araçlar sunucuyla birlikte gelir, Pro katmanı altında kaydolur ve NEXTPDF_MUTATION_TOOLS_ENABLED ile denetlenir (varsayılan olarak etkin). Dördü de ApprovalRequired niteliğindedir ve bir ETag üzerinden iyimser eşzamanlılık denetimi (OCC) kullanır.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
apply_ast_mutations	pdf_data, etag, idempotency_key, mutations (tümü zorunlu).	Bir mutasyon yığınını atomik olarak uygular; yinelenen bir idempotency_key için önbelleğe alınmış sonucu yeniden oynatır.	Mutasyona uğramış PDF’i ve yeni bir ETag’i içeren JSON.	ETag eskiyse OCC çakışması; mutasyon bozuksa doğrulama hatası.	Sınıf ApplyAstMutationsTool. Risk RiskLevel::ApprovalRequired. Katman: pro.
delete_ast_node	pdf_data, node_id, etag (tümü zorunlu).	Bir düğümü kaplama modunda kaldırır (özgün içeriğin üzeri örtülür, fiziksel olarak silinmez).	Değiştirilmiş PDF’i ve yeni bir ETag’i içeren JSON.	ETag eskiyse OCC çakışması; bilinmeyen bir node_id olduğunda hata.	Sınıf DeleteAstNodeTool. Risk RiskLevel::ApprovalRequired. Katman: pro.
insert_ast_node	pdf_data, parent_node_id, position, etag, node (tümü zorunlu).	Belirtilen konumda, üst düğümün altına yeni bir düğüm ekler.	Değiştirilmiş PDF’i ve yeni bir ETag’i içeren JSON.	ETag eskiyse OCC çakışması; düğüm bozuksa doğrulama hatası.	Sınıf InsertAstNodeTool. Risk RiskLevel::ApprovalRequired. Katman: pro.
update_ast_node	pdf_data, node_id, etag, updates (tümü zorunlu).	Bir düğümün metin içeriğini günceller.	Değiştirilmiş PDF’i ve yeni bir ETag’i içeren JSON.	ETag eskiyse OCC çakışması; bilinmeyen bir node_id olduğunda hata.	Sınıf UpdateAstNodeTool. Risk RiskLevel::ApprovalRequired. Katman: pro.

İstek ve yanıt şeması

gRPC aktarım katmanı, sunucunun tiplendirilmiş şemasını nextpdf.connect.v1 Protocol Buffers paketinde, proto/nextpdf/connect/v1/*.proto içinde tanımlar. Hizmet ve mesajlar, kanonik şema simgeleridir.

Hizmet NextPDFConnect

Hizmet NextPDFConnect, tekli (unary) ve sunucu akışlı RPC’leri sunar. Şema simgeleri, RPC yöntem adları ile bunların taşıdığı istek ve yanıt mesajlarıdır.

RPC	İstek mesajı	Yanıt mesajı	Biçim
Render	RenderRequest	RenderResponse	Tekli. Eşzamanlı, durumsuz işleme.
RenderStream	RenderRequest	RenderChunk (akış)	Sunucu akışlı. İşlenmiş çıktı, sıralı yığınlar olarak teslim edilir.
SubmitJob	SubmitJobRequest	JobResponse	Tekli. Eşzamansız bir işleme işi gönderir.
GetJobStatus	GetJobStatusRequest	JobResponse	Tekli. İş durumunu yoklar.
GetJobResult	GetJobResultRequest	RenderResponse	Tekli. Tamamlanmış bir sonucu indirir.
GetJobResultStream	GetJobResultRequest	RenderChunk (akış)	Sunucu akışlı. Tamamlanmış bir sonucu yığınlar halinde indirir.
CancelJob	CancelJobRequest	JobResponse	Tekli. Bir işi iptal eder veya siler.
CreateSession	CreateSessionRequest	SessionResponse	Tekli. Belge oluşturma oturumu oluşturur.
GetSession	GetSessionRequest	SessionResponse	Tekli. Oturum meta verilerini alır.
DestroySession	DestroySessionRequest	DestroySessionResponse	Tekli. Bir oturumu ve belgesini yok eder.
SessionOperation	SessionOperationRequest	SessionResponse	Tekli. Bir oturum belgesinde bir işlem yürütür.
SessionRender	SessionRenderRequest	RenderResponse	Tekli. Bir oturum belgesini PDF olarak işler.
SessionRenderStream	SessionRenderRequest	RenderChunk (akış)	Sunucu akışlı. Bir oturum belgesini yığınlar halinde işler.
ExecuteCapability	CapabilityRequest	CapabilityResponse	Tekli. Katmana bağlı bir yetenek işlemi yürütür.
GetCapabilities	GetCapabilitiesRequest	GetCapabilitiesResponse	Tekli. Kimliği doğrulanmış istemci için yetenekleri listeler.
HealthCheck	HealthCheckRequest	HealthCheckResponse	Tekli. Canlılık yoklaması.
ReadinessCheck	ReadinessCheckRequest	ReadinessCheckResponse	Tekli. Hazır olma yoklaması.

Mesaj simgeleri

İstek ve yanıt mesajları, şemanın yapısal simgeleridir. İşleme mesajları olan RenderRequest, RenderResponse ve akışlı RenderChunk, sayfa boyutunu, yönü, sıralı işlemleri ve üretilen PDF baytlarını taşır. İş mesajları olan SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest ve JobResponse, eşzamansız iş yaşam döngüsünü JobData mesajında tutulan iş meta verileriyle modeller. Oturum mesajları olan CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest ve SessionRenderRequest, durumlu oturum yaşam döngüsünü SessionData mesajında tutulan oturum meta verileriyle modeller. Yetenek mesajları olan CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest ve GetCapabilitiesResponse, katmana bağlı işlem sevkini ve iç gözlemi taşır. Sistem mesajları olan HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest ve ReadinessCheckResponse, canlılık ve hazır olma durumunu taşır.

Birlikte gönderilen .proto dosyaları, geçerli ağ sözleşmesini oluşturur; gRPC aktarımı bölümündeki gRPC aktarım başvuru kılavuzuna bakın.

Hata modeli

Sunucu, başarısızlıkları her aktarım katmanının yerel hata mekanizmasıyla bildirir. Her aktarım katmanı aynı mantıksal durumu korur; yalnızca kodlama biçimi farklıdır.

MCP

MCP hataları, JSON-RPC 2.0 hata nesneleridir. Bilinmeyen bir yöntem, yöntem bulunamadı (-32601) sonucunu döndürür; geçerli bir JSON-RPC mesajı olmayan bir giriş, geçersiz istek (-32600) sonucunu döndürür; ayrıştırılamayan giriş, ayrıştırma hatası (-32700) sonucunu döndürür. Başarısız olan bir araç, aktarım düzeyinde bir hata yerine içeriği hatayı işaretleyen başarılı bir JSON-RPC yanıtı döndürür; böylece aracı mesajı okuyabilir. Bir ApprovalRequired aracı için doğrulama isteği de hata değil, başarılı bir yanıttır.

REST

REST, anlamları RFC 9110 ile tanımlanan Hyper Text Transfer Protocol (HTTP) durum kodlarını kullanır. Bir 200 yanıtı sonucu taşır; istek alanlarından biri biçim doğrulamasından geçemezse 400 döndürülür; geçerli bir API anahtarı sunulmadığında 401 döndürülür ve WWW-Authenticate: Bearer doğrulama isteği üst bilgisini taşır; geçerli anahtarın katmanı işlemi yürütmeye yetkili değilse 403 döndürülür; katmana bağlı bir rota, paketi bulunmadığı için kayıtlı değilse 404 döndürülür. Makine tarafından okunabilir hata gövdeleri, RFC 9457 uyarınca Problem Details belgeleri biçimindedir; application/problem+json ortam türüyle ve her durum için kararlı bir type tekdüzen kaynak tanımlayıcısı (URI) ile sunulur. Alan düzeyindeki doğrulama hataları gövdede listelenir. Yol geçişine karşı bir sertleştirme önlemi olarak, document_id deseni doc_[a-f0-9]{24} ile eşleşmiyorsa, araç çalışmadan önce 400 ile reddedilir. REST aktarımı REST ara katman işlem hattını ve rota tablosunu belgeler.

gRPC

gRPC, standart gRPC durum kodlarını kullanır. Eksik, bozuk, bilinmeyen, devre dışı bırakılmış veya süresi dolmuş bir belirteç, çağrıyı HTTP durumu yerine UNAUTHENTICATED ile başarısız kılar. Ayrıntılı hata bilgisi, REST’teki Problem Details biçimini yansıtır ve gRPC durum ayrıntılarında taşınır; böylece hata type URI’si aktarım katmanları arasında tutarlı kalır.

Durum kodlarının anlamları için ayrıca RFC 9110 (HTTP Semantics) bölümüne ve hata gövdesi biçimi için RFC 9457 (Problem Details for HTTP APIs) bölümüne bakın.

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

Hız sınırları ve kotalar

REST aktarım katmanı, ara katman işlem hattında İnternet Protokolü (IP) adresi başına ve istemci başına hız sınırlamasının yanı sıra gövde boyutu, katman yükü sınırları ve istek başına zaman aşımı uygular. Bu sınırlar, sabit kodlanmış sabitler değil, yapılandırma değerleridir:

• Katman başına yük üst sınırları (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit) ve bunlara karşılık gelen zaman aşımları, kimliği doğrulanmış anahtarın katmanına göre REST’te geçerlidir. Yapılandırma bölümüne bakın.
• Bellek içi belge deposu max_documents (varsayılan 50) ve document_ttl (varsayılan 1800 saniye) ile sınırlandırılmıştır.
• Paylaşılan bir depo için NEXTPDF_REDIS_HOST yapılandırılmadığı sürece hız sınırı ve idempotentlik durumu çalışan başına tutulur. Dağıtım bölümüne bakın.

Hız sınırı ve idempotentlik depoları paylaşıldığında, aynı eşzamansız işin yinelenen gönderimleri idempotency_key ile yinelemeden arındırılır. MCP aktarım katmanı, kanallar üzerinden tek seferde bir isteği işler ve ağ hız sınırları uygulamak yerine yinelenen bir istek id değerini 64 girişlik bir arabellek kullanarak yinelemeden arındırır.

Geliştirme notları

• Araç adlarını, sınıfları ve risk katmanlarını src/Tools/ altındaki kaynaktan okuyun; sabit bir toplam varsaymayın. Araç kataloğu bölümünde gösterildiği gibi, kesin sayı için çalışan sunucuyu sorgulayın.
• gRPC istemci taslaklarını, birlikte gönderilen proto/nextpdf/connect/v1/*.proto dosyalarından yeniden oluşturun; paket ve ad alanı nextpdf.connect.v1 şeklindedir. Oluşturulan mesaj sınıflarını elle düzenlemeyin.
• Bir ApprovalRequired aracı, ilk çağrıda bir doğrulama isteğiyle yanıt verir. Yeniden deneme yolunu oluşturun: doğrulama isteğini iletin, ardından _confirmation_token ile yeniden çağırın; bunu output_pdf veya herhangi bir mutasyon aracını yöneten bir entegrasyonu yayına almadan önce yapın.
• Kurulu olmayan, katmana bağlı bir rota veya yetenek bir kimlik doğrulama hatası değildir: REST, bulunmayan bir rota için 404 döndürür ve gRPC ExecuteCapability işlemini kullanılamaz olarak bildirir. Eksik bir Pro veya Enterprise katmanını arıza değil, beklenen bir durum olarak değerlendirin.
• API anahtarlarını sürüm denetiminin dışında tutun; bunları bir gizli dosyadan bağlayın ve döndürme işleminin yeniden başlatma gerektirmemesi için anında yeniden yükleme yapabilen dosya anahtarı deposunu tercih edin. Güvenlik ve operasyonlar bölümüne bakın.

Ayrıca bkz.

• Geliştirici kılavuzu — mimari, yaşam döngüsü, genişletme noktaları ve test denetim listesi
• Araç kataloğu — doğrulanmış çekirdek araç kümesi ve çalışma zamanı sayısı
• HITL risk katmanları — risk modeli ve doğrulama isteği
• MCP aktarımı · REST aktarımı · gRPC aktarımı — aktarım katmanı başına ağ ayrıntıları
• Güvenlik ve operasyonlar — kimlik doğrulama, aktarım güvenliği ve tehdit modeli