Introduction

zplflow is an API-first platform for thermal label conversion. It converts bidirectionally between PDF and ZPL (Zebra Programming Language), applies programmable transformations via pipelines, and handles both synchronous inline conversions and asynchronous batch workflows.

Base URL: https://api.zplflow.io/v1

Execution Modes

zplflow provides two distinct execution paths:

Synchronous Conversion (/v1/convert/*): Inline, low-latency transformations. The payload is sent in the HTTP request body and converted data returns immediately in the JSON response.
Asynchronous Jobs (/v1/jobs): Batch processing backed by presigned S3 storage and background workers. Recommended for high-volume batches and heavy files.

Key Concepts

Jobs Lifecycle

Asynchronous conversions are managed as jobs with strict state transitions:

created → queued → running → succeeded
    ↓        ↓         ↘ failed
canceled  canceled

Status	Meaning	Token State
`created`	Job created; awaiting S3 payload upload	`reserved`
`queued`	Document uploaded and enqueued for async workers	`reserved`
`running`	Conversion currently in progress	`reserved`
`succeeded`	Conversion complete; output files available	`committed`
`failed`	Conversion failed; error details recorded	`rolled_back`
`canceled`	Job canceled by client before execution	`rolled_back`

Tokens

Tokens represent the resource accounting unit. Operations debit a fixed number of tokens from your balance:

PDF → ZPL: 3 tokens per page at 203 DPI; 4 tokens per page at 300 DPI.
ZPL → PDF: 1 token per label.
Pipelines: 1 base token per label (covers all DOM/textual steps), plus 3 tokens per heavy transform step (scale, rotate, crop, mirror, margin, or image insertion).

See Conversions for complete token accounting rules.

Quick Start

1. Authenticate

Retrieve your API key from the web console. Pass it via the standard Bearer authorization header:

Authorization: Bearer lb_YOUR_API_KEY

2. Convert PDF to ZPL (Synchronous)

Send the binary PDF payload with conversion parameters. The response contains the Base64-encoded ZPL output.

curl -s -X POST "https://api.zplflow.io/v1/convert/pdf-to-zpl?dpi=203&max_kb=64" \
  -H "Authorization: Bearer lb_YOUR_API_KEY" \
  -H "Content-Type: application/pdf" \
  -H "Idempotency-Key: 7b843799-a9a3-4414-b80c-519842a22bc7" \
  --data-binary @label.pdf

3. Convert ZPL to PDF (Synchronous)

Send the raw ZPL string with Content-Type: text/plain. The response contains the Base64-encoded PDF pages.

curl -s -X POST "https://api.zplflow.io/v1/convert/zpl-to-pdf" \
  -H "Authorization: Bearer lb_YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  -H "Idempotency-Key: 8a5d3e21-0b6c-489e-9d2a-1f3c84b12345" \
  --data-binary '^XA^FO50,50^A0N,30,30^FDHello World^FS^XZ'

Next Steps

Installation — Account setup and authentication details
Conversions — Synchronous endpoint specifications and response formats
Jobs API — Asynchronous processing for batch workloads
Pipelines — Programmable ZPL label transformation engine
Best Practices — Production integration and error-handling patterns