앱과 백엔드 업무 흐름을 위한 Shopify PDF API
Shopify 앱 또는 백엔드 업무 흐름에서 gPdf를 호출해 매핑된 Shopify 데이터로 주문 PDF, 인보이스, 포장 명세서, 반품 문서, 라벨을 생성합니다.
/api/v1/pdf/render 네이티브 Shopify App Store 연동이라고 주장하지 않고, Shopify 앱 또는 이커머스 백엔드가 주문, 고객, 상품, 풀필먼트, 반품 데이터를 gPdf JSON 또는 템플릿 data로 매핑해 재현 가능한 PDF를 반환합니다.
이 API를 쓰는 경우
- 외부 API를 호출할 수 있는 Shopify 앱, 비공개 백엔드, 풀필먼트 업무 흐름을 만들고 있습니다.
- 앱이 이미 Shopify 주문, 풀필먼트, 고객, 상품 데이터를 받습니다.
- 인보이스, 포장 명세서, 반품 문서, 창고 라벨, PDF 첨부 파일이 필요합니다.
- 판매자별 문서 레이아웃에 안정적인 template_id 계약을 원합니다.
대체하지 않는 것
- gPdf가 공식 Shopify 앱 또는 App Store 등록 앱이어야 합니다.
- gPdf가 판매자 스토어에 설치되거나 OAuth를 처리하거나 webhooks를 직접 구독해야 합니다.
- 배송 요율, 우편 요금 구매, 재고 관리, 판매자 UI 기능을 gPdf에서 제공해야 합니다.
호출할 endpoint
/api/v1/pdf/render
JSON Render가 이 처리 흐름의 기본 경로입니다.
/api/v1/template-render
관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.
최소 request
POST /api/v1/template-render - 앱 백엔드가 매핑된 Shopify 주문 데이터를 게시된 템플릿으로 보냅니다.
{
"template_id": "packing_list",
"data": [
{
"order_number": "#1042",
"customer_name": "Example Buyer",
"ship_to": "1200 Market St, San Francisco, CA",
"items": [
{ "sku": "TSHIRT-BLK-M", "name": "Black T-shirt", "quantity": 2 },
{ "sku": "MUG-WHT", "name": "White mug", "quantity": 1 }
]
}
]
}
gPdf가 처리하는 것
- 앱 백엔드가 매핑한 Shopify 기반 JSON에서 PDF 렌더링.
- 판매자 또는 브랜드별 문서 레이아웃을 위한 Template Render.
- 바코드, QR 코드, 표, 합계, 이미지, 라벨, 포장 명세서 구조.
- 공개 gPdf API를 통한 상태 없는 PDF 생성.
자체 시스템이 책임지는 것
- Shopify 앱 코드, OAuth, webhooks, 판매자 UI, App Store 배포.
- 주문, 풀필먼트, 고객, 반품, 상품, 세금 데이터 매핑.
- 판매자 설정, 템플릿 선택, 전달, 저장, 재시도.
운영 전 체크리스트
- Shopify credentials와 gPdf API tokens는 브라우저 코드가 아니라 백엔드에 보관합니다.
- Shopify 데이터를 명시적인 렌더링 요청 데이터 또는 템플릿 data schema로 매핑합니다.
- 승인 후 판매자별 레이아웃에는 Template Render를 사용합니다.
- 판매자 업무 흐름에 따라 생성된 PDF 또는 원본 데이터를 저장합니다.
- 이 연동이 공식 gPdf Shopify 앱이 아니라, 사용자의 앱이 gPdf를 호출하는 구조임을 문서화합니다.
지원 범위의 경계
- 공개 공식 Shopify 앱이 실제로 존재하지 않는 한 그렇게 주장하지 마세요.
- gPdf는 Shopify OAuth, 앱 설치, webhooks, 판매자 설정을 실행하지 않습니다.
- 호출자가 Shopify 데이터 매핑과 이커머스 업무 규칙을 담당합니다.
연동 모델
깔끔한 Shopify 연동 모델은 백엔드 대 백엔드입니다. 앱이 Shopify 데이터를 받거나 가져오고, 이를 gPdf DocumentRequest 또는 템플릿 data 객체로 매핑한 뒤, gPdf를 호출하고, 판매자 업무 흐름에 맞춰 PDF를 반환하거나 저장합니다.
이렇게 해야 공개 주장이 정확해집니다. gPdf는 Shopify 앱이 호출할 수 있는 PDF 생성 API입니다. 별도 앱 제품이 실제로 존재하지 않는 한 공개 공식 Shopify 앱이 아닙니다.
Template Render는 판매자 레이아웃에 적합합니다
이커머스 PDF는 종종 판매자별 문서가 됩니다. 브랜딩, 품목 표, 반품 안내, 라벨 블록, 선물 메시지, 현지화된 문구가 달라집니다. Template Render를 사용하면 앱은 매핑된 주문 데이터만 보내고, 이러한 레이아웃은 게시된 템플릿에 둘 수 있습니다.
플랫폼 로직은 앱에 유지하세요
OAuth, webhooks, 판매자 설정, 풀필먼트 상태, 재고, 반품 규칙, App Store 배포는 Shopify 앱에 남습니다. gPdf는 최종 렌더링 데이터를 받아 PDF를 생성해야 합니다.
FAQ
- gPdf는 공식 Shopify 앱인가요?
- 아니요. 이 페이지는 gPdf를 호출하는 앱과 백엔드를 위한 페이지입니다. 해당 제품이 실제로 존재하지 않는 한 gPdf를 공식 Shopify App Store 연동으로 소개하지 마세요.
- gPdf API 호출은 어디에서 해야 하나요?
- Shopify credentials와 gPdf API tokens가 보호되는 백엔드 또는 앱 서버에서 gPdf를 호출하세요.
- Shopify PDF에는 JSON Render와 Template Render 중 무엇을 써야 하나요?
- 맞춤 생성 레이아웃에는 JSON Render를 사용하세요. 판매자 또는 브랜드 레이아웃이 승인되어 호출자가 data만 보내야 할 때는 Template Render를 사용하세요.
- gPdf가 Shopify webhooks를 처리하나요?
- 아니요. 앱이 webhooks를 받고, 데이터를 매핑하고, 언제 렌더링할지 결정합니다. gPdf는 받은 PDF 요청만 렌더링합니다.