NextPDF Connect를 통해 PDF 양식 채우기 (Pro)

한눈에 보기

NextPDF Connect를 통해 XFDF(XML Forms Data Format)로 대화형 PDF 양식 필드를 채웁니다. 서명 및 양식용 도구는 fill_form입니다. Pro 도구 제공자는 new FillFormTool()을 등록하며, 프로토콜 이름은 fill_form입니다. fill_form은 Pro 등급 도구입니다. 부팅 시 서버는 class_exists()로 Pro 패키지를 탐지하고, 패키지가 있을 때만 도구를 등록합니다. Core만 사용하면 fill_form은 레지스트리에 없습니다.

설치

composer require nextpdf/server
composer require nextpdf/pro

전송을 바인딩합니다. diagnostic.capabilities로 도구 존재 여부를 확인합니다 (environment-diagnostics 참조). 고정된 도구 집합을 가정하지 마십시오.

개념 개요

XFDF는 <field> 요소로 필드 이름을 값에 매핑합니다. 각 이름은 대상 문서에 이미 정의된 AcroForm 필드와 일치해야 합니다. 각 필드는 대화형 양식 필드 사전에 보관되며(ISO 32000-2 §12.7), 제공된 값이 해당 필드의 값이 됩니다(ISO 32000-2 §12.7). 어떤 필드와도 일치하지 않는 이름은 오류로 처리되지 않고 건너뜁니다. 도구는 채운 필드 수와 건너뛴 필드 수를 보고합니다.

API 표면

도구	등급	역할	위험 등급
create_pdf	Core	세션 열기	안전
fill_form	Pro	XFDF 값을 AcroForm 필드에 적용	주의
output_pdf	Core	PDF를 렌더링하고 반환	승인 필요 / 검토 (base64)

도구 이름은 레지스트리의 프로토콜 이름입니다. 도구 카탈로그가 공식 카탈로그입니다. 사용 가능한 도구 집합은 설치된 등급에 따라 달라집니다. Pro 도구는 Pro 패키지가 설치된 경우에만 나타납니다.

코드 예제 — 빠른 시작

1. create_pdf (또는 양식 필드가 이미 있는 템플릿을 로드).
2. 필드 이름을 값에 매핑하는 xfdf_data로 fill_form을 호출합니다.
3. output_pdf → base64.

결과에는 fields_filled, fields_skipped, 그리고 일치한 필드의 이름이 보고됩니다.

코드 예제 — 프로덕션

AcroForm 필드 이름을 직접 제어할 수 있는 템플릿을 사용하십시오. XFDF를 보내기 전에 XFDF 스키마에 맞게 검증하십시오. fields_skipped와 반환된 이름 목록을 확인하여 이름 불일치를 찾아내십시오(이름은 대소문자를 구분합니다). 대량으로 채울 때는 XFDF 크기 제한을 넘지 않도록 하고, 필요하면 데이터를 분할하십시오.

엣지 케이스 및 주의점

• 형식이 잘못된 XFDF. 구문 분석 오류는 문제가 발생한 위치를 알려줍니다. XML 엔터티를 이스케이프하고 xmlns를 포함하십시오.
• 이름 불일치. 일치하지 않는 필드는 조용히 건너뛰며, fields_skipped가 증가합니다. 이름은 대소문자를 구분합니다.
• 양식 필드 없음. AcroForm이 없는 문서는 채워진 필드가 0개가 됩니다.
• XFDF가 너무 큼. 서버는 크기 제한을 초과하는 데이터를 거부합니다. 분할하거나 공백을 줄이십시오.
• Pro 부재. Core만 사용하면 fill_form은 등록되지 않으며, 호출하면 알 수 없는 도구 오류를 반환합니다. 먼저 diagnostic.capabilities로 확인하십시오.

성능

양식 채우기는 렌더링보다 빠릅니다. 출력은 필드 수와 폰트 임베딩에 따라 수 KB에서 수십 KB까지 다양합니다. 프로파일은 structural입니다.

보안 참고 사항

필드 값은 문서 콘텐츠입니다. 신뢰할 수 없는 채널로 PDF를 반환한다면 양식 필드에 비밀 정보를 넣지 마십시오. base64 경로는 파일 시스템에 부작용을 일으키지 않습니다. 파일 출력은 게이트로 제어됩니다.

적합성

진술	사양	조항	reference_id
양식 필드는 대화형 양식 필드 사전에 보관됩니다.	ISO 32000-2	§12.7
제공된 데이터가 해당 필드의 값이 됩니다.	ISO 32000-2	§12.7

상업적 맥락

fill_form은 Pro 등급 도구입니다. 서버는 부팅 시 Pro 패키지가 확인될 때만 이 도구를 등록합니다(class_exists() 탐지). Core 배포에서는 이를 노출하지 않습니다.

전송 가용성

전송	사용 가능	참고
MCP (stdio)	예 (Pro)	Pro가 설치된 경우에만 존재합니다.
REST	예 (Pro)	동일.
gRPC	예 (Pro)	동일.

HITL 위험 등급

fill_form은 되돌릴 수 있는 콘텐츠 변경이므로 주의(Caution)입니다. output_pdf는 승인 필요(Approval Required)이며, base64 모드에서는 검토(Review)로 하향됩니다(HITL risk tiers).

확인 게이트 JSON 엔벨로프

Base64 출력:

{ "allowed": true }

파일 출력은 output-approval에 설명된 챌린지 엔벨로프를 반환합니다.

참고 자료

• 텍스트 콘텐츠 추출
• 접근성 검사
• 도구 카탈로그