LabelInn 3.1.0

LabelInn C# SDK

Official .NET client for the LabelInn Cloud Print API. Send labels to thermal printers (Zebra, TSC, Honeywell), manage your fleet, and build print automation workflows — all from C#.

Zero external dependencies. Uses built-in HttpClient and System.Net.Http.Json.

Table of Contents

• Installation
• Quick Start
• Authentication
• Print Jobs
• Fleet Management
• Designs (Templates)
• Webhooks
• Data Connect
• Printer Commands, Passports, GHS and UFI
• Local Edge API (LAN, pinned TLS)
• Error Handling
• Configuration

Installation

dotnet add package LabelInn

Requires .NET 6.0 or later.

Quick Start

using LabelInn;

// Initialize client
var client = new LabelInnClient("sk_live_your_key_here");

// Print from a template
var job = await client.Print.CreateAsync(new CreateJobRequest
{
    PrinterId = "prt_abc123",
    PayloadType = "template",
    DesignId = "tmpl_shipping",
    Data = new Dictionary<string, string>
    {
        ["name"] = "Jane Doe",
        ["order"] = "ORD-4521",
        ["barcode"] = "TR123456789"
    },
    Copies = 2
});

Console.WriteLine($"Job {job.Id} → {job.Status}");

Authentication

Get your API key from LabelInn → Settings → API Keys.

// Test mode (sandbox — no real prints)
var dev = new LabelInnClient("sk_test_xxxxx");

// Live mode (sends to physical printers)
var prod = new LabelInnClient("sk_live_xxxxx");

// Custom base URL
var custom = new LabelInnClient("sk_live_xxxxx", "https://custom.api.example.com/v1");

Print Jobs

Send ZPL (raw printer code)

var job = await client.Print.CreateAsync(new CreateJobRequest
{
    PrinterId = "prt_abc123",
    PayloadType = "zpl",
    PayloadData = "^XA^FO50,50^ADN,36,20^FDShipping Label^FS^XZ"
});

Send an image

var job = await client.Print.CreateAsync(new CreateJobRequest
{
    PrinterId = "prt_abc123",
    PayloadType = "image",
    ImageUrl = "https://example.com/labels/shipping.png"
});

Print from a template with data

var job = await client.Print.CreateAsync(new CreateJobRequest
{
    PrinterId = "prt_abc123",
    PayloadType = "template",
    DesignId = "tmpl_shipping_v2",
    Data = new
    {
        order_id = "ORD-9876",
        customer = "Ali Yilmaz",
        barcode = "TR123456789"
    }
});

Idempotency (prevent duplicate prints)

var job = await client.Print.CreateAsync(
    new CreateJobRequest { ... },
    idempotencyKey: "order-9876-label"
);
// Calling again with the same key returns the original job

List & manage jobs

// List recent jobs
var list = await client.Print.ListAsync(limit: 10);

// With the next-page cursor
var page = await client.Print.ListPageAsync(limit: 10);
var next = await client.Print.ListPageAsync(limit: 10, pageToken: page.Pagination?.NextPageToken);

// Filter by status
var failed = await client.Print.ListAsync(status: "failed");

// Get job details
var job = await client.Print.GetAsync("job_abc123");

// Cancel a queued job
await client.Print.CancelAsync("job_abc123");

// Reprint with different printer
await client.Print.ReprintAsync("job_abc123", new ReprintRequest
{
    PrinterId = "prt_backup"
});

Fleet Management

// List all printers
var printers = await client.Fleet.ListAsync();

// Filter by status
var online = await client.Fleet.ListAsync(status: "online");

// Get printer details
var printer = await client.Fleet.GetAsync("prt_abc123");

// Quick status check
var status = await client.Fleet.StatusAsync("prt_abc123");
Console.WriteLine($"{status.Status} — online: {status.Online}");

Designs (Templates)

// List all designs
var designs = await client.Designs.ListAsync();

