gPdf
블로그

2026년에 PDF API를 고르는 법: 반드시 물어볼 8가지 질문

PDF 생성 API를 선택하기 위한 벤더 중립 의사결정 프레임워크. 12개월 뒤에도 만족할지를 실제로 가르는 8가지 질문입니다.

gPdf Engineering
#의사결정-프레임워크#평가

PDF 생성 API를 고르는 일은 시작 전에는 쉬워 보입니다. 시장에는 약 40곳의 벤더가 있고, 마케팅 페이지는 대부분 비슷하게 들리며, 실제 차이는 프로덕션에서 문서 수천 건을 만들어 본 뒤에야 드러납니다.

이 체크리스트는 벤더 평가 회의에 그대로 가져갈 수 있습니다. 특정 벤더에 치우치지 않았고, 조달 과정과 장애 사후 분석에서 팀들이 실제로 겪은 사건에서 뽑았습니다. 질문은 8개입니다. 이 8개 모두에 명확한 답을 얻지 못했다면, 아직 선택할 만큼의 정보가 없습니다.

1. 입력 형식은 HTML, JSON, 템플릿 DSL 중 무엇인가?

가장 중요한 질문입니다. 이 답이 팀이 무엇을 작성할지, 그리고 새벽 2시에 무엇을 디버그하게 될지를 결정합니다.

  • HTML/CSS (Puppeteer, DocRaptor, Prince): 익숙하고 거의 무한히 유연하지만, 실행 비용이 높고 결정적인 출력으로 만들기 어렵습니다.
  • JSON / 구조화 데이터 (gPdf): 렌더링 비용이 낮고 바이트 단위로 동일한 출력을 만들 수 있지만, 자체 데이터 모델을 문서 모델로 옮기는 작은 매퍼를 작성해야 합니다.
  • 템플릿 DSL (PDFKit, ReportLab, Apache PDFBox): 완전한 제어권을 주는 대신 페이지 나누기, 레이아웃, 대체 글꼴 처리도 모두 직접 책임져야 합니다.

모든 팀에 맞는 정답은 없습니다. 다만 당신의 팀에 맞지 않는 답은 있습니다. 3시간짜리 페이지 나누기 버그를 어느 모델에서 디버그하고 싶은지 엔지니어들에게 물어보세요.

2. 콜드 스타트 지연 시간은 얼마이며 예측 가능한가?

어떤 렌더러는 마이크로초 단위로 시작합니다(WASM이나 네이티브 바이너리 계열). 어떤 렌더러는 몇 초가 걸립니다(Chromium 기반). 이 차이는 트래픽 피크가 오기 전까지는 잘 보이지 않습니다.

벤더에게 물어볼 질문:

  • “콜드 워커의 첫 요청 p99 지연 시간은 얼마인가요?”
  • “마지막 요청 이후 얼마가 지나면 워커가 다시 콜드 상태가 되나요?”
  • “콜드 스타트 데이터를 포함한 상태 페이지를 공개하나요?”

첫 질문에 숫자로 답하지 못한다면, 좋지 않다고 가정하세요.

3. 렌더링 비용은 어떻게 계산되는가?

자주 발목을 잡는 순서대로 보면 세 가지입니다.

  • 페이지 단가 모델 (Anvil은 PDF당 0.10달러, DocRaptor는 10만 페이지당 89달러): 예측하기 쉽고 예산화도 쉽지만 규모가 커지면 비쌉니다.
  • 구독 티어 + 초과 과금 (gPdf는 월 5-12달러 + 초과분 페이지당 0.00005달러): 어떤 볼륨에서도 저렴하지만, 아직 테스트하지 않은 사용량은 예측하기가 더 어렵습니다.
  • 컴퓨트 기반 과금 (Lambda에서 자체 호스팅 Puppeteer): 콜드 스타트와 Chromium 메모리까지 포함한 컴퓨트 청구서를 직접 부담합니다.

계약하기 전에 현재, 5배, 50배 트래픽에서 실제 청구액을 계산하세요. 첫 화면에 보이는 가격보다 비용 곡선의 모양이 더 중요합니다.

4. 출력은 결정적인가?

