NextPDF Connect API 레퍼런스
한눈에 보기
섹션 제목: “한눈에 보기”이 페이지는 NextPDF Connect 서버(nextpdf/server)의 심볼 수준 레퍼런스입니다. 모든 도구를 등록된 도구 이름과 구현 클래스로 나열하고, gRPC 서비스 NextPDFConnect와 해당 원격 프로시저 호출(RPC) 메서드 및 요청·응답 메시지를 문서화합니다. 모든 전송 계층이 공유하는 인증, 오류, 속도 제한 계약도 명시합니다.
서버는 하나의 도구 레지스트리를 표준 입력 및 출력을 통한 Model Context Protocol(MCP), 표현 상태 전송(REST) 애플리케이션 프로그래밍 인터페이스(API), gRPC라는 세 가지 전송 계층으로 노출합니다. 각 전송 계층의 와이어 수준 세부 사항은 해당 페이지에서 설명합니다. MCP 전송, REST 전송, gRPC 전송을 참조하십시오. 이 페이지는 이러한 전송 계층이 실어 나르는 심볼의 카탈로그입니다.
아래의 도구 이름, 클래스, 위험 등급은 src/Tools/의 도구 구현에서 읽어 온 것입니다. 배포 환경이 실제로 노출하는 도구 수는 런타임 속성입니다. 도구 카탈로그를 참조하십시오. 등급의 의미는 부팅 및 디스커버리에서 설명합니다.
전송 계층 가용성
섹션 제목: “전송 계층 가용성”도구는 배포 환경에서 실행 중인 전송 계층을 통해 호출할 수 있습니다. 전송 계층은 독립적인 프로세스이며, 하나를 실행한다고 해서 다른 전송 계층이 시작되지는 않습니다.
| 전송 계층 | 진입점 | 와이어 형식 | 인증 |
|---|---|---|---|
| MCP | bin/nextpdf-mcp | stdio를 통한 JavaScript 객체 표기법 원격 프로시저 호출(JSON-RPC) 2.0 | 운영 체제 프로세스 경계(API 키 없음) |
| REST | bin/nextpdf-server | HTTP, OpenAPI 3.1 | Bearer API 키를 Authorization 헤더에 포함 |
| gRPC | bin/nextpdf-grpc | Protocol Buffers, 패키지 nextpdf.connect.v1 | Bearer 토큰을 authorization 호출 메타데이터에 포함 |
MCP에서는 등록된 도구 이름과 함께 tools/call로 도구를 호출합니다. REST와 gRPC에서는 동일한 엔진 기능이 렌더, 작업, 기능 표면을 통해 제공됩니다. REST 전송의 라우트 표와 gRPC 전송의 RPC 표를 참조하십시오.
인증 및 위험 등급
섹션 제목: “인증 및 위험 등급”API 키 인증
섹션 제목: “API 키 인증”REST와 gRPC 전송 계층은 인증되지 않은 상태 점검 프로브를 제외한 모든 요청에 Bearer API 키를 요구합니다. 키는 npk_live_{kid}_{secret} 형식을 가집니다. kid는 레코드 조회용 8자 식별자이고, 비밀 부분에는 엔트로피가 들어 있습니다. 서버는 키의 SHA-256 다이제스트만 저장하고 제시된 토큰을 상수 시간 비교로 검증하므로, 잘못된 키도 타이밍을 통해 아무 정보도 드러내지 않습니다. REST는 Authorization: Bearer … 헤더에서 토큰을 읽고, gRPC는 동일한 토큰을 authorization 호출 메타데이터에서 읽습니다. MCP stdio 전송 계층은 이를 실행하는 클라이언트가 신뢰하는 로컬 하위 프로세스이므로 API 키가 없습니다. 인증 모델의 전체 내용은 보안 및 운영에 문서화되어 있습니다.
네 가지 위험 등급
섹션 제목: “네 가지 위험 등급”모든 도구는 RiskLevel 열거형(src/Config/RiskLevel.php에 정의됨)으로 정의된, 순서가 있는 네 가지 위험 수준 중 하나를 선언합니다.
| 등급 | 열거형 케이스 | 값 | 효과 |
|---|---|---|---|
| Safe 등급 | RiskLevel::Safe | 0 | 읽기 전용이며 부작용이 없습니다. 자동으로 실행됩니다. |
| Caution 등급 | RiskLevel::Caution | 1 | 인메모리 상태를 생성하거나 수정합니다. 자동으로 실행되며 감사 로그에 기록됩니다. |
| Review 등급 | RiskLevel::Review | 2 | 오용될 수 있는 출력을 생성합니다. 자동으로 실행되며 감사 로그에 기록됩니다. |
| ApprovalRequired 등급 | RiskLevel::ApprovalRequired | 3 | 파괴적이거나 법적 또는 개인정보 보호 측면에서 중대한 작업입니다. 사람의 확인이 필요합니다. |
도구의 실제 적용 위험 수준은 정확히 두 곳에서 비롯됩니다. 도구 자체의 riskLevel() 선언과, 위험 수준을 높일 수만 있고 ApprovalRequired 도구를 결코 낮출 수는 없는 선택적 운영자 구성 재정의입니다. HITL 위험 등급과 구성을 참조하십시오.
승인 토큰의 흐름
섹션 제목: “승인 토큰의 흐름”ApprovalRequired 도구가 유효한 토큰 없이 호출되면, ConfirmationGate(src/Mcp/ConfirmationGate.php)는 도구를 실행하는 대신 일회용 챌린지 토큰을 반환합니다. 에이전트는 챌린지를 사람에게 전달한 다음, 발급된 토큰을 _confirmation_token 인수에 넣어 동일한 도구를 다시 호출합니다. 토큰은 도구 이름, 무작위 논스, 300초의 유효 시간(TTL)에 바인딩됩니다. 인수에는 바인딩되지 않으며 인증 자격 증명도 아닙니다. REST에서는 Bearer API 키가 여전히 요청을 인증하며, 게이트가 적용되는 작업 전에 공유 도구 실행기에서 동일한 게이트가 실행됩니다. gRPC에서는 디스패치된 작업 전에 동일한 게이트가 실행됩니다. 챌린지와 토큰 메커니즘은 전송 계층 전반에서 동일합니다.
도구 및 엔드포인트
섹션 제목: “도구 및 엔드포인트”이 표는 모든 도구를 등록된 도구 이름(심볼 열)을 기준으로 문서화하고 구현 클래스를 명시합니다. 도구는 등급과 범주별로 그룹화됩니다. 모든 AST 클래스와 변형 클래스는 src/Tools/Ast와 src/Tools/Ast/Mutation 아래에 있으며, 추출 클래스는 src/Tools/Extraction 아래에 있고, 나머지 클래스는 src/Tools/Core 아래에 있습니다.
코어 문서 도구
섹션 제목: “코어 문서 도구”| 심볼 | 매개변수 | 기본 동작 | 반환값 | 발생하는 예외 또는 실패 원인 | 참고 |
|---|---|---|---|---|---|
create_pdf | page_size(기본값 A4), orientation(portrait/landscape), title, author. 필수 항목 없음. | 인메모리 문서와 페이지 하나를 생성하고, 메타데이터가 제공되면 설정합니다. | 다음을 포함하는 JSON: document_id, page_count, page_size, orientation. | 실패 시 엔진 메시지를 담은 오류 결과를 반환합니다. | 클래스 CreatePdfTool. 위험 RiskLevel::Caution. core 등급. 반환된 document_id는 이후의 모든 작업에 입력됩니다. |
add_page | document_id(필수), 선택적 페이지 크기 및 방향. | 문서에 페이지를 추가합니다. | 새 페이지 수가 포함된 JSON. | 알 수 없는 document_id에 대한 오류 결과. | 클래스 AddPageTool. 위험 RiskLevel::Caution. core 등급. |
add_text | document_id(필수), text(필수), 선택적 위치 및 스타일. | 문서에 텍스트를 추가합니다. | JSON 문서 상태 요약. | 알 수 없는 document_id에 대한 오류 결과. | 클래스 AddTextTool. 위험 RiskLevel::Caution. core 등급. |
add_image | document_id(필수), source(필수: 파일 경로 또는 base64), 선택적 배치. | 경로 또는 base64 데이터에서 이미지를 추가합니다. | JSON 문서 상태 요약. | 소스를 읽을 수 없거나 document_id를 알 수 없을 때의 오류 결과. | 클래스 AddImageTool. 위험 RiskLevel::Caution. core 등급. |
add_table | document_id(필수), html(필수). | 하이퍼텍스트 마크업 언어(HTML) 표를 문서로 렌더링합니다. | JSON 문서 상태 요약. | 마크업이 잘못되었거나 document_id를 알 수 없을 때의 오류 결과. | 클래스 AddTableTool. 위험 RiskLevel::Caution. core 등급. |
set_font | document_id(필수), family(필수), 선택적 크기 및 스타일. | 이후 텍스트 작업에 사용할 글꼴을 설정합니다. | 활성 글꼴을 확인해 주는 JSON. | 글꼴을 알 수 없거나 document_id를 알 수 없을 때의 오류 결과. | 클래스 SetFontTool. 위험 RiskLevel::Caution. core 등급. |
output_pdf | document_id(필수), file_path(선택), destroy(기본값 true). | 문서를 마무리합니다. file_path에 기록하거나, 생략된 경우 base64를 반환하며, 기본적으로 문서를 파괴합니다. | 다음을 포함하는 JSON: file_path와 file_size, 또는 base64와 file_size. | 알 수 없는 document_id에 대한 오류 결과. 기본 디렉터리 밖에 기록하려 할 때 발생하는 경로 포함(path containment) 실패. | 클래스 OutputPdfTool. 위험 RiskLevel::ApprovalRequired. core 등급. 파일로 기록할 때는 확인 게이트를 거치지만 base64 모드는 거치지 않습니다. |
preview_layout | document_id(필수). | 최종 PDF를 렌더링하지 않고 레이아웃 요약을 반환합니다. | JSON 레이아웃 요약. | 알 수 없는 document_id에 대한 오류 결과. | 클래스 PreviewLayoutTool. 위험 RiskLevel::Safe. core 등급. |
parse_pdf | document_id(필수). | 구조적 메타데이터를 검사합니다: 페이지 수, 글꼴, 이미지, 암호화, Info Dictionary. | JSON 구조적 메타데이터. | 형식이 잘못된 문서에 대한 오류 결과. | 클래스 ParsePdfTool. 위험 RiskLevel::Safe. core 등급. NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED가 true 또는 1일 때만 등록됩니다. |
코어 진단 도구
섹션 제목: “코어 진단 도구”| 심볼 | 매개변수 | 기본 동작 | 반환값 | 발생하는 예외 또는 실패 원인 | 참고 |
|---|---|---|---|---|---|
diagnostic.doctor | 없음. | 상태 점검을 실행하고 구조화된 환경 진단을 반환합니다. | JSON 환경 보고서. | 내부 점검 실패에 대한 오류 결과. | 클래스 DiagnosticDoctorTool. 위험 RiskLevel::Safe. core 등급. 문서와 확인 모두 필요하지 않습니다. |
diagnostic.capabilities | 없음. | 등급 및 상태 정보와 함께 기능을 나열합니다. | JSON 기능 목록. | 내부 실패에 대한 오류 결과. | 클래스 DiagnosticCapabilitiesTool. 위험 RiskLevel::Safe. core 등급. |
diagnostic.inspect | document_id(필수). | PDF를 검사하고 구조적 메타데이터를 반환합니다. | JSON 구조적 메타데이터. | 알 수 없는 document_id에 대한 오류 결과. | 클래스 DiagnosticInspectTool. 위험 RiskLevel::Safe. core 등급. |
diagnostic.verify | document_id(필수), 선택적 PDF/A 또는 PDF/UA 프로파일. | 구조적 무결성을 검증하며, 선택적으로 VeraPDF 하위 프로세스를 생성해 PDF/A 또는 PDF/UA를 검증합니다. | JSON 검증 보고서. | 하위 프로세스 실패, 시간 초과, 입력 크기 초과에 대한 오류 결과. | 클래스 DiagnosticVerifyTool. 위험 RiskLevel::Caution. core 등급. 입력은 50메비바이트(MiB)로 제한됩니다. |
코어 바코드 도구
섹션 제목: “코어 바코드 도구”| 심볼 | 매개변수 | 기본 동작 | 반환값 | 발생하는 예외 또는 실패 원인 | 참고 |
|---|---|---|---|---|---|
generate_barcode | payload(필수), format(예: QR Code, DataMatrix). | 페이로드에 대한 2차원 바코드 모듈 행렬을 생성합니다. | JSON 모듈 행렬. | 지원되지 않는 format이거나 잘못된 페이로드에 대한 오류 결과. | 클래스 BarcodeTool. 위험 RiskLevel::Caution. core 등급. BarcodeTool은 코어 barcode 인코더 레지스트리가 설치된 nextpdf/core에 존재할 때만 등록되며, 등록된 도구 이름은 generate_barcode입니다. |
Enterprise 개인정보 보호 도구
섹션 제목: “Enterprise 개인정보 보호 도구”이 도구들은 Enterprise 개인정보 보호 클래스를 래핑하며, 해당 클래스를 자동 로드할 수 있을 때만 Enterprise 등급으로 등록됩니다. 일반 텍스트 콘텐츠를 대상으로 동작합니다.
| 심볼 | 매개변수 | 기본 동작 | 반환값 | 발생하는 예외 또는 실패 원인 | 참고 |
|---|---|---|---|---|---|
redact_pdf | content(필수), 선택적 탐지 옵션. | Enterprise 비실명화(redaction) 엔진을 사용하여 일반 텍스트 콘텐츠의 개인 식별 정보(PII)를 파괴적으로 제거합니다. | 비실명화된 콘텐츠와 SHA-256 해시가 포함된 JSON. | Enterprise 클래스가 없거나 탐지가 실패할 때의 오류 결과. | 클래스 RedactPdfTool. 위험 RiskLevel::Review. enterprise 등급. |
deidentify_pdf | content(필수), strategy(redact 또는 suppress). | Enterprise 비식별화 도구를 사용하여 일반 텍스트 콘텐츠에 체계적인 비식별화 전략을 적용합니다. | 비식별화된 콘텐츠가 포함된 JSON. | Enterprise 클래스가 없을 때의 오류 결과. | 클래스 DeIdentifyPdfTool. 위험 RiskLevel::Review. enterprise 등급. |
zone_redact_pdf | content(필수), zones(페이지와 정규화된 사각형 목록). | Enterprise 비실명화 엔진을 사용하여 좌표 기반 영역 비실명화를 적용합니다. | 비실명화된 콘텐츠가 포함된 JSON. | 영역이 잘못되었거나 Enterprise 클래스가 없을 때의 오류 결과. | 클래스 ZoneRedactionTool. 위험 RiskLevel::Review. enterprise 등급. |
추상 구문 트리(AST) 읽기 도구
섹션 제목: “추상 구문 트리(AST) 읽기 도구”이 도구들은 서버와 함께 제공되어 Pro 등급으로 등록되며, NEXTPDF_AST_TOOLS_ENABLED(기본적으로 활성화)로 게이트됩니다. 읽기 전용입니다.
| 심볼 | 매개변수 | 기본 동작 | 반환값 | 발생하는 예외 또는 실패 원인 | 참고 |
|---|---|---|---|---|---|
get_document_ast | pdf_data(필수). | 시맨틱 AST를 빌드합니다: 모든 구조적 요소에 대한 인용 앵커가 있는 전체 노드 트리. | 동시성 제어를 위한 ETag와 함께 JSON 노드 트리. | 형식이 잘못된 문서에 대한 오류 결과. | 클래스 GetDocumentAstTool. 위험 RiskLevel::Safe. pro 등급. |
get_ast_node | pdf_data(필수), node_id(필수). | 단일 AST 노드와 그 모든 자식을 검색합니다. | 자식이 포함된 JSON 노드. | 알 수 없는 node_id에 대한 오류 결과. | 클래스 GetAstNodeTool. 위험 RiskLevel::Safe. pro 등급. |
get_ast_diff | original_pdf_data(필수), modified_pdf_data(필수). | 두 문서의 시맨틱 AST를 비교하여 구조적 차이를 산출합니다. | 추가·제거·변경된 노드가 포함된 JSON. | 형식이 잘못된 입력 문서에 대한 오류 결과. | 클래스 GetAstDiffTool. 위험 RiskLevel::Safe. pro 등급. |
search_ast_nodes | pdf_data(필수), 선택적 유형, 페이지 인덱스, 텍스트 필터. | 유형, 페이지 인덱스, 텍스트 콘텐츠로 AST 노드를 검색합니다. | 얕은 자식을 포함하는 일치 노드의 평면 목록 JSON. | 형식이 잘못된 문서에 대한 오류 결과. | 클래스 SearchAstNodesTool. 위험 RiskLevel::Safe. pro 등급. |
extract_cited_text | pdf_data(필수), 선택적 headings_only. | 인용 앵커(페이지, 경계 상자, 신뢰도)와 함께 텍스트 블록을 추출합니다. | JSON 인용 텍스트 블록. | 형식이 잘못된 문서에 대한 오류 결과. | 클래스 ExtractCitedTextTool. 위험 RiskLevel::Safe. pro 등급. 범주 ast. |
extract_cited_tables | pdf_data(필수). | 인용 앵커와 함께 표 블록을 추출합니다. Table 노드마다 셀의 행 우선(row-major) 행렬을 반환합니다. | 앵커가 있는 JSON 표 행렬. | 형식이 잘못된 문서에 대한 오류 결과. | 클래스 ExtractCitedTablesTool. 위험 RiskLevel::Safe. pro 등급. 범주 extraction. |
AST 변형 도구
섹션 제목: “AST 변형 도구”이 도구들은 서버와 함께 제공되어 Pro 등급으로 등록되며, NEXTPDF_MUTATION_TOOLS_ENABLED(기본적으로 활성화)로 게이트됩니다. 네 가지 모두 ApprovalRequired이며 ETag를 통한 낙관적 동시성 제어(OCC)를 사용합니다.
| 심볼 | 매개변수 | 기본 동작 | 반환값 | 발생하는 예외 또는 실패 원인 | 참고 |
|---|---|---|---|---|---|
apply_ast_mutations | pdf_data, etag, idempotency_key, mutations(모두 필수). | 변형 배치를 원자적으로 적용합니다. 반복된 idempotency_key에 대해서는 캐시된 결과를 재생합니다. | 변형된 PDF와 새 ETag가 포함된 JSON. | ETag가 오래되었을 때의 OCC 충돌. 형식이 잘못된 변형에 대한 유효성 검사 오류. | 클래스 ApplyAstMutationsTool. 위험 RiskLevel::ApprovalRequired. pro 등급. |
delete_ast_node | pdf_data, node_id, etag(모두 필수). | 오버레이 모드로 노드를 제거합니다(원본 콘텐츠는 가려지며 물리적으로 삭제되지 않습니다). | 수정된 PDF와 새 ETag가 포함된 JSON. | ETag가 오래되었을 때의 OCC 충돌. 알 수 없는 node_id에 대한 오류. | 클래스 DeleteAstNodeTool. 위험 RiskLevel::ApprovalRequired. pro 등급. |
insert_ast_node | pdf_data, parent_node_id, position, etag, node(모두 필수). | 지정된 위치에 부모의 자식으로 새 노드를 삽입합니다. | 수정된 PDF와 새 ETag가 포함된 JSON. | ETag가 오래되었을 때의 OCC 충돌. 형식이 잘못된 노드에 대한 유효성 검사 오류. | 클래스 InsertAstNodeTool. 위험 RiskLevel::ApprovalRequired. pro 등급. |
update_ast_node | pdf_data, node_id, etag, updates(모두 필수). | 노드의 텍스트 콘텐츠를 업데이트합니다. | 수정된 PDF와 새 ETag가 포함된 JSON. | ETag가 오래되었을 때의 OCC 충돌. 알 수 없는 node_id에 대한 오류. | 클래스 UpdateAstNodeTool. 위험 RiskLevel::ApprovalRequired. pro 등급. |
요청 및 응답 스키마
섹션 제목: “요청 및 응답 스키마”gRPC 전송 계층은 Protocol Buffers 패키지 nextpdf.connect.v1의 proto/nextpdf/connect/v1/*.proto에서 서버의 타입화된 스키마를 정의합니다. 서비스와 그 메시지가 정식 스키마 심볼입니다.
서비스 NextPDFConnect
섹션 제목: “서비스 NextPDFConnect”서비스 NextPDFConnect는 단항(unary) RPC와 서버 스트리밍 RPC를 노출합니다. 스키마 심볼은 RPC 메서드 이름과 각 RPC가 실어 나르는 요청·응답 메시지입니다.
| RPC | 요청 메시지 | 응답 메시지 | 형태 |
|---|---|---|---|
Render | RenderRequest | RenderResponse | 단항. 동기식 무상태 렌더링. |
RenderStream | RenderRequest | RenderChunk (스트림) | 서버 스트리밍. 순서가 있는 청크로 전달되는 렌더링. |
SubmitJob | SubmitJobRequest | JobResponse | 단항. 비동기 렌더 작업을 제출합니다. |
GetJobStatus | GetJobStatusRequest | JobResponse | 단항. 작업 상태를 폴링합니다. |
GetJobResult | GetJobResultRequest | RenderResponse | 단항. 완료된 결과를 다운로드합니다. |
GetJobResultStream | GetJobResultRequest | RenderChunk (스트림) | 서버 스트리밍. 완료된 결과를 청크로 다운로드합니다. |
CancelJob | CancelJobRequest | JobResponse | 단항. 작업을 취소하거나 삭제합니다. |
CreateSession | CreateSessionRequest | SessionResponse | 단항. 문서 작성 세션을 생성합니다. |
GetSession | GetSessionRequest | SessionResponse | 단항. 세션 메타데이터를 가져옵니다. |
DestroySession | DestroySessionRequest | DestroySessionResponse | 단항. 세션과 그 문서를 파괴합니다. |
SessionOperation | SessionOperationRequest | SessionResponse | 단항. 세션 문서에 대한 작업을 실행합니다. |
SessionRender | SessionRenderRequest | RenderResponse | 단항. 세션 문서를 PDF로 렌더링합니다. |
SessionRenderStream | SessionRenderRequest | RenderChunk (스트림) | 서버 스트리밍. 세션 문서를 청크로 렌더링합니다. |
ExecuteCapability | CapabilityRequest | CapabilityResponse | 단항. 등급으로 게이트된 기능 작업을 실행합니다. |
GetCapabilities | GetCapabilitiesRequest | GetCapabilitiesResponse | 단항. 인증된 클라이언트의 기능을 나열합니다. |
HealthCheck | HealthCheckRequest | HealthCheckResponse | 단항. 활성(liveness) 프로브. |
ReadinessCheck | ReadinessCheckRequest | ReadinessCheckResponse | 단항. 준비(readiness) 프로브. |
메시지 심볼
섹션 제목: “메시지 심볼”요청 및 응답 메시지는 스키마의 구조적 심볼입니다. 렌더 메시지인 RenderRequest, RenderResponse, 스트리밍 RenderChunk는 페이지 크기, 방향, 순서가 있는 작업, 그리고 결과 PDF 바이트를 실어 나릅니다. 작업 메시지인 SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest, JobResponse는 비동기 작업 수명 주기를 모델링하며, 작업 메타데이터는 JobData 메시지에 보관됩니다. 세션 메시지인 CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest, SessionRenderRequest는 상태 저장 세션 수명 주기를 모델링하며, 세션 메타데이터는 SessionData 메시지에 보관됩니다. 기능 메시지인 CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest, GetCapabilitiesResponse는 등급으로 게이트된 작업 디스패치와 인트로스펙션을 실어 나릅니다. 시스템 메시지인 HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest, ReadinessCheckResponse는 활성 및 준비 상태를 실어 나릅니다.
제공되는 .proto 파일이 기록 기준이 되는 와이어 계약입니다. gRPC 전송 레퍼런스는 gRPC 전송에 있습니다.
오류 모델
섹션 제목: “오류 모델”서버는 각 전송 계층의 고유한 오류 메커니즘으로 실패를 보고합니다. 각 전송 계층은 동일한 논리적 조건을 유지하되 인코딩만 다릅니다.
MCP
섹션 제목: “MCP”MCP 오류는 JSON-RPC 2.0 오류 객체입니다. 알 수 없는 메서드는 method-not-found(-32601)를 반환하고, 유효한 JSON-RPC가 아닌 메시지는 invalid-request(-32600)를 반환하며, 파싱할 수 없는 입력은 parse-error(-32700)를 반환합니다. 도구 실행이 실패하면 전송 수준 오류가 아니라, 콘텐츠가 오류를 표시하는 성공적인 JSON-RPC 응답을 반환하므로 에이전트가 메시지를 읽을 수 있습니다. ApprovalRequired 도구에 대한 확인 챌린지도 오류가 아니라 성공적인 응답입니다.
REST
섹션 제목: “REST”REST는 RFC 9110에 정의된 의미 체계와 함께 하이퍼텍스트 전송 프로토콜(HTTP) 상태 코드를 사용합니다. 200은 결과를 담고, 400은 요청 필드의 형식 유효성 검사가 실패할 때 반환되며, 401은 유효한 API 키가 제시되지 않았을 때 반환되어 WWW-Authenticate: Bearer 챌린지 헤더를 담습니다. 403은 유효한 키의 등급에 해당 작업 권한이 없을 때 반환되고, 404는 등급으로 게이트된 라우트가 해당 패키지의 부재로 인해 등록되지 않았을 때 반환됩니다. 기계가 읽을 수 있는 오류 본문은 RFC 9457에 따른 Problem Details 문서로, application/problem+json 미디어 유형과 조건별로 안정적인 type 통합 자원 식별자(URI)와 함께 제공됩니다. 필드 수준의 유효성 검사 실패는 본문에 나열됩니다. 경로 순회(path traversal) 방어를 강화하기 위해, document_id가 doc_[a-f0-9]{24} 패턴과 일치하지 않으면 도구 실행 전에 400으로 거부됩니다. REST 미들웨어 파이프라인과 라우트 표는 REST 전송에 문서화되어 있습니다.
gRPC
섹션 제목: “gRPC”gRPC는 표준 gRPC 상태 코드를 사용합니다. 누락되었거나, 형식이 잘못되었거나, 알 수 없거나, 비활성화되었거나, 만료된 토큰이 있으면 호출은 HTTP 상태가 아니라 UNAUTHENTICATED로 실패합니다. 풍부한 오류 세부 정보는 REST Problem Details 형태를 반영하며 gRPC 상태 세부 정보에 담겨, 오류 type URI가 전송 계층 전반에서 일관됩니다.
참고: 상태 코드 의미 체계는 RFC 9110(HTTP Semantics), 오류 본문 형식은 RFC 9457(Problem Details for HTTP APIs)을 참조하십시오.
- RFC 9110, HTTP 의미 체계: https://www.rfc-editor.org/rfc/rfc9110
- RFC 9457, HTTP API 문제 세부 정보: https://www.rfc-editor.org/rfc/rfc9457
속도 제한 및 할당량
섹션 제목: “속도 제한 및 할당량”REST 전송 계층은 미들웨어 파이프라인에서 IP 주소별(per-IP) 및 클라이언트별 속도 제한과 함께, 본문 크기, 등급별 페이로드 제한, 요청별 시간 초과를 적용합니다. 관련 상한값은 하드코딩된 상수가 아니라 구성 값입니다:
- 등급별 페이로드 상한(
corePayloadLimit,proPayloadLimit,enterprisePayloadLimit)과 그에 대응하는 시간 초과는 인증된 키의 등급에 따라 REST에 적용됩니다. 구성을 참조하십시오. - 인메모리 문서 저장소는
max_documents(기본값 50)와document_ttl(기본값 1800초)로 제한됩니다. - 속도 제한 및 멱등성 상태는
NEXTPDF_REDIS_HOST가 공유 저장소로 구성되지 않는 한 워커별로 유지됩니다. 배포를 참조하십시오.
속도 제한 및 멱등성 저장소가 공유되는 경우, 반복되는 동일한 비동기 작업 제출은 idempotency_key로 중복 제거됩니다. MCP 전송 계층은 파이프를 통해 한 번에 하나의 요청을 처리하며, 네트워크 속도 제한을 적용하는 대신 64항목 버퍼에서 반복되는 요청 id를 중복 제거합니다.
개발 참고 사항
섹션 제목: “개발 참고 사항”- 도구 이름, 클래스, 위험 등급은
src/Tools/아래의 소스에서 확인하십시오. 고정된 총계를 가정하지 마십시오. 도구 카탈로그에 나온 대로, 권위 있는 수는 실행 중인 서버에 질의하십시오. - gRPC 클라이언트 스텁은 제공되는
proto/nextpdf/connect/v1/*.proto파일에서 재생성하십시오. 패키지와 네임스페이스는nextpdf.connect.v1입니다. 생성된 메시지 클래스를 직접 편집하지 마십시오. - 일부
ApprovalRequired도구는 첫 호출에서 확인 챌린지로 응답합니다. 챌린지를 전달한 다음_confirmation_token으로 다시 호출하는 재시도 경로를 구축한 뒤에output_pdf나 변형 도구를 구동하는 통합을 출시하십시오. - 설치되지 않은, 등급으로 게이트된 라우트나 기능은 인증 실패가 아닙니다. REST는 부재한 라우트에 대해
404를 반환하고, gRPCExecuteCapability는 작업을 사용할 수 없음으로 보고합니다. 부재한 Pro 또는 Enterprise 등급은 결함이 아니라 예상되는 동작으로 취급하십시오. - API 키를 소스 관리에서 제외하십시오. 비밀 파일로 마운트하고, 회전 시 재시작이 필요 없도록 핫 리로딩 파일 키 저장소를 선호하십시오. 보안 및 운영을 참조하십시오.