Skip to content
PenBlitz
← Developers

API: templates and documents

The format of a document, and how to store and reuse it as a template.

Templates

  • GET /api/v1/templates lists all templates, GET /api/v1/templates/{id} returns one.
  • PUT /api/v1/templates/{id} stores a template, creating it if needed.
  • GET /api/v1/templates/{id}/variables lists the placeholders a template uses.
  • Included: letter, card, postcard, envelope-dl, voucher-qr and calibration.

A document

A document is a page, handwriting settings and a list of blocks. All measures are millimetres. Everything except the blocks is optional.

{
  "name": "Thank you",
  "page": { "width_mm": 210, "height_mm": 297,
            "margin_left": 22, "margin_right": 22, "margin_top": 26, "margin_bottom": 22 },
  "humanize": { "enabled": true, "intensity": 1.0, "page_offset_jitter_mm": 1.0 },
  "blocks": [
    { "type": "text", "text": "Dear {{first_name}},\n\nthank you!", "font": "cursive", "size_mm": 5.5 },
    { "type": "spacer", "height_mm": 6 },
    { "type": "qr", "data": "https://shop.example/?c={{code|url}}", "module_mm": 1.5, "ec": "l",
      "caption": "{{code}}" }
  ]
}

Blocks

Text, QR and SVG blocks follow each other down the page. Give x_mm and y_mm to pin a block to a position; a text block also takes width_mm for its column.

TypeFields
texttext, font (cursive, script, block, gothic), size_mm, line_height, paragraph_gap, letter_spacing_mm, word_spacing, align, mix_fonts, shrink_to_fit
qrdata, module_mm, ec (l, m, q, h), align, caption, caption_size_mm
svgsvg (the SVG text), width_mm, align, variants (more versions, one is picked per sheet)
linex1_mm, y1_mm, x2_mm, y2_mm
spacerheight_mm

Page rules

  • Nothing may be written outside the page margins; such a sheet gets a warning.
  • On cards and standard letters postal_zones keeps the stamp area, the bottom 15 mm and the right edge free. Set it to false for cards that are not posted.
  • rotate turns the finished page by 0, 90, 180 or 270 degrees for machines that feed sideways.