결정성, 즉 같은 입력이 같은 바이트를 만든다는 말은 필요해지기 전까지는 학술적으로 들립니다.

다음 상황에서는 반드시 필요합니다.

  • CI에서 PDF diff로 의도하지 않은 템플릿 변경을 잡아야 할 때.
  • 전자 인보이스나 세무 보관 규칙에 따라 문서를 보관해야 할 때(저장한 PDF와 다시 생성한 PDF가 일치해야 합니다).
  • 아카이브 무결성을 위해 PDF 해시를 계산할 때.
  • 법무 검토를 위해 렌더링된 출력을 버전 관리할 때.

브라우저 기반 렌더러(Puppeteer와 Chromium 계열)는 패치 버전이 바뀌면 바이트 단위 출력이 달라지는 경우가 많습니다. 네이티브 바이너리 렌더러(Prince, gPdf)는 보통 더 유리합니다. 명시적으로 물어보세요. “렌더러 업데이트를 배포하면 제 출력 바이트가 바뀌나요?”

5. 렌더러는 글꼴, 특히 CJK와 RTL을 어떻게 처리하는가?

PDF 분야에서 이 질문만큼 많은 커리어 비용을 만든 것도 드뭅니다.

실패 양상은 일정합니다. 처음 출시한 본국 시장에서는 글꼴이 멀쩡합니다. 6개월 뒤 렌더러에 글리프가 없는 문자를 쓰는 시장으로 확장합니다. PDF가 ▢▢▢▢ 상자를 내보내기 시작합니다. 고객이 에스컬레이션합니다. 팀은 Dockerfile에 글꼴을 추가하느라 스프린트 두 번을 씁니다.

물어볼 질문:

  • “추가 설정 없이 어떤 문자권이 포함되어 있나요? (Latin, CJK, Cyrillic, Devanagari, Arabic, Hebrew?)”
  • “알 수 없는 글리프를 만나면 대체 글꼴로 넘어가나요, 아니면 tofu가 나오나요?”
  • “요청 시점에 사용자 지정 글꼴을 추가할 수 있나요, 아니면 미리 배포해야 하나요?”
  • “RTL 텍스트 shaping을 지원하나요?”

좋은 답은 이런 식입니다. “NotoSans CJK와 Noto 대체 글꼴 세트를 내장하고, 알 수 없는 글리프는 Noto Symbols로 넘어갑니다.” 나쁜 답은 “네, 글꼴을 지원합니다“입니다.

6. 어떤 컴플라이언스 프로파일을 지원하는가?

비즈니스가 언젠가 다음 중 하나라도 할 가능성이 있다면:

  • EU에서 인보이스를 발행한다(Factur-X / ZUGFeRD / EN 16931, 2026년까지 DE/FR/IT/PL에서 의무화)
  • SOX, HIPAA, GDPR 보관 규칙에 따라 문서를 보관한다(PDF/A)
  • 의료 기록을 제출한다(XML 첨부가 있는 PDF/A-3)
  • 디지털 서명을 포함한다(PAdES)

…렌더러가 어떤 컴플라이언스 프로파일을 기본 지원하는지 물어보세요. 나쁜 답은 “나중에 다른 도구를 돌려 변환하면 됩니다“입니다. 그 순간 운영해야 할 다단계 처리 흐름이 하나 더 생깁니다.

좋은 답은 보통 단일 플래그처럼 보입니다. 예를 들어 gPdf는 settings.profile: "pdfa-3b"와 함께 standard: "factur_x" 및 내장 CII XML을 담은 settings.e_invoice 블록을 받습니다. 처음부터 내장된 기능은 나중에 덧붙이는 방식보다 운영 부담이 훨씬 작습니다.

7. 렌더링은 무상태인가? 렌더링 후 내 문서는 어디로 가는가?

서로 연결된 두 질문입니다.

무상태 렌더링은 요청을 받고 PDF를 내보낸 뒤 아무것도 저장하지 않는다는 뜻입니다. 영속성은 직접 처리합니다(S3, 자체 DB 등). 컴플라이언스 부담이 큰 업무에는 이 방식이 맞습니다. 렌더러가 데이터 보관자가 되지 않기 때문입니다.

