보고서 작성의 전체 흐름
1. 보고서 구조 만들기
제목, 보고 기간, 차트, 상세 표가 있는 보고서 템플릿을 만드세요. 여러 페이지로 이어질 수 있는 내용에는 흐름 배치를 사용합니다. 필요에 따라 머리글, 바닥글, 페이지 번호를 추가하세요.
2. 데이터는 한 번만 정의
예를 들어 monthlyRevenue 배열에 month와 revenue 속성을 사용하세요. 차트를 해당 배열에 바인딩하고 범주 필드는 month, 계열 필드는 revenue로 선택합니다. 상세 표도 같은 배열에 바인딩하면 두 화면에서 같은 데이터를 사용합니다.
3. 경계 사례 테스트
빈 배열, 단일 범주, 긴 범주 이름, 누락된 필드, 많은 행을 테스트하세요. 차트 합계를 표와 비교하세요. 원형이나 도넛 차트에는 음수를 사용하지 마세요. 레이블이 빽빽하면 차트를 키우거나, 범주를 줄이거나, 상세 내용을 표로 표시하세요.
보고서 생성 전체 과정
보고서는 보통 일괄 생성되고 단일 청구서보다 시간이 오래 걸리므로 대기열에서 처리합니다. 먼저 차트를 단독으로 검증한 후 문서를 대기열에 넣고 웹훅 또는 폴링으로 추적하세요.
# 1 - 문서에 넣기 전에 차트를 단독 검증
curl -X POST https://api.pdfgine.com/api/v1/templates/chart-preview \
-H "X-PDFgine-Key: $PDFGINE_KEY" \
-H "Content-Type: application/json" \
-d '{
"width": 640,
"locale": "ko",
"element": {
"id": "quarterly-volume",
"type": "chart",
"placementMode": "flow",
"layout": { "width": 100, "widthUnit": "percent", "height": 240 },
"content": {
"title": "생성된 문서",
"data": [
{ "quarter": "Q1", "documents": 120 },
{ "quarter": "Q2", "documents": 180 },
{ "quarter": "Q3", "documents": 240 },
{ "quarter": "Q4", "documents": 310 }
]
},
"chart": {
"type": "bar",
"labelField": "quarter",
"series": [{ "field": "documents", "label": "문서", "color": "#e3232a" }],
"showLegend": true,
"showValues": true
}
}
}'
# 2 - 보고서를 대기열에 추가 - statusUrl이 포함된 202 응답
curl -X POST https://api.pdfgine.com/api/v1/documents/render \
-H "X-PDFgine-Key: $PDFGINE_KEY" \
-H "Content-Type: application/json" \
-d '{
"templateCode": "maintenance-report",
"format": "pdf",
"locale": "ko",
"webhookUrl": "https://example.com/hooks/pdfgine",
"data": { "document": { "title": "분기별 유지보수" } }
}'
# 3 - 추적 - 웹훅을 지정하지 않았으면 이 엔드포인트를 폴링
curl -s https://api.pdfgine.com/api/v1/async-jobs/queue_fe86ad38402a4909b3b5a7965847924a \
-H "X-PDFgine-Key: $PDFGINE_KEY"대기열은 완성된 문서 대신 statusUrl이 포함된 202 응답을 반환합니다. 직접 조회하는 대신 알림을 받으려면 webhookUrl을 지정하세요. 문서가 준비되면 대기열이 호출하며 호출에 실패하면 재시도합니다.
4. 출력 검증 및 공유
저장과 게시를 확인한 후 필요한 PDF와 Word 출력을 생성하세요. Viewer에서는 페이지 수와 차트가 사용 가능한 공간을 채우는지 확인합니다. Word 차트는 편집 가능한 기본 차트가 아니라 이미지입니다. 외부 공유 시 만료 시간과 다운로드 권한을 확인하고, 공유 링크에 API 키를 넣지 마세요.
차트와 보고서 →자주 발생하는 문제
- 대기열은 보고서가 아닌 statusUrl이 포함된 202로 응답합니다. 이 응답에서 documentId를 바로 읽으면 항상 null입니다.
- 행이 없는 달도 실제로 발생합니다. 빈 차트와 제목 없는 표가 고객에게 전달되기 전에 빈 배열을 테스트하세요.
- 차트와 표를 비교하세요. 한 배열에 바인딩된 차트와 다른 배열에서 계산한 합계 행의 불일치는 보고서에서 가장 알아차리기 어려운 숫자 오류입니다.
- 원형 또는 도넛 차트에 음수를 정확하게 표시할 수 없습니다. 차트가 아닌 원본 데이터를 수정하세요.
- 일괄 작업에는 페이지 한도와 요금제의 분당 문서 수라는 두 상한이 있습니다. 429를 반복해서 받지 않도록 작업을 분산하세요.