API транспортных этикеток для PDF-этикеток 4x6
Генерируйте готовые к печати PDF-этикетки 4x6 из JSON заказа: с векторными штрихкодами, размерами страниц для labels и детерминированной перепечаткой на складе.
/api/v1/pdf/render Рендерить PDF нужного label-размера из данных заказа, получателя, сервиса и трекинга, чтобы склад или ecommerce backend могли надежно печатать одну и ту же этикетку 4x6 при fulfillment и детерминированно перепечатывать ее при необходимости.
Когда использовать эту API
- В вашей системе уже есть tracking number, адрес назначения, service text и barcode payload.
- Нужен PDF-вывод для Zebra, SATO, Honeywell или других процессов с термопринтерами.
- Нужны векторные модули штрихкода, а не растровое изображение штрихкода, вставленное в PDF.
- Один и тот же payload должен давать ту же этикетку для перепечатки и audit evidence.
Что она не заменяет
- Нужно купить postage, рассчитать стоимость shipment или создать carrier label через аккаунт перевозчика.
- Нужен endpoint-заменитель ZPL. gPdf возвращает PDF, а не язык команд принтера.
- Нужна carrier certification от gPdf. Проверка сканирования и приемки перевозчиком остается на вашей стороне.
Какой endpoint вызывать
/api/v1/pdf/render
JSON Render — путь по умолчанию для этого сценария.
/api/v1/template-render
Используйте, когда сценарию нужен связанный API-путь, контракт шаблона или проверка возможностей.
Минимальный запрос
POST /api/v1/pdf/render - минимальная этикетка 4x6 со штрихкодом трекинга.
{
"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
- PDF-страницы размера этикетки, включая процессы 4x6 inch.
- Векторный рендеринг штрихкодов для carrier и warehouse label content.
- Текст, адресные блоки, service marks, линии, рамки и опциональную привязку к template.
- Детерминированный PDF-вывод для складской перепечатки.
Что контролирует ваша система
- Аккаунт перевозчика, покупку postage, выбор сервиса и создание tracking number.
- Корректные barcode payloads, человекочитаемый текст, адреса и routing data.
- Настройку принтера, материал этикетки, scan testing и carrier acceptance checks.
Production-чеклист
- Напечатайте тестовые этикетки на реальной модели принтера и реальном label stock.
- Проверьте scan rate штрихкода при целевом DPI и расстоянии до сканера.
- Храните исходные shipment data или возвращенный PDF согласно вашей reprint policy.
- Используйте Template Render после утверждения layout этикетки и его повторного использования в системах.
- Держите carrier-specific logic вне render request.
Границы заявлений
- gPdf рендерит PDF этикетки; он не покупает postage и не обращается напрямую к перевозчикам.
- gPdf не является органом сертификации carrier labels.
- API выдает PDF, а не ZPL, EPL или другой command stream для термопринтера.
Форма API для транспортных этикеток
Страницы транспортных этикеток не являются отдельным carrier endpoint. Вы вызываете JSON Render со страницей размера этикетки, текстовыми блоками, линиями, опциональными изображениями и элементами штрихкода. Для повторяемых этикеток опубликуйте утвержденный layout как template и вызывайте Template Render с shipment data.
Так граница ответственности остается понятной. gPdf отвечает за PDF-рендеринг и отрисовку штрихкодов. Ваша система отвечает за carrier transaction, shipment state и смысл payload.
JSON Render или Template Render
Используйте JSON Render, когда fulfillment-система генерирует весь layout или когда операционная команда еще настраивает координаты. Используйте Template Render, когда склад утвердил стабильный layout этикетки и все callers должны отправлять один и тот же набор полей.
Оба пути возвращают PDF. Разница в том, описывает ли caller layout в каждом
request или ссылается на опубликованный template_id.
Print testing имеет значение
Качество термоэтикетки физически зависит от носителя и оборудования. Проверяйте вывод на реальном label stock, реальных принтерах и реальных сканерах. Корректность barcode payload, quiet zones, плотность печати и правила конкретного перевозчика остаются production-ответственностью вне render API.
FAQ
- Создает ли gPdf carrier labels за меня?
- Нет. Перевозчик или ваша shipping-система создает shipment перевозчика и barcode payload. gPdf рендерит эти данные в PDF-этикетку.
- Можно ли использовать Template Render для транспортных этикеток?
- Да. Используйте JSON Render при проектировании или тестировании этикетки, а Template Render — когда layout стабилен и вызывающие системы должны отправлять только data.
- Выдает ли gPdf ZPL?
- Нет. Публичные render API выдают PDF. Если вашему print path нужен ZPL, конвертируйте или маршрутизируйте PDF вне gPdf.
- Что нужно проверить перед production?
- Печатайте на реальном принтере и label stock, сканируйте штрихкод production-сканерами и подтвердите, что carrier-specific text и payloads приходят из вашей shipping-системы.