// Get design details
var design = await client.Designs.GetAsync("tmpl_shipping");

// Get template variables
var vars = await client.Designs.ListVariablesAsync("tmpl_shipping");
Console.WriteLine(vars);

// Clone a design
var clone = await client.Designs.CloneAsync("tmpl_shipping");

// Render a preview
var preview = await client.Designs.RenderAsync("tmpl_shipping", new
{
    data = new { customer_name = "John" }
});
Console.WriteLine(preview);

// Create a new design
var newDesign = await client.Designs.CreateAsync(new
{
    name = "Custom Label",
    width_mm = 100,
    height_mm = 50
});

Workflows

Build, test and trigger visual label workflows from code.

// Dry-run with a sample record — nothing prints
var result = await client.Workflows.TestAsync("wf_abc123", new { sku = "A-1042", qty = 2 });

// Mint a signed inbound trigger once and store the secret
var trigger = await client.Workflows.CreateTriggerAsync("wf_abc123", signed: true);

// Then, from your system, run the workflow with a record
var run = await client.Workflows.FireAsync("wf_abc123", trigger.Token,
    new { order_id = "ORD-9876", sku = "A-1042" }, trigger.Secret);
Console.WriteLine($"Accepted: {run.Accepted}, jobs: {string.Join(", ", run.PrintJobIds)}");

Print History

var history = await client.Audit.PrintHistoryAsync(printerId: "prt_abc123", status: "completed", limit: 50);
foreach (var entry in history.Data) Console.WriteLine(entry);

var check = await client.Audit.VerifyPrintAsync("job_abc123", expectCopies: 2);

Webhooks

// List webhooks
var webhooks = await client.Webhooks.ListAsync();

// Create a webhook
var wh = await client.Webhooks.CreateAsync(new CreateWebhookRequest
{
    Url = "https://example.com/webhooks/labelinn",
    Events = new[] { "print.job.completed", "print.job.failed" }
});
Console.WriteLine($"Secret (save this): {wh.SigningSecret}");

// Update webhook
await client.Webhooks.UpdateAsync(wh.Id, new UpdateWebhookRequest
{
    Enabled = true,
    Events = new[] { "print.job.completed" }
});

// Send test event
await client.Webhooks.TestAsync(wh.Id);

// Get delivery history
var deliveries = await client.Webhooks.DeliveriesAsync(wh.Id, limit: 50);

// Delete webhook
await client.Webhooks.DeleteAsync(wh.Id);

Data Connect

Data Connect lets you ingest data from any enterprise system (SAP, Oracle, CSV, JSON) and print labels. Supports XML/IDoc, CSV/TSV, and JSON/NDJSON with auto-detection.

Ingest Data

var result = await client.Connect.IngestAsync(new ConnectIngestRequest
{
    SourceId = "src_abc123",
    Payload = "[{\"sku\": \"A001\"}, {\"sku\": \"A002\"}]",
    Format = "json"
});
Console.WriteLine($"Ingested {result.RecordCount} records");

Test Parse

var parsed = await client.Connect.TestParseAsync(new ConnectIngestRequest
{
    Payload = csvString,
    Format = "csv"
});
foreach (var field in parsed.Schema ?? Array.Empty<SchemaField>())
    Console.WriteLine($"{field.Path} ({field.Type}): {field.Sample}");

Manage Sources

// Create
var source = await client.Connect.CreateSourceAsync(new CreateSourceRequest
{
    Name = "SAP Orders",
    Format = "xml"
});

// List
var sources = await client.Connect.ListSourcesAsync();

// Get / Update / Delete
var detail = await client.Connect.GetSourceAsync("src_abc123");
await client.Connect.UpdateSourceAsync("src_abc123", new UpdateSourceRequest { Name = "SAP v2" });
await client.Connect.DeleteSourceAsync("src_abc123");

Schema, Records & Mappings

