Integrations and the API

The complete, interactive API description is at API docs (Help → API docs). There you can also try every call: click Authorize, paste a token, open a call, Try it out.

Postman

Two downloads under Help set up Postman:

• Postman collection — every API call with sample data.
• Postman environment — all the variables the collection uses (baseUrl, token, client_id, client_secret, site_id, plant, template_code, printer_id, username, run_id, job_id), with baseUrl already pointing at this server.

Import both files in Postman, select the environment labelpipe — local Mac at the top right, fill in token (or client_id and client_secret, then run OAuth 2.0 token) and run Ping first. Print and preview requests remember the job id in the environment, so the Jobs requests work right after them. For another server, duplicate the environment and change baseUrl and the credentials.

Ways to print

1. Stored templates — POST /api/v1/print-jobs with the template code, store and products. The template decides the layout.
2. Dynamic ZPL — POST /api/v1/zpl/print-jobs (or /zpl/render to only get the result). The request contains the ZPL with placeholders, their values and the label setup; nothing is stored as a template.
3. Document forms — POST /api/v1/documents/print-jobs (or /documents/renders for the PDF) with the form code, the store and one document: header values plus the list of table rows. See Document forms; Postman folder 6 · Document forms has a sample delivery note (create a form with the code delivery-note first).

Dynamic ZPL example

{
  "site_id": "demo-main",
  "zpl": "^XA^FO20,20^A0N,32,32^FD{{name}}^FS^FO20,70^A0N,60,60^FD{{price}} €^FS^XZ",
  "label": { "dpi": 203, "width_mm": 58, "height_mm": 40, "copies": 1, "darkness": 5 },
  "records": [
    { "copies": 2, "fields": { "name": "Бормашина", "price": "89.90" } }
  ]
}

Label setup: dpi (152/203/300/600), width_mm/height_mm (adds ^PW/^LL, needed for previews; png/pdf previews go through the driver chosen in Setup → ZPL preview, named in the X-Preview-Driver header and the JSON driver field, at most 60 a minute per client), copies, darkness (^MD), speed (^PR), orientation (normal/inverted), home_x/home_y (^LH). Settings already in your ZPL win.

Placeholders without a value print empty and are listed in missing_fields; send "strict": true to reject such requests instead.

Stores, printers and users

With a token that has the directory:read ability, a system can look up:

• GET /api/v1/sites: the stores this client may use, each with its printers and default printer
• GET /api/v1/sites/{code}: one store
• GET /api/v1/printers?site=demo-main&accepts=zpl: printers, optionally for one store or only PDF/ZPL printers
• GET /api/v1/users?search=geras: users found by login name, e-mail or name, with their stores and printers
• GET /api/v1/users/{username}: one user by login name, e.g. alex

Results only contain the client’s own stores. Set a user’s login name under Access → Users.

When you issue a token (Access → Integration clients → Issue token), choose its abilities:

• Print and preview labels (labels:submit)
• Look up stores, printers and users (directory:read)

Every token has an expiry date: one year at most (LABELPIPE_API_TOKEN_LIFETIME_DAYS), and you can choose an earlier date. Issue a new token before the old one expires. Tokens from OAuth 2.0 token last one hour.

The API log

Access → API log lists every call to the API, including refused ones (wrong token, unknown store, and so on). For each call it shows:

• the time, the client, the status, how long it took, and the error code
• the request and response bodies, and a link to the print job

Tokens are masked, and generated files (PDF, images) are not stored. Entries are kept for 30 days, which you can change with API_LOG_RETENTION_DAYS. Use the filters to find failed calls or the calls of one client.

Logging in

Systems can log in in three ways — choose what the other system supports:

GET /api/v1/ping answers ok with the client name and its stores — the quickest test of a connection. GET /api/v1/usage returns the edition, labels generated today against the daily limit, when it resets, and the stores, users, printers and integration clients against their limits. Over the daily limit a job is refused with 429 quota_exceeded and a Retry-After header (see Editions and usage).

Refused calls

• 401: wrong, expired or revoked token, or wrong client ID and secret. After 20 failed logins from one address in a minute, that address gets 429 Too many requests for the rest of the minute, even with correct credentials.
• 403 ip_not_allowed: the client has Allowed source IPs / CIDR set, and the call came from another address. Leave the list empty to allow any address. Behind a reverse proxy, the administrator sets LABELPIPE_TRUSTED_PROXIES so the real caller’s address is used.

SAP S/4HANA Cloud

SAP calls labelpipe as an outbound HTTP service. In short:

1. enter each store’s SAP plant (Setup → Sites),
2. create an integration client for SAP and give it a Client ID & secret,
3. in SAP, create the communication scenario, system and arrangement with that ID and secret.

SAP can send its own formats: plant instead of site_id, numbers for prices, and dates like 20261008 or 2026-10-08. Errors come back in the OData style that SAP understands, and the X-CorrelationID header links SAP’s log with Access → API log. Administrators find the step-by-step guide with example code under Help → Developer docs → SAP S/4HANA Cloud integration guide.

Good practice

• Send money and article numbers as text: "price": "89.90", "sku": "001234". Numbers are accepted too.
• Send an Idempotency-Key header when retrying: the same key returns the original job instead of printing twice.
• submitted means the print server accepted the job; check delivery_unknown jobs before reprinting.