상태 보유 렌더링은 벤더가 PDF를 저장하고(대개 자체 CDN에), 서명된 URL을 돌려주는 방식입니다. “고객에게 링크를 보내기” 같은 가벼운 사용 사례에는 편하지만, 규제 대상 업무에는 문제가 됩니다. 이제 제3자가 당신이 만든 모든 문서의 사본을 갖게 되기 때문입니다.

물어보세요.

  • “기본값이 무상태 렌더링인가요?”
  • “문서를 저장한다면 지리적으로 어디에 저장하나요?”
  • “얼마나 오래 보관하나요?”
  • “컴플라이언스 검토를 위해 무상태 렌더링 보장을 문서로 받을 수 있나요?”

답이 흐릿하면, 9개월 뒤 개인정보보호팀이나 법무팀이 이 문제를 쟁점으로 만들 가능성이 큽니다.

8. 렌더러가 실패하면 어떻게 되며, 나는 어떻게 알 수 있는가?

모든 렌더러는 가끔 실패합니다. 물어볼 질문은 다음과 같습니다.

  • 실패는 어떻게 드러나는가? 스택 트레이스가 붙은 500인가요? 구조화된 오류가 있는 4xx인가요? 빈 PDF인가요?
  • 재시도 정책은 무엇인가? 멱등적인가요? 실패한 렌더링에도 과금하나요?
  • 벤더는 어떤 계측을 제공하는가? 상태 페이지가 있나요? 장애 웹훅이 있나요? 지역별 p50/p99 대시보드가 있나요?
  • 합성 모니터링이 있는가? 벤더가 공개 엔드포인트를 직접 모니터링하나요, 아니면 고객이 티켓을 열 때까지 기다리나요?

빠른 테스트가 있습니다. 지금 벤더의 상태 페이지를 열어 보세요. 존재하지 않거나, 실시간이 아니거나, 아무 세부 정보 없이 “all systems operational“만 보여 준다면 구매 후에도 그 수준의 신뢰성 투명성을 얻게 됩니다.

(참고로 gPdf는 최근 7일의 합성 모니터링 데이터와 Cloudflare Analytics를 포함한 /status를 공개합니다.)

8가지 질문에 대한 gPdf의 답

우리 블로그이기 때문에 질문을 우리에게 유리하게 골랐다고 의심할 수 있습니다. 그래서 솔직한 점수표를 적습니다.

# 질문 gPdf 답변
1 입력 형식 JSON DocumentRequest (구조화 데이터)
2 콜드 스타트 5-20 ms (V8 isolate, 브라우저 없음)
3 비용 모델 월 0/5/8/12달러; 초과분 페이지당 0.00005달러
4 결정성 바이트 단위 동일, 같은 엔진 버전에서는 보장
5 글꼴 NotoSans CJK와 Latin 대체 글꼴 내장
6 컴플라이언스 PDF/A-1b/2b/3b/4 + Factur-X / ZUGFeRD 첨부 내장
7 무상태 예, 계약상 보장되며 어디에도 문서를 저장하지 않음
8 실패와 가시성 7일 추세가 있는 공개 상태 페이지, 구조화된 4xx/5xx, 멱등적 처리

우리가 지는 지점도 있습니다. Q1에서 입력이 정말로 바꿀 수 없는 HTML이라면(예: 사용자 생성 보고서, 레거시 템플릿), DocRaptor나 Prince가 맞는 답입니다.

요약

“가장 좋은 PDF API가 무엇인가“라고 묻지 마세요. 8가지 질문을 던지고, 답을 점수화한 뒤, 실제 업무 부하와 맞는 벤더를 고르세요. 9개월 뒤 5번 질문에 뒤통수를 맞아 조금 더 싼 경쟁사에게 조달을 넘긴 팀도 같은 말을 할 것입니다.

당신의 업무 부하가 gPdf가 만들어진 방식과 맞는다면 Playground에서 30초면 평가할 수 있습니다. 맞지 않는다면 적합한 도구를 기꺼이 알려드리겠습니다. 보통 HTML 형태의 문제에는 DocRaptor, 자체 호스팅에는 Prince, 입력이 정말 임의의 웹페이지라면 Puppeteer입니다.