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.
| Type | Fields |
|---|---|
text | text, font (cursive, script, block, gothic), size_mm, line_height, paragraph_gap, letter_spacing_mm, word_spacing, align, mix_fonts, shrink_to_fit |
qr | data, module_mm, ec (l, m, q, h), align, caption, caption_size_mm |
svg | svg (the SVG text), width_mm, align, variants (more versions, one is picked per sheet) |
line | x1_mm, y1_mm, x2_mm, y2_mm |
spacer | height_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.