Versandetikett-API für 4×6-PDF-Etiketten
Erzeugen Sie druckfertige 4×6-Versandetikett-PDFs aus Bestell-JSON, mit Vektor-Barcodes, Etiketten-Seitengrößen und deterministischen Nachdrucken im Lager.
/api/v1/pdf/render Aus Bestell-, Empfänger-, Service- und Trackingdaten etikettengroße PDFs rendern, damit ein Lager- oder E-Commerce-Backend dasselbe 4×6-Etikett im Fulfillment zuverlässig drucken und bei Bedarf deterministisch nachdrucken kann.
Wann diese API passt
- Ihr System besitzt Trackingnummer, Zieladresse, Servicetext und Barcode-Nutzdaten bereits.
- Sie benötigen PDF-Ausgabe für Zebra-, SATO-, Honeywell- oder andere Thermodrucker-Workflows.
- Sie möchten Vektor-Barcode-Module statt gerasterter Barcodebilder in einem PDF.
- Dieselben Daten sollen für Nachdrucke und Audit-Nachweise dasselbe Etikett erzeugen.
Was sie nicht ersetzt
- Sie müssen Porto kaufen, eine Sendung bewerten oder über ein Carrier-Konto ein Carrier-Label erstellen.
- Sie benötigen einen ZPL-Ersatz-Endpunkt. gPdf gibt PDF aus, keine Drucker-Befehlssprache.
- Sie erwarten Carrier-Zertifizierung durch gPdf. Scanner- und Carrier-Akzeptanztests bleiben Ihre Aufgabe.
Welchen Endpoint aufrufen
/api/v1/pdf/render
JSON Render ist der Standardpfad für diesen Workflow.
/api/v1/template-render
Nutzen Sie dies, wenn der Workflow den zugehörigen API-Pfad, einen Template-Vertrag oder eine Capability-Abfrage braucht.
Minimaler Request
POST /api/v1/pdf/render - minimales 4×6-Etikett mit Tracking-Barcode.
{
"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" }
}
]
}
]
}
Was gPdf übernimmt
- Etikettengroße PDF-Seiten, etwa für 4×6-Zoll-Workflows.
- Vektor-Barcode-Rendering für Carrier- und Lageretiketten.
- Text, Adressblöcke, Servicekennzeichen, Linien, Kästen und optionale Template-Bindung.
- Deterministische PDF-Ausgabe für Nachdrucke im Lager.
Was Ihr System verantwortet
- Carrier-Konto, Portokauf, Serviceauswahl und Erstellung der Trackingnummer.
- Korrekte Barcode-Nutzdaten, menschenlesbarer Text, Adressen und Routingdaten.
- Druckereinrichtung, Etikettenmaterial, Scan-Tests und Carrier-Akzeptanzprüfungen.
Produktions-Checkliste
- Drucken Sie Testetiketten auf dem echten Druckermodell und dem echten Etikettenmaterial.
- Prüfen Sie Barcode-Scanraten bei Ziel-DPI und Scannerabstand.
- Speichern Sie Quell-Sendungsdaten oder das zurückgegebene PDF gemäß Ihrer Nachdruck-Policy.
- Nutzen Sie Template Render, sobald das Etikettenlayout freigegeben und systemübergreifend wiederverwendet wird.
- Halten Sie Carrier-spezifische Logik außerhalb des Rendering-Requests.
Aussagegrenzen
- gPdf rendert das Etiketten-PDF; es kauft kein Porto und spricht nicht direkt mit Carriern.
- gPdf ist keine Zertifizierungsstelle für Carrier-Labels.
- Die API gibt PDF aus, nicht ZPL, EPL oder einen anderen Thermodrucker-Befehlsstrom.
Die Form der Versandetikett-API
Versandetikett-Seiten sind kein separater Carrier-Endpunkt. Sie rufen JSON Render mit einer etikettengroßen Seite, Textblöcken, Linien, optionalen Bildern und Barcode-Elementen auf. Für wiederkehrende Etiketten veröffentlichen Sie das freigegebene Layout als Vorlage und rufen Template Render mit Sendungsdaten auf.
Damit bleibt die Verantwortungsgrenze klar. gPdf verantwortet PDF-Rendering und Barcode-Zeichnung. Ihr System verantwortet Carrier-Transaktion, Sendungsstatus und die Semantik der Nutzdaten.
JSON Render versus Template Render
Nutzen Sie JSON Render, wenn Ihr Fulfillment-System das vollständige Layout erzeugt oder wenn das Operations-Team Koordinaten noch feinjustiert. Nutzen Sie Template Render, wenn das Lager ein stabiles Etikettenlayout freigegeben hat und jeder Aufrufer dieselben Datenfelder senden soll.
Beide Wege geben PDF aus. Der Unterschied ist, ob der Aufrufer das Layout bei
jedem Request beschreibt oder auf eine veröffentlichte template_id verweist.
Drucktests sind wichtig
Die Qualität von Thermoetiketten ist physisch. Validieren Sie die Ausgabe mit echtem Etikettenmaterial, echten Druckern und echten Scannern. Korrekte Barcode-Nutzdaten, Ruhezonen, Druckerdichte und carrier-spezifische Regeln sind Produktionsverantwortung außerhalb der Rendering-API.
FAQ
- Erstellt gPdf Carrier-Labels für mich?
- Nein. Ihr Carrier- oder Versandsystem erstellt die Sendung und die Barcode-Nutzdaten. gPdf rendert diese Daten als PDF-Etikett.
- Kann ich Template Render für Versandetiketten nutzen?
- Ja. Nutzen Sie JSON Render beim Entwerfen oder Testen des Etiketts und wechseln Sie zu Template Render, sobald das Layout stabil ist und Aufrufer nur noch Daten senden sollen.
- Gibt gPdf ZPL aus?
- Nein. Die öffentlichen Render-APIs geben PDF aus. Wenn Ihr Druckpfad ZPL benötigt, konvertieren oder routen Sie das PDF außerhalb von gPdf.
- Was sollte ich vor Produktion validieren?
- Drucken Sie auf echtem Drucker und Etikettenmaterial, scannen Sie den Barcode mit Produktionsscannern und bestätigen Sie, dass carrier-spezifischer Text und Nutzdaten aus Ihrem Versandsystem stammen.