구조화된 문서 생성을 위한 JSON-PDF 변환 API

{
  "pages": [
    {
      "size": "a4",
      "elements": [
        {
          "type": "text",
          "x": 20,
          "y": 24,
          "content": "Hello from gPdf",
          "style": {
            "font_size": 18,
            "font_family": "NotoSans-Regular"
          }
        }
      ]
    }
  ]
}

JSON Render 흐름이 맞는 경우

JSON Render는 가장 낮은 수준의 공개 렌더링 경로입니다. 애플리케이션이 페이지 크기, 요소, 좌표, 스타일, 메타데이터, 출력 모드, 선택적 PDF/A 설정 등 문서 구조를 직접 보냅니다. 문서 레이아웃을 코드로 생성하거나 팀이 PDF를 픽셀 수준으로 제어하려는 경우에 맞는 계층입니다.

API 계약은 명시적입니다. 자체 시스템이 텍스트 요소를 보내면 gPdf는 텍스트 요소를 렌더링합니다. 바코드 요소를 보내면 gPdf는 바코드를 벡터 PDF 콘텐츠로 그립니다. gPdf는 요청 데이터에서 업무 의도를 읽지 않으며, 인보이스 번호, 운송사 추적 값, 세금 필드가 올바른지 판단하지 않습니다.

Template Render로 전환할 시점

같은 레이아웃을 여러 시스템에서 반복적으로 사용한다면 템플릿으로 게시하고 template_id와 data[]를 함께 POST /api/v1/template-render로 호출하세요. 이렇게 하면 레이아웃 관리가 각 호출자에서 빠져나오고 ERP, OMS, WMS, SaaS 백엔드에는 안정적인 필드 계약이 생깁니다.

레이아웃 생성, 일회성 문서, 프로그램으로 생성되는 문서에는 JSON Render를 사용하세요. 레이아웃이 고정되어 있고 요청마다 바뀌는 것이 업무 데이터뿐이라면 Template Render를 사용하세요.

운영 형태

운영 환경에서는 PDF 요청을 다른 중요한 API 호출과 같이 다루세요. 요청 ID를 포함하고, 타임아웃을 설정하며, 재시도가 멱등적으로 동작하게 하고, 응답 메타데이터를 로깅합니다. 보관이 필요하다면 반환된 PDF는 자체 시스템에만 저장하세요. 표준 렌더링 응답 이후 gPdf 렌더링 경로는 상태를 보관하지 않습니다.