4×6 PDF ラベルのための配送ラベル API
注文 JSON から、ベクターバーコード、ラベル用ページサイズ、倉庫での再現性ある再印刷に対応した印刷用 4×6 配送ラベルPDFを生成します。
/api/v1/pdf/render 注文、届け先、配送サービス、追跡データからラベルサイズの PDF をレンダリングし、倉庫や EC バックエンドが出荷作業中に同じ 4×6 ラベルを安定して印刷し、必要時にも同じ内容で再印刷できるようにします。
この API が合う場合
- 自社システム側に追跡番号、届け先、配送サービス表記、バーコードにエンコードする値がすでにある場合。
- Zebra、SATO、Honeywell など、感熱式ラベルプリンターの運用に PDF 出力が必要な場合。
- PDF に貼り付けるラスター画像ではなく、ベクターのバーコードモジュールを使いたい場合。
- 再印刷や監査証跡のために、同じ送信データから同じラベルを再現したい場合。
置き換えないもの
- 送料の購入、出荷運賃の計算、配送会社アカウントを通じた配送ラベル作成が必要な場合。
- ZPL の代替エンドポイントが必要な場合。gPdf はプリンターのコマンド言語ではなく PDF を返します。
- gPdf に配送会社ラベルの認定を求める場合。スキャナー検証と配送会社による受け入れ確認は、自社側で行います。
呼び出す endpoint
/api/v1/pdf/render
JSON Render がこのワークフローの標準パスです。
/api/v1/template-render
関連 API パス、テンプレート契約、または機能確認が必要な場合に使います。
最小リクエスト
POST /api/v1/pdf/render - 追跡バーコード付きの最小構成の 4×6 ラベル。
{
"pages": [
{
"size": "label_4_6_in",
"elements": [
{
"type": "text",
"x": 4,
"y": 6,
"content": "SHIP TO",
"style": { "font_size": 8, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 4,
"y": 13,
"content": "Acme Warehouse\n1200 Logistics Pkwy\nMemphis TN 38116",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "code128",
"content": "1Z999AA10123456784",
"x": 4,
"y": 62,
"width": 92,
"height": 22,
"barcode_text": { "enabled": true, "position": "bottom" }
}
]
}
]
}
gPdf が担当すること
- 4×6 インチ運用などのラベルサイズ PDF ページ。
- 配送会社ラベルや倉庫ラベルの内容に使うベクターバーコードの描画。
- テキスト、住所ブロック、サービス表記、罫線、枠、必要に応じたテンプレート連携。
- 倉庫での再印刷に使える再現性のある PDF 出力。
自社システムが担当すること
- 配送会社アカウント、送料購入、配送サービス選択、追跡番号の発行。
- 正しいバーコード値、人が読めるテキスト、住所、仕分け・経路データ。
- プリンター設定、ラベル用紙、スキャンテスト、配送会社の受け入れ確認。
本番前チェックリスト
- 実機のプリンター型番とラベル用紙でテストラベルを印刷する。
- 想定 DPI とスキャナー距離でバーコードの読取率を検証する。
- 再印刷ポリシーに従い、元の出荷データまたは返された PDF を保存する。
- ラベルレイアウトが承認され、複数システムで再利用される段階になったら Template Render を使う。
- 配送会社固有のロジックはレンダリングリクエストの外側に置く。
対応範囲の境界
- gPdf はラベルPDFをレンダリングします。送料を購入したり、配送会社と直接通信したりはしません。
- gPdf は配送会社ラベルの認定機関ではありません。
- この API は PDF 出力であり、ZPL、EPL、その他の感熱プリンターのコマンドストリームではありません。
配送ラベル API の構成
配送ラベルのページは、配送会社向けの独立エンドポイントではありません。ラベルサイズのページ、テキストブロック、罫線、必要に応じた画像、バーコード要素を指定して JSON Render を呼び出します。繰り返し使うラベルでは、承認済みのレイアウトをテンプレートとして公開し、出荷データとともに Template Render を呼び出します。
これにより責任範囲が明確になります。gPdf は PDF のレンダリングとバーコード描画を担います。自社システムは、配送会社とのトランザクション、出荷ステータス、送信データの業務上の意味を管理します。
JSON Render と Template Render
フルフィルメントシステムがレイアウト全体を生成する場合や、運用チームがまだ座標を調整している段階では JSON Render を使います。倉庫が安定したラベルレイアウトを承認し、すべての呼び出し元が同じデータフィールドだけを送ればよい状態になったら Template Render を使います。
どちらの経路も PDF 出力を返します。違いは、呼び出し側がリクエストごとにレイアウトを記述するか、公開された template_id を参照するかです。
印刷テストが重要
感熱ラベルの品質は物理条件に左右されます。実際のラベル用紙、実際のプリンター、実際のスキャナーで出力を検証してください。バーコード値の正しさ、クワイエットゾーン、プリンター濃度、配送会社固有のルールは、レンダリング API の外側にある本番運用上の責任です。
FAQ
- gPdf が配送会社のラベルを作成してくれますか？
- いいえ。配送会社との出荷トランザクションとバーコード値は、自社が使う配送会社または出荷システムが作成します。gPdf はそのデータを PDF ラベルとしてレンダリングします。
- 配送ラベルに Template Render を使えますか？
- はい。ラベルを設計・テストしている間は JSON Render を使い、レイアウトが安定して呼び出し側がデータだけを送ればよくなったら Template Render を使います。
- gPdf は ZPL を出力しますか？
- いいえ。公開レンダリング API は PDF を出力します。印刷経路に ZPL が必要な場合は、gPdf の外側で PDF を変換するか、印刷経路を分けます。
- 本番前に何を検証すべきですか？
- 実機のプリンターとラベル用紙で印刷し、本番用スキャナーでバーコードを読み取り、配送会社固有のテキストとバーコード値が自社の出荷システムから来ていることを確認します。