API Reference

Complete field reference for the xPdf Label API.

---

Endpoints

Version	Path	Auth	Description
V3	POST /api/v3/label	Bearer Token	Production SaaS endpoint
V2	POST /api/v2/label	None	Testing / Demo
V1	POST /api/v1/label	Internal Token	System integration

---

Request Structure

{
  "settings": { ... },
  "header": { ... },
  "footer": { ... },
  "pages": [ ... ]
}

Settings (Optional)

"settings": {
  "defaults": {
    "font_family": "NotoSans",
    "font_size": 12,
    "color": "#000000",
    "unit": "mm"
  },
  "metadata": {
    "title": "My Document",
    "author": "Author Name",
    "language": "en"
  },
  "profile": "pdfa2b"
}

Header / Footer (Optional)

"header": { "height": 20, "elements": [ ... ] },
"footer": { "height": 15, "elements": [ ... ] }

• Variables: {page} is replaced with current page number.
• Auto-pagination: Tables exceeding page height automatically create new pages with repeated header/footer.

Pages (Required)

"pages": [
  { "width": 100, "height": 150, "elements": [ ... ] }
]

---

Element Types

All elements are distinguished by their type field:

Type	Description
text	Text content
barcode	1D/2D barcodes
line	Line segments
rect	Rectangles
image	Images
table	Data tables

---

Text Element

{
  "type": "text",
  "x": 10, "y": 20,
  "content": "Hello World",
  "style": {
    "font_family": "Roboto",
    "font_size": 14,
    "font_weight": "bold",
    "color": "#000000",
    "text_align": "left",
    "vertical_align": "top",
    "line_height": 1.5,
    "width": 80,
    "height": 20
  }
}

Rich Text Tags:

• \n - Line break
• [B]...[/B] - Bold
• [L]...[/L] - Large (1.5x size)

---

Barcode Element

{
  "type": "barcode",
  "x": 10, "y": 50,
  "format": "code128",
  "content": "ABC123",
  "width": 60,
  "height": 20,
  "options": {
    "quiet_zone": 2,
    "bar_width": 0.5,
    "color": "#000000",
    "background_color": "#FFFFFF"
  },
  "hrt": {
    "enabled": true,
    "content": "ABC-123",
    "style": { "font_size": 8, "text_align": "center" }
  }
}

Supported Formats:

Category	Formats
1D	code128, code39, ean13, ean8, upca, itf, codabar
2D	qrcode, datamatrix, pdf417, aztec, maxicode

---

Shape Elements

Line

{
  "type": "line",
  "x1": 0, "y1": 0,
  "x2": 100, "y2": 50,
  "stroke_width": 1,
  "stroke_color": "#000000"
}

Rectangle

{
  "type": "rect",
  "x": 0, "y": 0,
  "width": 100, "height": 50,
  "fill_color": "#FFFFFF",
  "stroke_color": "#000000",
  "corner_radius": 2
}

---

Image Element

{
  "type": "image",
  "x": 10, "y": 10,
  "width": 30, "height": 30,
  "data": "logo.png"
}

• data: Filename (loaded from assets/images) or Base64 string.

---

Table Element

{
  "type": "table",
  "x": 10, "y": 100,
  "width": 150,
  "data": {
    "columns": [
      { "field": "name", "title": "Product", "width": 60 },
      { "field": "qty", "title": "Qty", "width": 30 }
    ],
    "records": [
      { "name": "iPhone", "qty": "10" }
    ]
  },
  "layout": {
    "show_col_header": true,
    "row_height": 10
  }
}

Cell Merging: { "value": "Total", "col_span": 3 }

---

Coordinate System

• Unit: Millimeters (mm)
• Origin: Top-left corner (0, 0)
• X-axis: Increases to the right →
• Y-axis: Increases downward ↓

---

Response

Success: 200 OK with Content-Type: application/pdf

Error:

{
  "error": true,
  "code": "API-001",
  "message": "Invalid JSON structure",
  "req_id": "uuid-v4"
}

Code	Description
API-00x	Input errors (JSON, validation)
API-10x	Auth errors (missing token, rejected)
API-50x	System errors