API Referansı

Labelixa REST API referansı: render ve barkod uç noktaları, istek/yanıt header'ları, hata kodları ve API anahtarı ile kimlik doğrulama.

Kimlik doğrulama

Ücretsiz katman anahtarsız çalışır (IP bazlı sınır); hiçbir planda çıktıya filigran eklenmez. Anahtarı X-API-Key header'ında gönderin; limitleri yükseltir. ?key= query parametresi hâlâ çalışıyor ama kullanımdan kaldırılıyor (kapanma 2027-01-31): query string tarayıcı geçmişine, Referer başlığına, vekil loglarına ve paylaşılan bağlantılara sızar. Bu yolu kullanan isteklere yanıtta Deprecation ve Sunset başlıkları eklenir.

Anonim (anahtarsız) istekler IP adresi başına sayılır (IPv6: /64 öneki başına) — o adresin arkasındaki herkes tek kovayı paylaşır: takvim ayı (UTC) başına 5.000 etiket ve 10.000 istek, günlük 5.000 etiket tavanı, saniyede 3 istek, istek başına en çok 50 etiket. Ücretsiz hesap (labelixa.com/panel) IP'den bağımsız kendi aylık kotasıyla bir API anahtarı alır ve etiket kaydedebilir; ücretli planlar sınırları yükseltir.

API kararlılığı

/v1 içinde yalnız EKLEME yapılır: yeni yanıt alanı, yeni opsiyonel parametre ve yeni uç her an çıkabilir — tanımadığınız alanı yok sayın. Kırıcı bir değişiklik (alan kaldırma/yeniden adlandırma, tip ya da anlam değiştirme, hata kodu semantiğini değiştirme) bunun YANINDA yaşayan yeni bir ana sürüm olarak çıkar. Bir uç ya da kimlik doğrulama yolu kaldırılırken en az altı ay önceden bildirim, Deprecation ve Sunset başlıkları ve kaldırma sonrası 410 Gone + halefin adresi verilir — sessiz bir 404 asla. Bu bir alışkanlık değil sözleşme taahhüdüdür: Kullanım Şartları §24.4.1.

Taahhüt bu sayfada BELGELENEN uçları kapsar. /v1 altında belgelenmemiş yollar da yanıt verebilir; onlar iç akışlar için vardır, kararlılık sözü taşımaz ve habersiz değişebilir. Entegrasyonunuzu yalnız belgelenen uçlara kurun.

Hızlı başlangıç

1. Bir ZPL etiketini anonim uca gönderin — anahtar gerekmez, ücretsiz kota yeter:
   bash

   curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/0" \
     -H "Content-Type: text/plain" \
     --data-binary '^XA^FO50,50^A0N,40,40^FDHello^FS^XZ' \
     -o label.png

2. Gelen PNG etiketin kendisidir. Aynı gövdeyi Accept: application/pdf ile PDF olarak da alabilirsiniz.
3. Hesap açıp X-API-Key başlığı ekleyince kota ve hız sınırı planınıza göre yükselir; ayrıntı aşağıdaki başlıklarda.

Uç noktalar

İstek header'ları

Yanıt header'ları

Hata kodları

Hata gövdesinin biçimi uca göre değişir; ayrıştırmadan önce Content-Type kontrol edin.

Barkod API'sinde geçersiz veri, HTTP 200 ile birlikte hatayı bir görsel olarak döndürür (no-code araç uyumu) ve ayrıntı X-Warnings header'ında verilir.

Hatalar ve çözümleri

Her hata bir HTTP durum kodu ve bir gövdedir. Önce durumu, sonra gövdeyi okuyun: render uçları TEK SATIR DÜZ METİN, diğer uçlar mesajı hata alanında (İngilizce) taşıyan JSON döndürür. Bazı JSON gövdeler ayrıca kararlı bir makine-okur ad taşır — kod (snake_case) ya da hata_tipi (PascalCase) — ve bu adlar kablo değeridir: dallanmayı onlara göre yapın, cümleye göre değil. Anahtar adlarının neden Türkçe olduğunu Yanıt alan adları bölümü anlatır. Aşağıdaki tablo entegratörlerin gerçekten karşılaştığı hataları, ne zaman olduklarını ve nasıl çözüldüklerini listeler.

401 / 403 — anahtar, köken, plan, kapsam, Business Central

{"hata": "Invalid API key", "kod": "gecersiz_anahtar"}

{"hata": "X-API-Key required"}

{"hata": "Access denied", "kod": "origin_kapisi"}

{"hata": "This feature (webhook) is not available on the free plan. See the /v1/plans endpoints to upgrade."}

{"hata": "This key does not have the 'etiket_yaz' scope", "kod": "kapsam_yok", "gereken_kapsam": "etiket_yaz"}

{"hata": "The billing portal can only be opened with the account's primary key or a panel session", "kod": "birincil_gerekli"}

{"hata": "Role 'viewer' is not allowed to perform 'etiket_yaz'", "kod": "rol_yetkisiz", "gereken_eylem": "etiket_yaz"}

