Preview a sheet print
const url = 'https://example.com/api/v1/print/example/sheet/preview';const options = { method: 'POST', headers: {'X-Label-Hub-Key': '<X-Label-Hub-Key>', 'Content-Type': 'application/json'}, body: '{"expected_cells":[{"cells":[1],"id_cell":1,"sheet":"example"}],"items":[{"content_type":"qr_only","data":{"items":[],"primary_id":"example","qr_payload":"example","secondary":[],"title":"example"},"lookup":{"app":"example","identifier":"example"},"purpose":"example","ref":"example","source":"example"}],"placements":[{"cells":"first_free","count":1,"new_sheet":{"id_placement":"cell","type":"example","version":1},"sheet":"example","skip":[1]}],"tray":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/print/example/sheet/preview \ --header 'Content-Type: application/json' \ --header 'X-Label-Hub-Key: <X-Label-Hub-Key>' \ --data '{ "expected_cells": [ { "cells": [ 1 ], "id_cell": 1, "sheet": "example" } ], "items": [ { "content_type": "qr_only", "data": { "items": [], "primary_id": "example", "qr_payload": "example", "secondary": [], "title": "example" }, "lookup": { "app": "example", "identifier": "example" }, "purpose": "example", "ref": "example", "source": "example" } ], "placements": [ { "cells": "first_free", "count": 1, "new_sheet": { "id_placement": "cell", "type": "example", "version": 1 }, "sheet": "example", "skip": [ 1 ] } ], "tray": "example" }'Plans where the items would go and draws them, without reserving or printing anything. Per page: every cell with its state, a 150 dpi PNG of the new content only, whether the sheet ID and the feed-direction mark are printed, and where. Also the cells left free, the plan to send back as expected_cells, and where lookup items were printed before. The picture is never calibrated. Only page (IPP) printers print sheets. A run plans one sheet: a second placement is refused (preview_too_large), and the items the sheet does not take are left out (placed, remaining).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Printer slug or UUID.
Printer slug or UUID.
Request Bodyrequired
Section titled “Request Bodyrequired”object
What a preview promised for one page; the print refuses a different plan.
One label to print: a content type plus raw data or an integration lookup.
purpose is what the cell is recorded as (default: the label’s title, else its primary
id). source names the origin of raw data (default api); a lookup is recorded under
the integration’s name and its identifier as ref.
object
Tape-independent semantic content types for label rendering.
Raw label data of a sheet item: the same fields, every free text bounded.
A page job stores its labels in the job row, and a preview renders them, so the sizes are
capped at the request: qr_payload at 512 characters, every other text at 512, at most
10 secondary lines and 100 items (listing rows). A cell shows far less than that;
the renderer shortens what does not fit. Since #258 the tape RawLabelData carries the
same caps, so this class adds nothing but its name.
object
Resolve label data via an integration plugin.
object
Either an existing sheet (sheet) or a new one (new_sheet), never both.
Items fill the placements in order; the last placement may leave count out and takes
the rest. cells and skip belong to an existing sheet only.
object
first_free, or the cell numbers, in the order the items fill them.
Cells first_free leaves out for this request (never stored).
Responses
Section titled “Responses”Successful Response
object
Free cells left on each page’s sheet afterwards.
object
object
New cells only: may be cut off by this printer’s hardware margins.
The sheet ID label of a cell sheet.
Drawn as text because the sheet type has no QR (spec 12.5).
Text had to be shortened to fit.
The feed-direction mark is printed on this page.
object
No margin band is deep enough: no ID on this page.
The sheet ID is printed in a margin band on this page.
1-bit PNG, 150 dpi, page size: only the new content.
Items this run places: the first ones of items, as many as the sheet takes.
Items left out because one run prints one sheet; print them in another run.
Where lookup items were printed before: the newest ones per item, on the first copy of the item. reprint_totals has the full count.
One earlier print of a lookup item: a used cell it was printed into.
object
The cell of the earlier print.
Index of the item in items. Only on the first copy of an item (the first item with this source and ref): its other copies, and later cart lines of the same item, carry no hints.
When the cell was printed (UTC).
The sheet the earlier print is on.
One entry per item that has reprint_hints: the count of all its earlier prints.
How often an item was printed before: all earlier prints, not only the listed ones.
object
The item the hints are on (see ReprintHint.item_index).
Earlier prints of the item per sheet code.
object
Earlier prints of the item; reprint_hints lists the newest ones only.
Example
{ "pages": [ { "cells": [ { "state": "used" } ], "geometry": { "page_size": "A4", "shape": "rectangle" }, "margin_band": "top" } ]}These credentials may not use this printer (printer_not_allowed).
Unknown printer (printer_not_found), sheet (sheet_not_found), sheet type, or an item the integration does not have (app-lookup-not-found).
Not a page printer (media_kind_mismatch), the printer is disabled (printer_disabled), the sheet is discarded or archived, or the cells do not fit (insufficient_cells, cells_taken).
Invalid request (invalid_request, field paths only), an unknown or disabled tray (tray_unknown), an item the cell cannot show (content_type_data_mismatch), a plan of more than one sheet (preview_too_large), or an unknown integration (integration_unknown_app). Item errors carry item_index.
The key has a preview in progress already, or a render of the key is stuck past the time limit (too-many-previews): one per key at a time. The body has the rate limit’s shape (retry_after_seconds).
An integration lookup failed (integration_lookup_failed).
An integration is not configured (integration_not_configured), or no render slot became free in time (render-unavailable): every slot is held by a stuck render, the callers without a key have a stuck render, or the wait for the caller’s turn (one slot per key, one for all callers without a key) reached LABELYARD_RENDER_TIMEOUT_S.
A page took longer than LABELYARD_RENDER_TIMEOUT_S to draw (render-timeout). The drawing goes on: the key’s next preview answers 429 too-many-previews until it has ended.