API этикеток возврата для ecommerce reverse logistics
Генерируйте PDF-этикетки возврата и return instructions из ecommerce или support data: с label-size страницами, штрихкодами и template-перепечаткой.
/api/v1/pdf/render Рендерить PDF-этикетки возврата или листы с инструкциями возврата из RMA, customer, item, destination и barcode data, чтобы returns portal мог выдать клиенту детерминированный документ.
Когда использовать эту API
- Ваша система уже создала RMA и return authorization.
- Перевозчик или returns system уже передали label payload или tracking data.
- Нужна PDF-этикетка или лист инструкций, который можно скачать, отправить по email или перепечатать.
- Один и тот же return label layout должен использоваться повторно через Template Render.
Что она не заменяет
- Нужно, чтобы gPdf одобрил возврат, купил postage или создал carrier shipment.
- Нужна прямая carrier API orchestration.
- Нужен printer command output, например ZPL.
Какой endpoint вызывать
/api/v1/pdf/render
JSON Render — путь по умолчанию для этого сценария.
/api/v1/template-render
Используйте, когда сценарию нужен связанный API-путь, контракт шаблона или проверка возможностей.
Минимальный запрос
POST /api/v1/pdf/render - return label со штрихкодом RMA.
{
"pages": [
{
"size": "label_4_6_in",
"elements": [
{
"type": "text",
"x": 5,
"y": 8,
"content": "RETURN TO",
"style": { "font_size": 9, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 5,
"y": 18,
"content": "Acme Returns\n500 Dock Door 4\nColumbus OH 43215",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "code128",
"content": "RMA-2026-77881",
"x": 5,
"y": 70,
"width": 88,
"height": 20,
"barcode_text": { "enabled": true, "position": "bottom" }
}
]
}
]
}
Что выполняет gPdf
- PDF-рендеринг label-size return labels и страниц инструкций.
- Штрихкоды, текст, адреса, RMA и service blocks.
- Template binding для утвержденных return label или instruction layouts.
- Детерминированный вывод для повторных скачиваний клиентом и support reprints.
Что контролирует ваша система
- Return eligibility, RMA state, carrier account, postage, tracking number и customer messaging.
- Корректные barcode payloads, destination address, item references и return window rules.
- Email delivery, portal download и support audit trail.
Production-чеклист
- Проверьте return payload у перевозчика или returns provider перед рендерингом.
- Печатайте и сканируйте этикетки на том же stock, который будут использовать клиенты или магазины.
- Добавляйте X-Request-Id и храните RMA-to-PDF trace в support logs.
- Сделайте повторные downloads идемпотентными с точки зрения клиента.
- Отделяйте label rendering от логики refund approval.
Границы заявлений
- gPdf рендерит PDF-этикетки возврата; он не авторизует возвраты и не покупает postage.
- Carrier acceptance и корректность barcode payload остаются вашей ответственностью.
- Публичный API возвращает PDF, а не ZPL или прямые команды принтера.
Reverse logistics требует ясной ответственности
Return labels соединяют customer experience и правила перевозчика. gPdf отвечает за PDF-рендеринг. Ваша returns-система отвечает за eligibility, RMA state, tracking, carrier payloads и customer communication.
Держите эту границу видимой в интеграции. Сначала создайте решение по возврату, затем рендерьте документ из финальных данных.
FAQ
- Создает ли gPdf return shipment?
- Нет. Ваш carrier или returns platform создает shipment и payload. gPdf рендерит эти данные в PDF.
- Можно ли генерировать return labels из templates?
- Да. Используйте Template Render после утверждения return label или instruction layout.
- Может ли PDF включать инструкции по возврату?
- Да. Один render request может создать страницу этикетки, страницу инструкций или оба варианта, в зависимости от вашего layout.
- Заменяет ли gPdf carrier certification?
- Нет. Carrier acceptance, scanner tests и payload rules остаются вашей ответственностью.