Labelixa 0.2.0

Labelixa (.NET)

Thin .NET client for the Labelixa API: render, validate and convert thermal printer label code — ZPL, EPL, TSPL and CPCL — without a printer.

dotnet add package Labelixa

using Labelixa;

var client = new LabelixaClient();                                  // anonymous
var client = new LabelixaClient(apiKey: Environment.GetEnvironmentVariable("LABELIXA_API_KEY"));

byte[] png = await client.RenderPngAsync("^XA^FO50,50^A0N,40,40^FDHello^FS^XZ");
await File.WriteAllBytesAsync("label.png", png);

JsonElement report = await client.ValidateAsync(zpl);
Console.WriteLine(report.GetProperty("ozet").GetProperty("error").GetInt32() + " errors");

Requires .NET 8. No packages.

Backing off correctly

Quota answers have their own exception, because a caller that cannot tell 429 from a generic failure either never retries or retries immediately — and both are wrong.

try
{
    byte[] png = await client.RenderPngAsync(zpl);
}
catch (QuotaExceededException error)
{
    await Task.Delay(TimeSpan.FromSeconds(error.RetryAfter));
    // error.Action is "upgrade" or "addon" when the server suggests one
}

Reading a response

Response keys are stable wire names and most of them are Turkish; they never change inside /v1. The English name of every key is listed at https://labelixa.com/docs/api#response-fields. A real answer of ValidateAsync (POST /v1/diagnostics) for a label whose ^FD field is not closed (abridged only where marked):

{
  "diagnostics": [
    {
      "code": "ZPL2001",
      "severity": "warning",
      "message_key": "diag.zpl2001",
      "line": 1, "col": 19, "end_line": 1, "end_col": 27,
      "args": { "komut": "^FD" },           // komut: command
      "quickfix": {                          // a one-click fix
        "offset": 26, "end_offset": 26,
        "yeni": "^FS"                        // yeni: replacement text to insert at offset
        // (abridged: also a short English title and its message key)
      },
      // mesaj: message (always English)
      "mesaj": "^FD field data is not terminated with ^FS; real printers may misread the commands that follow",
      "onizleme": { "x": 50, "y": 50 },      // onizleme: preview position, in dots
      "url": "https://labelixa.com/zpl/rules/ZPL2001"
    }
  ],
  "ozet": { "toplam": 1, "error": 0, "warning": 1, "info": 0 },  // ozet: summary, toplam: total
  "alanlar": [{ "line": 1, "x": 50, "y": 50 }],                 // alanlar: fields (each ^FD / ^FV)
  "rfid": []
}

An error is a status code plus a body. Render endpoints answer with one line of plain text (dpmm must be 6, 8, 12 or 24); JSON endpoints carry an English sentence and, where one exists, a stable machine-readable name in kod (code) or hata_tipi (error type). When you read the raw body, branch on that name, never on the sentence. This client throws LabelixaException with Status and ServerMessage (the sentence only); the status code is the stable signal it exposes.

// 401 Unauthorized
// WWW-Authenticate: ApiKey realm="labelixa"
{
  // (abridged: the English sentence "Invalid API key", which the client
  //  puts in the exception message)
  "kod": "gecersiz_anahtar"   // kod: code (the key sent belongs to no account)
}

When each error happens and how to fix it: https://labelixa.com/docs/api#errors.

Using your application's HttpClient

Pass your own client — from IHttpClientFactory, with your own handlers, timeout and policies. It is used as-is and never mutated, so the API key stays on the requests this client makes and never leaks onto a client shared with the rest of your application.

public sealed class LabelService(IHttpClientFactory factory)
{
    private readonly LabelixaClient _labels = new(
        apiKey: "lbx_...",
        clientName: "erp-connector/2.1",
        httpClient: factory.CreateClient("labelixa"));
}

clientName is sent as X-Client so usage is attributed to the integration, never to a person.

What the client does

Every method maps 1:1 to a documented REST endpoint and there are no hidden retries: a retry that swallows a quota answer turns a clear signal into a slow mystery. https://labelixa.com/docs/api is the source of truth.

Reports come back as JsonElement rather than typed classes on purpose. The server owns those shapes and adds fields over time; a fixed class here would silently drop whatever this version has not heard of.

Two things worth knowing

A rendered preview is not a print guarantee. The render shows what the code draws; the printer adds firmware, resident fonts, media and calibration.

An invalid barcode is not a 4xx. The server answers 200 with an error image and an X-Warnings header. Handing that back as a generated barcode would be a lie, so this client turns it into an exception carrying the warning verbatim.

On-premise

var client = new LabelixaClient(baseUrl: "https://labels.internal.example");

The API key is only sent over https: a client with a key and a plain http base URL (other than localhost) throws ArgumentException. The default HttpClient never follows redirects, so a server cannot forward the key to another host. If you pass your own HttpClient, give it a handler with AllowAutoRedirect = false for the same guarantee.

Self-hosting and support

• Documentation: https://labelixa.com/docs/api
• Issues: https://github.com/Labelixa/labelixa-sdk/issues

MIT licensed.