gPdf
청구와 재무

이커머스와 SaaS 결제를 위한 영수증 PDF API

주문, 결제, 세금, 환불 데이터에서 QR 코드, 바코드, PDF/A 설정, 반복 가능한 템플릿 출력을 포함한 영수증 PDF를 생성합니다.

주 API JSON Render
ENDPOINT /api/v1/pdf/render
시스템 이커머스 백엔드 / 청구 백엔드 / SaaS 플랫폼 / POS 내보내기 서비스
Playground에서 테스트 문서 보기
해결할 작업

완료된 주문, 결제, 환불, 세금 데이터를 이메일 발송, 저장, 인쇄, 고객 계정 첨부에 사용할 수 있는 영수증 PDF로 변환하되, 모든 호출자가 PDF drawing 코드를 직접 관리하지 않아도 되게 합니다.

이 API를 쓰는 경우

  • 결제 상태, 영수증 번호, 세금 라인, 고객 데이터를 이미 자체 시스템이 관리합니다.
  • 이메일, 계정 이력, 지원 업무 흐름, 감사 내보내기에 사용할 영수증 PDF가 필요합니다.
  • 조회, 환불, 픽업 흐름을 위해 영수증 안에 QR 코드나 바코드를 넣고 싶습니다.
  • 레이아웃 승인 후 안정적인 영수증 템플릿이 필요합니다.

대체하지 않는 것

  • 결제 처리나 환불 실행이 필요합니다. gPdf는 영수증을 렌더링하고, 자금 이동은 결제 시스템이 담당합니다.
  • 법적 전자 인보이스 패키징이 필요합니다. Factur-X 또는 ZUGFeRD 출력에는 E-Invoice Render endpoint를 사용하세요.
  • POS 하드웨어 제어나 금전함 로직이 필요합니다.

호출할 endpoint

주 경로

/api/v1/pdf/render

JSON Render가 이 처리 흐름의 기본 경로입니다.

보조 경로 1

/api/v1/template-render

관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.

최소 request

POST /api/v1/pdf/render - 조회용 QR 코드가 포함된 간단한 영수증.

{
  "pages": [
    {
      "size": "a6",
      "elements": [
        {
          "type": "text",
          "x": 10,
          "y": 12,
          "content": "Receipt R-2026-1001",
          "style": { "font_size": 16, "font_family": "NotoSans-Regular" }
        },
        {
          "type": "text",
          "x": 10,
          "y": 28,
          "content": "Order total: $82.40\nPaid by card ending 4242\nTax: $6.10",
          "style": { "font_size": 10, "font_family": "NotoSans-Regular" }
        },
        {
          "type": "barcode",
          "format": "qrcode",
          "content": "https://example.com/receipts/R-2026-1001",
          "x": 10,
          "y": 58,
          "width": 28,
          "height": 28
        }
      ]
    }
  ]
}

gPdf가 처리하는 것

  • JSON Render 요청 데이터에서 영수증 페이지를 렌더링합니다.
  • 텍스트, 합계, 품목 라인, QR 코드, 바코드, 메타데이터, 선택적 PDF/A 설정을 처리합니다.
  • 같은 영수증 레이아웃을 재사용할 때 Template Render 바인딩을 제공합니다.
  • 실패 시 공유 gPdf 오류 envelope와 함께 바이너리 PDF 출력을 제공합니다.

자체 시스템이 책임지는 것

  • 결제 승인, capture, 환불, 세금 계산, 영수증 번호 부여.
  • 고객 식별, 주문 상태, 통화 표시 형식, 보관 정책.
  • 이메일 전달, 계정 저장, 중복 영수증 처리.

운영 전 체크리스트

  1. 안정적인 영수증 번호를 사용하고 모든 렌더 요청에 X-Request-Id를 전달합니다.
  2. 영수증을 원본 데이터에서 다시 생성할지, 첫 렌더 후 저장할지 결정합니다.
  3. 긴 품목명, 환불, 할인, 여러 세금 라인, 0원 주문을 테스트합니다.
  4. 지원팀과 재무팀이 레이아웃을 승인하면 Template Render로 전환합니다.
  5. 결제와 세금 판단은 렌더링 요청 밖에 둡니다.

지원 범위의 경계

  • gPdf는 결제를 처리하거나, 세금을 계산하거나, 환불을 발행하지 않습니다.
  • 영수증 PDF는 자동으로 법적 전자 인보이스가 되지 않습니다.
  • 비즈니스 기준 정보는 자체 시스템이 관리하고, gPdf는 그 PDF 표현을 렌더링합니다.

영수증 PDF는 렌더링 출력입니다

이것은 별도의 결제 또는 POS endpoint가 아닙니다. 이커머스, 청구, POS 백엔드가 영수증이 존재한다고 결정한 뒤, 영수증 내용을 DocumentRequest 또는 게시된 템플릿의 data로 gPdf에 보냅니다.

렌더링 계층은 결정적으로 유지되어야 합니다. 지원 담당자가 같은 영수증을 다시 요청하면, 보관 정책에 따라 자체 시스템이 원본 데이터를 다시 보내거나 이전에 저장한 PDF를 반환할 수 있습니다.

반복 영수증을 위한 템플릿 경로

영수증 레이아웃은 보통 빠르게 안정됩니다. 디자인이 승인되면 템플릿을 게시하고 영수증 필드와 함께 POST /api/v1/template-render를 호출하세요. 이렇게 하면 결제 시스템은 데이터에 집중하고, 레이아웃 관리는 한곳에 둘 수 있습니다.

FAQ

gPdf가 영수증 합계를 계산할 수 있나요?
아니요. 결제 또는 커머스 시스템이 합계, 할인, 세금, 환불 상태를 관리합니다. gPdf는 사용자가 보낸 값을 렌더링합니다.
영수증에는 JSON Render와 Template Render 중 무엇을 써야 하나요?
레이아웃을 설계하는 동안에는 JSON Render를 사용하세요. 영수증 레이아웃과 필드 계약이 안정되면 Template Render를 사용하세요.
영수증에 QR 코드를 포함할 수 있나요?
네. gPdf는 PDF 출력에서 QR 코드 바코드 요소를 지원합니다. QR 코드에 인코딩되는 URL 또는 입력 데이터는 자체 시스템이 관리합니다.
이것은 e-invoice API와 같은 것인가요?
아니요. 일반 영수증 PDF는 JSON Render 또는 Template Render를 사용합니다. Factur-X와 ZUGFeRD 패키징은 E-Invoice Render endpoint를 사용합니다.
Solution 인보이스 PDF API JSON Render Solution Shopify PDF API JSON Render Solution QR 코드 PDF API JSON Render Reference Render API 레퍼런스 /docs/api-reference/ Reference Template API 레퍼런스 /docs/template-api/ Reference PDF 생성 API 사용 사례 /use-cases/pdf-generation-api/ Reference 템플릿 갤러리 /templates/ Reference 2026년에 PDF API를 고르는 법 /blog/choosing-a-pdf-api-in-2026/