{"hata": "Saved labels require an account; a free account is enough (POST /v1/accounts).", "kod": "hesap_gerekli"}

{"hata": "Invalid Entra token: signature verification failed", "hata_tipi": "EntraJetonuGecersiz"}

{"hata": "This Entra tenant is not linked to a Labelixa account; run Connect Account with an API key first", "hata_tipi": "EntraEslemesiYok"}

{"hata": "This Entra tenant is linked to more than one Labelixa account; connect with an API key", "hata_tipi": "EntraBelirsiz"}

{"hata": "This tenant/environment/company is linked to another account", "hata_tipi": "KiraciBaskasinin"}

400 / 404 / 413 / 422 — parametre, boyut, doğrulama

dpmm must be 6, 8, 12 or 24

Label size must be at most 15 inches

{"hata": "Not found"}

Request body exceeds the 1 MB limit

At most 20000 commands per label (23417 found). Split the ZPL stream into several labels or simplify it.

At most 50 labels per request (120 sent). Upgrade your plan for a higher limit.

{"detail": [{"type": "json_invalid", "loc": ["body", 1], "msg": "JSON decode error", "input": {}}]}

{"hata": "Quick batch accepts at most 20 rows; for more, use a Pro bulk job (/v1/bulk/jobs)", "kod": "satir_tavani", "tavan": 20, "satir_sayisi": 21}

{"hata": "An account with this email already exists", "kod": "eposta_kullanimda"}

402 / 429 — hız sınırı ile günlük/aylık kota

Per-second request limit exceeded (3/s). Starter: 5/s, 9 USD/month -> https://labelixa.com/pricing?amac=kota

Daily quota insufficient: 3 operations left, this request needs 5 (daily 5000). Upgrade your plan to continue. Next plan: starter, 9 USD/month -> https://labelixa.com/pricing?amac=kota

Monthly label quota insufficient: 40 labels left, this request needs 50 (monthly 20000). The quota renews on 2026-11-17T00:00:00Z; upgrade your plan to continue.

{"hata": "Too many account creation attempts; try again later", "kod": "hiz_siniri"}

{"hata": "Saved label limit reached (5/5)"}

{"hata": "Free DirectPrint trial used up (25 labels). Upgrade to Starter or higher to continue.", "hata_tipi": "DenemeDoldu"}

{"hata": "This tenant's monthly BC print cap (500) is reached", "hata_tipi": "TavanDoldu"}

İki farklı sınır aynı 429 durumunu paylaşır; onları başlıklar ayırır. Saniyelik hız sınırı Retry-After: 1 ile ve X-Quota-Reason başlığı OLMADAN döner: bir saniye bekleyip isteği yeniden gönderin. Günlük ya da aylık kota Retry-After: 3600, X-Quota-Action ve X-Quota-Reason (gunluk, aylik_etiket ya da aylik_istek) ile döner; X-Quota-Reset yenilenmenin tam UTC anını verir ve ondan önce denemek boşunadır — planı yükseltin (sonraki plan ve adresi X-Quota-Next-Plan ile X-Quota-Upgrade-Url başlıklarında makine-okur) ya da sıfırlanmayı bekleyin. Anonim 200 yanıtları, 5.000 ücretsiz etiketten 150 tanesi kullanılınca X-Quota-Hint ekler: ücretsiz anahtar size kendi kotanızı verir.

409 / 412 / 428 — eşzamanlılık ve yeniden deneme

{"hata": "If-Match is required (prevents lost updates)", "guncel_surum": 7, "etag": "\"7\""}

{"hata": "The label changed in the meantime (version mismatch)", "guncel_surum": 8, "etag": "\"8\""}

{"hata": "Same Idempotency-Key but a different request"}

{"hata": "A previous request with the same Idempotency-Key is still being processed"}

5xx — render bütçesi ve servis

Render time limit exceeded

Service temporarily unavailable

{"hata": "Unexpected server error"}

Baskı işi hata tipleri

Düşen bir baskı işi HTTP isteğini düşürmez — POST /v1/print 202 döndü, sonuç iş durumundadır. Başarısız işin hata_tipi alanı şu sınıflardan biridir; asama işin düşmeden önce nereye kadar geldiğini söyler.

Yanıt alan adları

JSON yanıtlarındaki anahtarlar sabit kablo adlarıdır. Çoğu Türkçe kelimedir (ör. ozet, mesaj, durum) ve olduğu gibi kalır: bir anahtarı yeniden adlandırmak geriye uyumsuz bir değişikliktir ve yukarıdaki API kararlılık taahhüdü bunu /v1 içinde dışarıda bırakır. Resmî entegrasyonlar — MCP sunucusu ve n8n düğümü — anahtarları çevirip İngilizce adlarıyla gösterir. Aşağıdaki tablo onların kullandığı eşlemeden üretilir; ham yanıtla entegrasyon çıktısını yan yana okuyabilirsiniz. Listede olmayan anahtar entegrasyonlarda da JSON adıyla görünür. Hata gövdeleri insan-okur mesajı İngilizce olarak hata alanında taşır. Her hatanın ne zaman olduğu ve nasıl çözüldüğü: Hatalar ve çözümleri.

