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.

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.

Uç noktalar

İstek header'ları

Yanıt header'ları

Hata kodları

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.

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.

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.

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.