var schema = await client.Connect.GetSchemaAsync("src_abc123");
var records = await client.Connect.ListRecordsAsync("src_abc123", limit: 50);
var mappings = await client.Connect.GetMappingsAsync("src_abc123");
await client.Connect.UpdateMappingsAsync("src_abc123", new Dictionary<string, string> { ["sku"] = "product_code" });

Print from Connector

// Rows 1-25 of a source, one label per row
var printResult = await client.Connect.PrintAsync("src_abc123", new ConnectPrintRequest
{
    DesignId = "dsg_shipping",
    PrinterId = "prt_warehouse1",
    RowStart = 1,
    RowCount = 25,
});
Console.WriteLine($"Job {printResult.JobId}: {printResult.TotalLabels} labels");

// Or let the design's bound data source be used
await client.Connect.PrintDesignAsync(new ConnectPrintRequest { DesignId = "dsg_shipping", PrinterId = "prt_warehouse1" });

Custom API connections: client.Connect.Custom (ListAsync, CreateAsync, GetAsync, UpdateAsync, DeleteAsync, TestAsync, ExecuteAsync).

Printer Commands, Passports, GHS and UFI

var answer = await client.Fleet.CommandAsync("prt_abc123", new PrinterCommandRequest { Command = "STATUS" });

await client.Passport.UpdateAsync(new
{
    gtin = "09506000134352", serial = "SN1",
    fields = new[] { new { key = "state_of_health", value = 92 } },
});
var passport = await client.Passport.ResolveAsync("01/09506000134352/21/SN1");

var ghs = await client.Labels.PreviewAsync(new { data = new { h_codes = new[] { "H225" } } });
var ufi = await client.Ufi.GenerateAsync("DE123456789", 4521, "DE");

Also client.Audit.Compliance.SignAsync(...) and client.Relay.StatusAsync().

Local Edge API (LAN, pinned TLS)

Every PC running the LabelInn desktop app can serve a local API on port 6631. LabelInnEdge.FromDescriptor() reads ~/.labelinn/edge.json (written by the app). When the PC serves HTTPS with its own self-signed certificate, the file carries tlsSha256 and the client pins it in the TLS handshake (ServerCertificateCustomValidationCallback), so a server with another certificate never receives the request (LabelInnEdgePinException). PCs without TLS (or older app versions) keep working over plain http.

using var edge = LabelInnEdge.FromDescriptor();                       // this PC
using var remote = new LabelInnEdge("192.168.1.40", token: "EDGE_TOKEN", tlsSha256: "3f1c...e9");

var accepted = await edge.PrintAsync(new EdgePrintJob { PrinterId = "usb_zebra_01", PayloadType = "zpl", PayloadData = "^XA^XZ" });
var result = await edge.GetJobAsync(accepted.GetProperty("jobId").GetString()!);   // 404 until processed

Other methods: HealthAsync, ListPrintersAsync, ListPeersAsync, StartDiscoveryAsync, GetDiscoveryAsync, ListDesignsAsync, GetDesignAsync, ScheduleStatusAsync, ScheduleRunNowAsync, AuditRecentAsync.

MQTT note: the app's built-in broker only accepts labelinn/cmd/* commands from a client that logs in with the configured MQTT username and password (or from the same PC).

Error Handling

try
{
    var job = await client.Print.GetAsync("job_abc123");
}
catch (LabelInnRateLimitException ex)
{
    Console.WriteLine($"Rate limited. Retry after {ex.RetryAfterSeconds}s");
}
catch (LabelInnException ex)
{
    Console.WriteLine($"Error [{ex.Status}] {ex.Code}: {ex.Message}");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Network error: {ex.Message}");
}

Configuration

Control JSON serialization and timeouts:

var client = new LabelInnClient(
    apiKey: "sk_live_xxxxx",
    baseUrl: "https://custom.api.example.com/v1"  // override URL
);

Requirements

• .NET 6.0 or later
• No external NuGet dependencies

Contributing

See GitHub for issues & contributions.

License

MIT — See LICENSE file