Sabit değerler

Bazı alanlar sabit bir kümeden tek kelime taşır. JSON değeri değişmez; entegrasyonlar İngilizce kelimeyi gösterir. Yollar yukarıdaki tablodaki İngilizce alan adlarıyla yazılır; [] dizi öğesini, * herhangi bir anahtarı gösterir.

Toplu iş durumları

Toplu işin durum alanı şunlardan biridir:

Uyumluluk kademeleri

Uyumluluk denetimi risk.seviye alanında bir risk kademesi döndürür, asla garanti vermez:

onizleme_kapsami etiketteki komutları BİZİM önizlememizin onlarla ne yaptığına göre gruplar. Önizlemeyi anlatır, yazıcıyı değil:

Veri çıkarımı (JSON)

Render uç noktasına Accept: application/json gönderirseniz, etiketteki görünür metin ve barkod alanları koordinatlarıyla birlikte JSON olarak döner (barkodlar tur: barkod ile ayrılır):

curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/0" \
     --data "^XA^FO50,60^FDMerhaba^FS^XZ" -H "Accept: application/json"

ZPL dönüştürme (application/zpl)

Accept: application/zpl ile ZPL'iniz yeniden biçimlendirilir (her komut ayrı satır; X-Formatter: Off ile kapatılır) ve X-Target-Dpmm verilirse koordinat/boyut parametreleri kaynak çözünürlükten hedefe ölçeklenir. Veri alanları (^FD) değişmez.

curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/0" \
     --data-binary @etiket.zpl -H "Accept: application/zpl" \
     -H "X-Target-Dpmm: 12" > etiket-12dpmm.zpl

EPL2 çıktısı (application/epl)

