ZplJet 1.0.0

ZplJet

Official .NET SDK for the ZPLJet API — fast ZPL → PDF/PNG conversion.

• Zero dependencies on modern .NET (a single System.Text.Json reference on netstandard2.0 only)
• Fully documented — XML docs on every public member, typed results and exceptions
• Reliable by default — automatic retries with exponential backoff (honoring Retry-After), per-attempt timeouts, CancellationToken support
• Broad reach — targets net8.0 and netstandard2.0 (works on .NET Framework 4.7.2+, .NET 6/8/10, Unity, Mono)

Installation

dotnet add package ZplJet

Quickstart

Create an API key in the dashboard (keys look like zpl_…), then:

using ZplJet;

using var zpljet = new ZplJetClient(Environment.GetEnvironmentVariable("ZPLJET_API_KEY")!);

LabelData label = await zpljet.ConvertAsync(
    new ConvertRequest("^XA^FO50,50^A0N,50,50^FDHello^FS^XZ"));

await File.WriteAllBytesAsync("label.pdf", label.Data);

Keep your API key server-side. Anyone with the key can spend your quota. Create one ZplJetClient and reuse it — it is thread-safe and pools its HTTP connections.

Usage

Convert to PDF or PNG

Unset values use API defaults. Use ConvertToUrlAsync for hosted output.

LabelData label = await zpljet.ConvertAsync(new ConvertRequest(zpl)
{
    Format = LabelFormat.Png,
    Dpmm = Dpmm.D12,
    WidthMm = 101.6,
    HeightMm = 152.4,
});

label.Data;        // byte[] — the file
label.ContentType; // "application/pdf" | "image/png"
label.Id;          // conversion id (shows up in your dashboard)

Hosted URLs (paid plans)

ConvertToUrlAsync returns a hosted public link. Retention follows the account setting and plan limit.

HostedLabel hosted = await zpljet.ConvertToUrlAsync(new ConvertRequest(zpl));

hosted.Url;           // public URL to the PDF (works until the file is deleted)
hosted.Pages;         // pages rendered (one per ^XA…^XZ block)
hosted.RetentionDays; // how long the file is kept
hosted.ExpiresAt;     // when the file is deleted and the URL stops working (DateTimeOffset, UTC)

Error handling

Every API error code maps to a dedicated exception, so you branch with catch clauses — no string matching:

try
{
    LabelData label = await zpljet.ConvertAsync(new ConvertRequest(zpl));
}
catch (BadRequestException ex)
{
    Console.WriteLine($"Invalid request ({ex.Param}): {ex.Message}");
}
catch (QuotaExceededException ex)
{
    Console.WriteLine($"Quota used up ({ex.Used}/{ex.Quota}), resets {ex.ResetsAt}");
}
catch (RateLimitException ex)
{
    Console.WriteLine($"Rate limited — retry after {ex.RetryAfter}");
}
catch (ConversionFailedException ex)
{
    Console.WriteLine($"Engine rejected the ZPL (conversion {ex.ConversionId})");
}
catch (ApiConnectionException ex)
{
    Console.WriteLine($"Network problem: {ex.Message}");
}

All of these extend ZplJetException, and every HTTP error carries Status, Code, DocUrl, and the raw error payload in Raw. Full code reference: zpljet.com/docs/errors.

Retries

Rate limits, transient 5xx responses, timeouts, and network failures retry up to twice by default. Retries use exponential backoff and honor Retry-After. conversion_failed is never retried.

Timeouts & cancellation

Each attempt has a 60-second timeout by default, and every method takes a CancellationToken:

using var zpljet = new ZplJetClient(new ZplJetClientOptions
{
    ApiKey = "zpl_…",
    BaseUrl = "https://api.zpljet.com",
    Timeout = TimeSpan.FromSeconds(10),
    MaxRetries = 5,
    HttpMessageHandler = myHandler,
});

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
await zpljet.ConvertAsync(new ConvertRequest(zpl), cts.Token);

A timed-out attempt throws ApiTimeoutException (after retries); your own cancellation surfaces as OperationCanceledException and is never retried.

Examples

Runnable examples live in examples/:

ZPLJET_API_KEY=zpl_… dotnet run --project examples/ZplJet.Examples -- pdf

Contributing & development

dotnet build
dotnet test

ZPLJET_API_KEY=zpl_… dotnet test --filter Category=E2E

License

MIT