Đây có phải API nhãn hoàn trả độc lập không?

Có. Trang này ánh xạ quy trình nhãn hoàn trả vào endpoint công khai POST /api/v1/pdf/render. Hệ thống của bạn vẫn sở hữu dữ liệu nghiệp vụ, còn gPdf chỉ tạo PDF từ request hợp lệ.

Khi nào nên dùng Template Render?

Dùng Template Render khi bố cục đã được duyệt và bạn muốn gọi bằng template_id cùng data thay vì gửi toàn bộ tọa độ ở mỗi request.

API có trả PDF trực tiếp không?

Có. Khi kết xuất thành công, API trả về application/pdf. Khi lỗi, API dùng JSON error envelope chung với mã API-XXX và req_id.

Cần kiểm tra gì trước production?

Hãy in thử bằng máy in thật, kiểm tra scan mã vạch và xác nhận với hãng vận chuyển, marketplace hoặc quy trình kho liên quan.

Logistics và nhãn

API nhãn hoàn trả cho reverse logistics thương mại điện tử

Tạo PDF nhãn hoàn trả và hướng dẫn hoàn trả từ dữ liệu ecommerce hoặc support, với trang cỡ label, mã vạch và template reprint.

API CHÍNH JSON Render

ENDPOINT /api/v1/pdf/render

HỆ THỐNG backend thương mại điện tử / cổng hoàn trả / OMS / backend 3PL

Thử trong Playground Đọc tài liệu

Việc cần giải quyết

Kết xuất PDF nhãn hoàn trả hoặc tờ hướng dẫn hoàn trả từ dữ liệu RMA, khách hàng, mặt hàng, đích đến và mã vạch để cổng returns cung cấp tài liệu xác định cho khách hàng.

Khi nào dùng API này

Hệ thống của bạn đã có dữ liệu cần in, payload mã vạch và nội dung hiển thị.
Bạn cần đầu ra PDF cho quy trình in kho, fulfillment hoặc vận hành.
Bạn muốn mã vạch vector thay vì ảnh raster dán vào PDF.
Bạn cần cùng payload kết xuất ra cùng tài liệu để reprint và audit.

Những gì không thay thế

Bạn cần mua vận chuyển, tính cước hoặc tạo nhãn hãng vận chuyển qua tài khoản hãng vận chuyển.
Bạn cần endpoint thay thế ZPL/EPL. gPdf trả về PDF, không phải máy in command language.
Bạn cần gPdf chứng nhận hãng vận chuyển hoặc quy trình vận hành. Kiểm thử scan và acceptance vẫn thuộc về bạn.

Endpoint cần gọi

CHÍNH

/api/v1/pdf/render

JSON Render là đường mặc định cho quy trình này.

PHỤ 1

/api/v1/template-render

Dùng khi quy trình cần API liên quan, hợp đồng mẫu hoặc truy vấn năng lực.

Request tối thiểu

POST /api/v1/pdf/render - nhãn hoàn trả.

{
  "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 xử lý gì

Trang PDF cỡ label hoặc tài liệu vận hành theo request.
Kết xuất mã vạch vector cho nội dung hãng vận chuyển, kho hoặc vận hành.
Văn bản, block địa chỉ, service marks, đường kẻ, khung và binding template tùy chọn.
Đầu ra PDF xác định cho reprint trong kho.

Hệ thống của bạn quản lý gì

Tài khoản hãng vận chuyển hoặc marketplace, lựa chọn dịch vụ và tạo mã tracking nếu có.
Payload mã vạch đúng, text đọc được, địa chỉ, routing data và dữ liệu vận hành.
Thiết lập máy in, vật liệu nhãn, kiểm thử scan và kiểm tra acceptance.

Checklist đưa vào production

In thử trên đúng model máy in và vật liệu nhãn.
Kiểm tra tỷ lệ scan mã vạch ở DPI và khoảng cách máy quét mục tiêu.
Lưu dữ liệu nguồn hoặc PDF trả về theo reprint policy.
Dùng Template Render khi bố cục đã duyệt và được nhiều hệ thống dùng lại.
Giữ logic hãng vận chuyển hoặc đặc thù marketplace ngoài request kết xuất.

Ranh giới tuyên bố

gPdf kết xuất PDF tài liệu; gPdf không mua vận chuyển hoặc gọi trực tiếp hãng vận chuyển.
gPdf không phải cơ quan chứng nhận hãng vận chuyển, marketplace hoặc GS1.
API tạo đầu ra PDF, không phải ZPL, EPL hoặc command stream của máy in nhiệt.

Reverse logistics cần ranh giới sở hữu rõ ràng

API nhãn hoàn trả phù hợp khi hệ thống của bạn đã quyết định dữ liệu cần in và chỉ cần tạo PDF ổn định. gPdf nhận dữ liệu có cấu trúc, bố cục hoặc template, rồi kết xuất thành PDF có thể in và reprint.

Các quyết định nghiệp vụ như hãng vận chuyển, mã tracking, routing, dữ liệu sản phẩm, tồn kho, quy tắc marketplace hoặc kiểm thử acceptance vẫn nằm ngoài gPdf. Điều này giữ đường kết xuất rõ ràng: gPdf tạo tài liệu; hệ thống vận hành của bạn quyết định tài liệu đó có đúng để dùng hay không.

FAQ

Đây có phải API nhãn hoàn trả độc lập không?: Có. Trang này ánh xạ quy trình nhãn hoàn trả vào endpoint công khai POST /api/v1/pdf/render. Hệ thống của bạn vẫn sở hữu dữ liệu nghiệp vụ, còn gPdf chỉ tạo PDF từ request hợp lệ.
Khi nào nên dùng Template Render?: Dùng Template Render khi bố cục đã được duyệt và bạn muốn gọi bằng template_id cùng data thay vì gửi toàn bộ tọa độ ở mỗi request.
API có trả PDF trực tiếp không?: Có. Khi kết xuất thành công, API trả về application/pdf. Khi lỗi, API dùng JSON error envelope chung với mã API-XXX và req_id.
Cần kiểm tra gì trước production?: Hãy in thử bằng máy in thật, kiểm tra scan mã vạch và xác nhận với hãng vận chuyển, marketplace hoặc quy trình kho liên quan.