Accept: application/epl ile etiketiniz EPL2'ye çevrilir — Zebra'nın eski nesil yazıcılarında kullanılan dil. Metin, barkod, kutu ve çizgi alanları EPL2 komutlarına dönüşür; ölçüler yazıcının nokta yoğunluğuna göre hesaplanır (8dpmm = 203 dpi, 12dpmm = 300 dpi — EPL2'nin font ölçüleri bu ikisinde FARKLIDIR ve doğru tablo otomatik seçilir).

EPL2'nin komut kümesi ZPL'den dardır, bu yüzden her etiket birebir çevrilemez. Çevrilemeyen alan sessizce düşmez: X-Warnings başlığında adıyla bildirilir. Bugün çevrilmeyenler: QR kodu (^BQ), DataMatrix (^BX), gömülü grafik (^GF) ve metin bloğu (^FB). Ayrıca EPL2'de metin ölçüsü süreklidir DEĞİL — sabit font × tam sayı çarpan — ve dar çubuk genişliği sembolojiye göre sınırlıdır (Code 128'de 1-10, EAN/UPC'de 2-4); istediğiniz değer aralık dışındaysa kırpılır ve bu da uyarıya yazılır.

Desteklenen barkodlar: ^BC Code 128, ^B3 Code 39, ^BE EAN-13, ^B8 EAN-8, ^BU UPC-A, ^B2 Interleaved 2/5, ^BK Codabar.

curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/" \
     --data-binary @etiket.zpl -H "Accept: application/epl" \
     -D basliklar.txt > etiket.epl

Giden webhook

Toplu iş bittiğinde durumu yoklamak yerine size haber verebiliriz. POST /v1/webhooks ile bir uç kaydedersiniz; olaylar toplu.tamamlandi ve toplu.basarisiz.

curl -X POST "https://api.labelixa.com/v1/webhooks" \
     -H "X-API-Key: $LABELIXA_KEY" -H "Content-Type: application/json" \
     -d '{"url": "https://erp.sirketiniz.com/labelixa"}'

İmza sırrı yalnız bu yanıtta döner ve listelemede bir daha gösterilmez; kaybederseniz ucu silip yeniden oluşturursunuz. Sır hesap API anahtarınızdan ayrıdır: anahtarınızı döndürmek webhook doğrulamasını bozmaz.

Her istek Labelixa-Signature: t=<unix>,v1=<hmac> taşır. HMAC-SHA256, "<t>.<gövde>" üzerinden hesaplanır — zaman damgası imzanın içindedir, yani tazeliğine bakarak tekrar (replay) saldırısını eleyebilirsiniz. Biçim Stripe'ınkiyle aynıdır; Stripe webhook'u doğrulayan kodunuzu uyarlayabilirsiniz.

import hmac, hashlib, time

def dogrula(sir, govde, baslik, tolerans=300):
    p = dict(x.split("=", 1) for x in baslik.split(","))
    t = int(p["t"])
    if abs(time.time() - t) > tolerans:
        return False
    beklenen = hmac.new(sir.encode(), f"{t}.".encode() + govde,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(p["v1"], beklenen)

Her istek ayrıca Labelixa-Delivery-Id taşır ve bu kimlik yeniden denemelerde değişmez. Aynı kimliği ikinci kez görürseniz işlemi tekrarlamayın — teslimat en az bir kez (at-least-once) garantisiyle çalışır.

Sır rotasyonu

POST /v1/webhooks/{id}/rotate yeni bir sır üretir. Eski sır bir geçiş penceresi boyunca (varsayılan 24 saat) geçerli kalır ve o süre boyunca her istek iki imza taşır (v1=… ,v1=…). Doğrulamanız hangisini biliyorsa onunla eşleşir; yani sırrı kesintisiz döndürebilirsiniz. Kalan süreyi GET /v1/webhooks yanıtındaki rotasyon_bitis alanından görürsünüz.

Doğrulama kodunuz birden çok v1 değerini desteklemeli — başlığı sözlüğe çevirip tek değer okursanız yalnızca sonuncusunu görür ve rotasyonun ilk yarısında imzayı reddedersiniz.

2xx dışındaki her yanıt başarısızlıktır ve yeniden denenir; yönlendirme (3xx) takip edilmez. Üst üste başarısız olan uç kendiliğinden pasifleşir — listelemede aktif: false ve son durum kodu görünür. Gövdede satır içeriği yoktur: yalnız iş kimliği ve sayaçlar gönderilir, sonucu iş kimliğiyle çekersiniz.

Kaydedilmiş etiketler

Render uçları durumsuzdur ve hiçbir şey kaydetmez; kaydetme yalnız bu uçlarla, açık istekle olur. Ücretli plan gerektirir (Başlangıç 50, Profesyonel 500 kayıtlı etiket; Enterprise sınırsız — bu sınır aylık işlem kotasından bağımsızdır: biri kaç etiket bastığınız, öbürü kaç tasarım tuttuğunuz).

Eşzamanlılık (If-Match)

Her okuma yanıtı bir ETag taşır ve her yazma isteği If-Match başlığını zorunlu ister: başlıksız yazma 428, eski sürümle yazma 412 alır (gövdede güncel sürüm döner). Bu, iki sekmede açık bir etikette ikincinin birincinin yazdığını sessizce ezmesini önler. Bilerek üzerine yazmak için If-Match: * gönderin.

curl -X POST "https://api.labelixa.com/v1/labels" \
     -H "X-API-Key: $LABELIXA_KEY" -H "Content-Type: application/json" \
     -d '{"ad": "Kargo", "zpl": "^XA...^XZ"}'
# yanıt: 201 + ETag: "1"

curl -X PATCH "https://api.labelixa.com/v1/labels/ETIKET_ID" \
     -H "X-API-Key: $LABELIXA_KEY" -H 'If-Match: "1"' \
     -H "Content-Type: application/json" -d '{"ad": "Kargo v2"}'

Sürümler ve çöp kutusu

Her güncelleme eski hâli tarihçeye yazar (etiket başına son 50 sürüm saklanır). Eski sürüme dönmek yeni bir sürüm olarak yazılır — tarihçe silinmez, geri dönmek de geri alınabilir. Silinen etiket 30 gün çöp kutusunda bekler ve /restore ile geri gelir; aktif etiketleriniz süresiz saklanır.

Idempotency-Key başlığı POST /v1/labels için de geçerlidir: ağ zaman aşımından sonra aynı anahtarla tekrar denerseniz ikinci bir etiket oluşmaz, saklanan yanıt oynatılır.

Baskı

Render uçları size bir görüntü döndürür; bu uçlar işi kayıtlı bir yazıcıya gönderir. Ücretli plan gerektirir (Başlangıç ve üzeri). Ücretlendirme çift saymaz: daha önce render edilmiş bir işin kimliğini kaynak_is_id ile verirseniz baskı bedava; ham ZPL doğrudan gelirse etiket burada üretilmiş sayılır ve burada ücretlenir.

İş durumları — ve printed neden yok

Sözlükte bilerek bir “basıldı” durumu yoktur. Ham 9100 üzerinden bir etiketin gerçekten basıldığı kanıtlanamaz: soketin baytları kabul etmesi yalnız yazıcının tamponuna girdiklerini gösterir; kâğıdın bitmesi, kafanın açık kalması veya sıkışma baytlar kabul edildikten sonra olur ve soket bunu size söylemez. En ileri durum dispatched = “teslim ettik”. Yanıt ayrıca her zaman basim_onaylandi: false taşır — alanı yok saymak “demek ki basıldı” anlamına gelmesin diye.

Yani: baskıyı tetikleyen bir iş akışı kurabilirsiniz, ama basım onayı üzerine iş kuralı kurmayın. Onayı gerçekten gerektiren senaryolarda (ilaç, İTS) doğrulama etiketin kendisinden okunarak yapılmalıdır.

failed “hiçbir şey basılmadı” demek değildir

Bir iş beş ayrı noktada başarısız olabilir ve bunların dördünde yazıcıya tek bayt gitmez (cihaz eşlenmemiş, adaptör yok, kimlik doğrulanamadı). Beşincisinde — yazıcıyla bağlantı koptuğunda — baytlar gitmiş, hatta çok kopyalı bir işin bir kısmı basılmış olabilir. Durum yanıtı bu farkı ayrı alanlarda taşır:

Yazıcıya bayt gitmiş bir iş otomatik olarak yeniden denenmez — denenseydi çıkmış etiket ikinci kez basılırdı. Böyle bir iş beklemeye alınır ve devam kararını siz verirsiniz. Yazıcıya hiç ulaşmamış hatalar eskisi gibi kendiliğinden yeniden denenir.

Bu işleri alıp yazıcıya ileten DirectPrint agent'ı buradan indirilir: /tr/download

Agent'ı kurmak (kurulum sihirbazı)

Yazıcıların bağlı olduğu bilgisayarda labelixa-agent setup çalıştırın (indirme sayfasındaki tek satırlık kurulum agent'ı kurar ve sizin için başlatır). Agent tarayıcıda Labelixa sayfasını açar; sayfada agent penceresindekiyle aynı kısa kodun yazdığını kontrol edip Bağla'ya basın. Tarayıcı yoksa panelin Yazıcılar sayfasında bir eşleştirme kodu oluşturup labelixa-agent setup KOD çalıştırın. Ücretsiz planda 1 bilgisayar, 1 yazıcı ve toplam 25 etiketlik bir deneme vardır (test etiketi sayılmaz); devamı ücretli plan ister. Agent'ı indirmek ücretsizdir.

Sihirbaz bilgisayarın yazdırma kuyruklarına bakar: tek bir etiket yazıcısı sorusuz seçilir, birden çoğu liste olarak sunulur, ofis yazıcısı ancak siz onaylarsanız kullanılır. Seçilen her yazıcı hesabınıza eklenir ve bu bilgisayarda eşlenir; sonunda bir test etiketi basılabilir. Kurulum sırasında yazıcıya hiçbir şey gönderilmez ve ağ taranmaz.

• labelixa-agent discover -mdns kendini ağda duyuran yazıcıları (Bonjour/mDNS) onlara bir şey göndermeden listeler.
• labelixa-agent import DOSYA çok sayıda ağ yazıcısını bir CSV dosyasından tek seferde ekler; her yazıcı için bir ad,adres[,grup] satırı (-dry-run önce dosyayı denetler). Her satır raporlanır; hatalı bir satır dosyayı durdurmaz.
• Bağlı bir bilgisayarda setup'ı yeniden çalıştırmak bağlantıyı ve kurulu yazıcıları korur.

Agent buluta iş sorar ve bulut iş gelene kadar isteği açık tutar (uzun yoklama); etiket gönderildiği anda teslim edilir. Agent hiçbir port açmaz: her bağlantı bilgisayardan Labelixa'ya doğrudur.

Windows: BT ekipleri için sessiz kurulum

Intune, Grup İlkesi ya da SCCM ile dağıtım için Windows agent'ı MSI paketi olarak da yayımlanır. Tek satır agent'ı LabelixaAgent Windows hizmeti olarak kurar, panelin Yazıcılar sayfasından alınan tek kullanımlık kodla eşleştirir ve yazıcı listesini içe aktarır: msiexec /i labelixa-agent_0.6.1_windows_amd64.msi /qn PAIRCODE=KOD PRINTERSFILE=C:\yol\yazicilar.csv. PRINTERSFILE isteğe bağlıdır (her yazıcı için bir ad,adres[,grup] satırı); eşleştirme ya da içe aktarma başarısızsa kurulum geri alınır, kod kurulum günlüğüne yazılmaz. Paket ve sağlama toplamı yayın sayfasındadır.

Tekrarı önlemek: Idempotency-Key

Ağ zaman aşımı yaşadığınızda isteği yeniden göndermek doğru bir reflekstir — ama etiket çoktan çıkmış olabilir. Idempotency-Key başlığı gönderirseniz aynı anahtarla gelen ikinci istek yeni bir iş yaratmaz, ilk yanıtı aynen geri verir (Idempotency-Replayed: true). Aynı anahtarla FARKLI bir gövde göndermek 422 alır: anahtarı geri dönüştürmek sessizce yanlış etiketi bastırırdı.

Kuyruk dolduğunda dönen 429 anahtarı tüketmez — aynı anahtarla yeniden denemeniz beklenir.

Hazır şablondan baskı

yuk yerine sablon_id ve degiskenler gönderebilirsiniz; yük şablondan üretilir. İkisini birlikte göndermek reddedilir. Eksik ya da geçersiz bir değişken 400 döner — eksik değişkenli bir etiket basılsaydı kâğıt boşa giderdi ve bunu ancak yazıcının başındaki kişi fark ederdi.

Kayıtlı etiketten baskı: etiket_id

yuk yerine hesabınızda kayıtlı bir etiketin (/v1/labels) etiket_id'sini, değişkenleri için degiskenler ile birlikte gönderebilirsiniz; yük etiketten üretilir. Birden çok etiketi TEK iş olarak basmak için satirlar gönderin: etiket başına bir nesne, 1-1000 satır; satırın değerleri degiskenler'i ezer ve etiket_sayisi satır sayısı olur. Boş satirlar listesi reddedilir; tek etiket için alanı hiç göndermeyin. etiket_id; yuk, zpl ya da sablon_id ile birlikte gönderilemez (422). Eksik ya da geçersiz bir değişken 422 döner ve satırı söyler — iş kuyruğa alınmaz, hiçbir satır atlanmaz. Başka bir hesabın etiketi, olmayan etiketle aynı 404'ü alır; arşivlenmiş etiket basılmaz. Idempotency-Key, kopya, device_id / printer_group ve ücretlendirme ham yükle tamamen aynı çalışır; yanıt etiket_id taşır. Onay akışı açıkken yalnız yayınlanmış etiketler basılır (aksi hâlde 422); etiketi panelde Kayıtlı işler altında onaya gönderin ve onaylayın ya da POST /v1/labels/{id}/publish ve /approve uçlarını kullanın.

Yazıcı grupları: printer_group

Bir cihazı kaydederken grup verirseniz (DEPO, URETIM gibi) baskı isteğinde device_id yerine printer_group gönderebilirsiniz. Amaç, cihaz kimliklerini iş tarafından uzak tutmaktır: bir yazıcı değiştiğinde ERP tarafındaki koda dokunmak gerekmez, cihaz kaydındaki grup taşınır.

Çözüm kuralı belirlenimcidir ve bu bilinçli bir tercihtir — “boşta olanı seç” türü bir dağıtım için gereken veriye sahip değiliz (ham 9100 soketi yazıcının doluluğunu bildirmez). Grupta tek cihaz varsa o seçilir; birden çok cihaz varsa grubun varsayılan işaretlisi seçilir. Varsayılan yoksa ya da birden çoksa iş basılmaz ve hata hangi cihazların çakıştığını sayar. Rastgele bir yazıcı seçmek, geri alınamayan bir çıktı üretirdi.

device_id ile printer_group birlikte gönderilemez. Grup adları büyük harfe normalleştirilir (depo = DEPO) ve yalnız harf, rakam, -, _ içerebilir. Grup kullanmayan entegrasyonlar için hiçbir şey değişmez: grup alanı boş doğar ve device_id eskisi gibi çalışır. Yanıt her iki yolda da işin düştüğü device_id'yi geri verir.

Webhook ile bildirim

Durum sormak için sürekli yoklama yapmanız gerekmez: baski.teslim ve baski.basarisiz olaylarına abone olun. baski.basildi diye bir olay yoktur — yukarıdaki gerekçenin aynısı. Gövde ham etiket içeriği taşımaz; iş kimliği, aşama ve sayaçlar gider. Başarısızlık olayı yalnızca iş kalıcı olarak başarısızlığa düştüğünde yayımlanır — her yeniden denemede bildirim göndermek gerçek arızayı gürültüde kaybederdi. uncertain olan iş baski.belirsiz yayımlar — ayrı bir olaydır ki baski.basarisiz'a yeniden baskı bağlamış bir otomasyon onu ikinci kez basmasın; mevcut abonelikler onu ancak eklediğinizde alır. Her baski.* gövdesi veri.sira (iş başına 1, 2, …) ve veri.status (o olaydaki durum) taşır. Teslimat yeniden denendiği için eski bir olay yenisinden sonra gelebilir: sira'yı karşılaştırın ve o iş için son işlediğinizden küçük sira taşıyan olayı yok sayın.

USB yazıcı: işletim sisteminin yazdırma kuyruğu

USB ile bağlı masaüstü yazıcı 9100 portunu açmaz; işletim sisteminde bir yazdırma kuyruğu olarak görünür (Windows yazdırma biriktiricisi, macOS ve Linux'ta CUPS). Agent 0.2.0 ve sonrası baytları bu kuyruğa RAW olarak verir: sürücü hiçbir şey çizmez, etiket dili yazıcıya gönderdiğiniz gibi ulaşır.

1. Cihazı adaptor: "os_driver" ile kaydedin (POST /v1/devices).
2. Agent makinesinde kuyruk adını bulun: labelixa-agent discover -queues.
3. Cihazı kuyruğa eşleyin: labelixa-agent map-printer -device CIHAZ_ID -queue "KUYRUK_ADI".
4. İsterseniz agent'ı her oturum açılışında arka planda çalıştırın: labelixa-agent install (macOS'ta LaunchAgent, Linux'ta systemd kullanıcı birimi; Windows'ta yönetici PowerShell'inde çalıştırılacak servis komutlarını basar).

Bu yolda en ileri aşama submitted_to_os'tur: biriktirici işi kabul etti. Bu, submitted_to_printer'ın bir adım gerisidir — kapalı ya da kâğıdı bitmiş yazıcı burada değil, işletim sisteminin kuyruğunda görünür ve kuyruk yazıcı durumu bildirmez (yazici_durumu: null). Yazıcı kapalıyken gönderilen iş o kuyrukta bekler, yazıcı açılınca basılır. Kuyruğa kısmen verilmiş çok kopyalı iş otomatik yeniden denenmez.

Bulut kaydı ile agent eşlemesi uyuşmalıdır: ağ adresine eşlenmiş bir os_driver cihazı ya da kuyruğa eşlenmiş bir raw_tcp cihazı basılmaz ve AdaptorYok hatasıyla düşer — yanlış yazıcıya basmaktansa durmak.

USB Zebra yazıcıya buluttan ZPL baskısı

PrintOps — metrikler, uyarılar, baskı denetimi

Baskı uçlarının işletim yüzü: ne basıldı, ne takıldı, kim bastı. Yalnız okur; mevcut baskı kayıtlarını hesabın sahibine özetler. Aynı veriler panelde PrintOps sekmesinde (yazıcılarla aynı plan kapısı).

Business Central

Labelixa'nın Business Central uzantısı (Labelixa Core + DirectPrint) bu uçları kullanır; kendi entegrasyonunuz da kullanabilir. Kimlik API anahtarıdır; anonim istek eşleme kuramaz (403). Plan kapısı baskı uçlarıyla aynıdır.

AI asistanları için MCP sunucusu

Claude, ChatGPT ve MCP destekleyen diğer AI istemcileri Labelixa'yı doğrudan araç olarak kullanabilir: uzak MCP sunucusu https://api.labelixa.com/mcp adresindedir (streamable HTTP, JSON-RPC; kurulum gerekmez, istemcinize tek URL yapıştırırsınız). Anahtar zorunlu değildir — anonim kullanım ücretsiz katman limitlerine tabidir; Authorization: Bearer lbx_... başlığıyla bağlanırsanız kendi hesap kotanız kullanılır.

MCP çağrıları REST ile aynı kota ve hız sınırlarından düşer — MCP ayrı bir katman değil, aynı API'nin araç yüzüdür. Yukarıdaki tablo öne çıkanlardır; tam ve güncel araç listesi canlı sunucudan (tools/list) ve /mcp sayfasından gelir.

Kodlama asistanları için kural dosyaları

Tek bir kural dosyası Claude Code, Cursor, GitHub Copilot ya da Windsurf'e etiket kodunu metinden tahmin etmek yerine Labelixa ile doğrulatmayı ve render ettirmeyi öğretir. Asistanınıza uygun dosyayı Labelixa/agent-skills deposundan projenize kopyalayın: .claude/skills/labelixa/SKILL.md, .cursor/rules/labelixa.mdc, .github/instructions/labelixa.instructions.md, .windsurf/rules/labelixa.md. Kurallar MCP sunucusunu ya da CLI'ı çağırır; varsa API anahtarı yalnız ortamdan gelir.

Basılmış etiketi geri okuma

POST /v1/verify yüklediğiniz fotoğraf veya taramadaki barkodları okur — "bastım, ama el terminali okuyacak mı?" sorusunun cevabı. Gövde multipart/form-data olarak file alanında gönderilir; PNG, JPEG, BMP ve GIF kabul edilir, sınır 5 MB ve 6000×6000 pikseldir. Yanıtta olculdu (çözücü çalıştı mı), okunan listesi (her biri format + veri) ve bir not alanı bulunur.

Bunu POST /v1/barcode-check ile karıştırmayın: orada girdi ZPL'dir, etiketi biz çizip kendi çizdiğimizi okuruz. Burada girdi gerçek dünyadan gelen görseldir.

Sonucun sınırı yanıtta yazılıdır ve ciddiye alınmalıdır: "okundu" her el terminalinin okuyacağını GARANTİ ETMEZ, "okunamadı" da etiketin bozuk olduğunu KANITLAMAZ — fotoğrafın açısı, odağı veya aydınlatması yetersiz olabilir. Bu uç bir ISO/IEC 15416 barkod kalite derecelendirmesi (A–F) DEĞİLDİR; onun için doğrulayıcı bir cihaz gerekir.

curl -X POST "https://api.labelixa.com/v1/verify" \
     -F "file=@etiket-fotografi.jpg"

Aynı işi tarayıcıdan yapmak için: Barkod Doğrulayıcı.

Önizleyiciyi kendi sayfanıza gömme

/embed/viewer site iskeleti olmayan minimal bir önizleme bileşenidir; kendi uygulamanıza <iframe> ile gömersiniz. ZPL sorgu dizesinde değil URL parçasında (#) taşınır — parça sunucuya hiç gönderilmez, yani etiket içeriğiniz bizim ya da aradaki vekillerin loglarına düşmez. Biçim önizleyicinin "bağlantıyı kopyala" çıktısıyla AYNIDIR (base64 JSON), o bağlantıyı olduğu gibi yapıştırabilirsiniz.

<iframe src="https://labelixa.com/embed/viewer#eyJ6IjoiXlhBLi4uIiwiZCI6IjgiLCJ3IjoiNCIsImgiOiI2In0"
        width="420" height="620" style="border:0"></iframe>

Yükseklik sizin verdiğiniz ölçüdür; bileşen görseli çerçeveye sığdırır. Sayfa noindex'tir ve sitemap'te yoktur — bir içerik sayfası değil, bileşendir.

ZPL dışındaki yazıcı dilleri

Aşağıdaki uçlar ZPL karşılıklarını aynalar: render etiketin PNG'sini, diagnostics satır numaralı tanılamayı döndürür. Kapsam her dilde bilinçli olarak bir MVP alt kümesidir ve her yanıt kendi sınırını yazar — çizemediğimiz komut bildirilir, sessizce atlanmaz.

POST /v1/language-detect başka bir soruyu yanıtlar: sizin yazmadığınız bir kod hangi dilde? Cevap sezgisel ve deterministiktir (LLM yok); güven uydurma bir yüzde değil High/Medium/Low olarak bildirilir.

POST /v1/compatibility ZPL ve bir yazıcı modeli alır, uyumluluk risk analizi döndürür: dil postürü, boyut kuralı bulguları ve önizleme kapsamı. Emülatör DEĞİLDİR ve asla uyumluluk garantisi vermez — kırk modelin yalnız birini fiziksel olarak test ettik ve belgelenmiş bir emülasyon kipi yerli destek değildir.

Yazıcı dili çevirisi (SBPL / DPL / IPL → ZPL)

Üç uç SATO SBPL, Honeywell (Datamax) DPL ve Honeywell (Intermec) IPL akışını ZPL'e çevirir; etiket böylece ZPL araçlarıyla önizlenir, denetlenir ve basılır. Gövde ham akıştır — gerçek kontrol karakterleri ile belgelerdeki okunabilir gösterim (<STX>, <ESC>) aynı sonucu verir. Kaynak dili siz seçersiniz: otomatik dil tespiti bu üç dili tanımaz.

Parametreler

Yanıt

Uyarı varsa çeviri birebir değildir. Desteklenen alt kümenin dışındaki komutlar — yazıcı ayarları (hız, koyuluk, sensör), RFID, iş yönetimi ve bazı 2B barkod türleri — uyarıyla atlanır, asla sessizce yutulmaz. Uyarıları etiketi basacak kişiye gösterin.

curl -X POST "https://api.labelixa.com/v1/convert/sbpl-to-zpl?dpmm=8" \
     --data-binary "<A><CS>6<V>100<H>200<L>0202<XM>ABCD<Q>1<Z>"

{"zpl": "^XA\n^FO199,99^A0N,48,48^FDABCD^FS\n^PQ1\n^XZ",
 "uyarilar": ["<CS> Print Speed not carried over to ZPL (manual p. 326; printer setting or outside the supported subset)"],
 "kaynak_dil": "sbpl", "birebir": false}

curl -X POST "https://api.labelixa.com/v1/convert/dpl-to-zpl?dpmm=8&etiket_boyu_mm=101.6" \
     --data-binary @label.dpl

Fiziksel yazıcıda doğrulanmadı. SATO, Datamax ya da Intermec yazıcı kullanılmadı: çıktı her üreticinin komut belgesine göre eşdeğer ZPL'dir. Döndürülmüş alanların konumu yaklaşıktır ve diğer yazı tipi aileleri ^A0'a taşınır; ikisi de uyarıyla söylenir. Üretimden önce önizlemeyi ve bir deneme baskısını kontrol edin.

Çeviri işlem kotasından düşmez; yalnız saniyelik hız sınırı uygulanır. Gövde en çok 512 KB (üstü 413), boş gövde 400. Uçlar durumsuzdur: kod saklanmaz, loglanmaz.

Aynısını tarayıcıda yapmak için: Yazıcı Dili Dönüştürücü.

Postman koleksiyonu

Bu referanstaki her uç, herkese açık Postman çalışma alanında hazır istek olarak duruyor: postman.com/labelixa-3901521. Koleksiyon OpenAPI şemasından (/openapi.json) üretilir; elle bakılan ikinci bir kopya değildir. Anahtar apiKey değişkeninde taşınır ve koleksiyona GÖMÜLMEZ — çalışma alanını çatalladıktan sonra kendi ortamınıza yazarsınız; boş bırakırsanız istekler anonim kotayla çalışır.

README'niz için rozet

Deponuzdaki ZPL dosyaları CI'da denetleniyorsa (POST /v1/diagnostics hatada sıfır dışı sonuç verir) bunu statik bir rozetle söyleyebilirsiniz — sayaç ve izleme yok, bir gün önbelleklenir:

[![ZPL validated with Labelixa](https://labelixa.com/static/badge-zpl-validated.svg)](https://labelixa.com/tools/zpl-preview)

Yalnız iddia deponuz için doğruysa kullanın; önizleyiciyi kendi sayfanıza gömme ve altına atıf satırı için gömme rehberi.