LabelInn REST API — ERP, WMS ve Özel Araçlarınıza Etiket Yazdırmayı Ekleyin (2026)

Eğer ekibiniz baskı işiyle uğraşan bir yazılım geliştiriyorsa — siparişleri tamamlayan bir ERP, depoyu yöneten bir WMS, operatörlerinizin yaşadığı bir iç panel — muhtemelen iki duvardan birine çarpmışsınızdır.

Birinci duvar: her yazıcı markasının kendi SDK'sı, sürücü varsayımları ve garipliği var. Yarı Zebra, yarı TSC, üzerine renkli etiket için Epson ColorWorks olan bir filoyu yönetmek üç ayrı entegrasyon ve üç ayrı nöbet rotasyonu demek. İkinci duvar: incelediğiniz "etiket API'leri" temelde dosya yükleme uçları. Bir PDF yazdırır, iş kimliği döner, biter. Filo görünümü yok, şablon sürümleme yok, 1.000 etiketlik bir partinin ortasında bir etiket başarısız olunca olay akışı yok.

LabelInn REST API ikinci sorunu çözmek için tasarlandı. Tek, sürümlenmiş, OpenAPI ile belgelenmiş bir yüzey: yazdırma, filo yönetimi, tasarım CRUD, toplu işlemler, webhook'lar, denetim izi ve kota — LabelInn'in desteklediği tüm yazıcılarda. Bu rehber yüzeyi, yetkilendirme modelini, idempotency'yi, hız limitlerini ve en sık gördüğümüz entegrasyon kalıplarını anlatır.

Temel URL ve Sürümleme

API şu adreste yayınlanıyor:

https://api.labelinn.com/v1

/v1 öneki kalıcı. Kırıcı değişiklikler /v2 olarak yayınlanır; /v1 halefin GA'sından sonra en az 18 ay desteklenir. Eklemeli değişiklikler (yeni opsiyonel alanlar, yeni uçlar) /v1'e iner.

OpenAPI 3.0.3 spesifikasyonunun tamamı yayınlanmış durumda — codegen aracınızı oraya yöneltin, bir dakikadan kısa sürede dilediğiniz dilde tipli istemciniz olur.

Yetkilendirme

LabelInn API anahtarları ile Bearer auth kullanır:

curl https://api.labelinn.com/v1/print/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json"

Anahtarları LabelInn panelinde Ayarlar → API Anahtarları bölümünden oluşturun. Kullanım başına kapsamlı anahtar öneriyoruz:

• İş gönderen ERP için sadece-yazdırma anahtar — tasarım yazma yok, anahtar rotasyonu yok
• Panel ve analitik için sadece-okuma anahtar — yazdırma yok, yazma yok
• Yalnızca yönetim araçları için tam-erişim anahtar — tek güvenilen sunucuda tutulur

Test anahtarları (sk_test_*) hiçbir fiziksel yazıcıya dokunmayan sandbox'a düşer — CI için ideal. Canlı anahtarlar (sk_live_*) gerçek donanımı sürer.

Önemli Uçlar

POST /v1/print/jobs — Yazdırma İşi Gönder

Beygir uç. Üç giriş modu: kayıtlı tasarım, ham ZPL veya barındırılan görsel URL'si.

POST /v1/print/jobs
{
  "printer_id": "prn_depo_a_01",
  "design_id": "dsg_kargo_pro",
  "variables": {
    "order_id": "SIP-45123",
    "customer_name": "Ayşe Yılmaz",
    "tracking_url": "https://takip.example.com/45123"
  },
  "copies": 2
}

Yanıt:

{
  "id": "job_01HVZK...",
  "status": "queued",
  "printer_id": "prn_depo_a_01",
  "queued_at": "2026-05-07T09:14:22.103Z"
}

Durum geçişleri: queued → printing → completed (veya failed). Bilmek için webhook kullanın; polling yapmayın.

POST /v1/print/batch — Tek Çağrıda 100'e Kadar İş

Gün sonu sipariş partileri için. Parti tek birim olarak kabul edilir veya reddedilir (geçersiz iş alan-seviyesi hatalarla partiyi düşürür), sonra her alt iş normal kuyruktan geçer. Geri dönüşte iş kimliklerinin dizisini alırsınız.

GET /v1/print/jobs — Listeleme ve Filtreleme

Sorgu parametreleri: status, printer_id, design_id, created_after, created_before, limit (en fazla 100), cursor. Sayfa numarası değil — cursor sayfalandırma; ağır trafik altında bile doğru kalır.

POST /v1/print/jobs/:id/reprint ve /retry

Reprint aynı yükle yeni bir iş yaratır (sizin kararınız — yeniden gönderim için). Retry geçici bir hatadan (sürücü, ağ, kağıt sıkışması) sonra orijinali yeniden kuyruklar ve 24 saatlik pencerede idempotenttir. Operasyon otomasyonu için retry, insan tetikli yeniden çalıştırma için reprint kullanın.

GET /v1/fleet/printers — Envanter ve Durum

Şirketin tüm yazıcılarını model, firmware, desteklenen medya boyutları, mevcut durum (online, offline, busy, error), kuyruk derinliği ve son hata ile birlikte döndürür. Filo panelini beslemek veya iş göndermeden önce sağlıklı bir hedef seçmek için kullanın.

GET / POST / PUT /v1/designs — Şablon CRUD

Şablon kütüphanenizi okuyun, JSON tanımından yeni tasarım yaratın veya mevcutları programatik olarak güncelleyin. POST /v1/designs/:id/publish ile birlikte tam sürüm kontrolüne sahip olursunuz: yayınlanmış her snapshot değişmezdir ve yazdırma çağrılarınızda sabitleyebileceğiniz snapshot_id'si vardır.

POST /v1/render — Yazdırmadan Render

Önizlemeler, denetimler veya başka bir sisteme PDF beslemek için yararlıdır. Tasarım + değişkenleri gönderin, geri PNG veya PDF URL'si alın. Varsayılan olarak asenkron — AI ajanları ve uzun süren render'lar için yanıt bir iş kimliğidir; polling veya webhook ile bekleyebilirsiniz.

POST / GET / DELETE /v1/webhooks — Olay Abonelikleri

Olaylara abone olun. En faydalı beş tanesi:

• job.completed — etiket başarıyla yazdırıldı
• job.failed — yazıcı reddetti, kağıt bitti, ZPL hatası vb. (yapısal hata alanlarıyla)
• printer.offline — sürücü kalp atışı kayıp
• printer.online — geri döndü
• design.updated — sisteminizin bağımlı olduğu bir tasarımın yeni snapshot'ı yayınlandı

Olaylar imzalıdır (gövde üzerinde HMAC-SHA256, anahtar olarak uç sırrınız). Yeniden deneme: 1sn → 5sn → 25sn → 60sn, en fazla 5 deneme. 50 ardışık başarısızlıktan sonra abonelik otomatik devre dışı bırakılır ve sahibine e-posta gider.

Idempotency

Her POST bir Idempotency-Key başlığı kabul eder. Yanıtı 24 saat önbelleğe alırız ve aynı gövdeyi tekrarlarda döndürürüz. Bu, entegrasyonunuzun en büyük güvenilirlik kaldıracıdır — ayarlayın ve 1.000 işlik bir gün sonu partisi sırasındaki ağ kesintisi 1.000 yinelenmiş baskı üretmez.

curl https://api.labelinn.com/v1/print/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: siparis-45123-kargo-v2" \
  -H "Content-Type: application/json" \
  -d '{...}'

Hem iş kimliğini hem amacı içeren anahtarlar seçin — yalnızca 45123 değil, siparis-45123-kargo-v2 — böylece müşteri hizmetlerinin yeniden yazdırma talebi orijinalle deduplike edilmez.

Hız Limitleri

Limitler her yanıtta X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarında döner. 429 yanıtı saniye cinsinden Retry-After başlığı içerir — geri çekilin, üst üste vurmayın.

Hata Modeli

Her hata, sabit bir code, insan-okur message ve details objesi içeren bir JSON gövdesidir. Switch'inizi code üzerinde yaparsınız:

{
  "error": {
    "code": "printer_offline",
    "message": "Yazıcı prn_depo_a_01 çevrimdışı.",
    "details": {
      "printer_id": "prn_depo_a_01",
      "last_seen": "2026-05-07T08:42:11.000Z"
    }
  }
}

Yaygın kodlar: invalid_argument, printer_offline, printer_busy, design_not_found, quota_exceeded, idempotency_key_conflict, media_mismatch (tasarımın medya boyutu yazıcıya yüklü etiketle uyuşmuyor).

Sık Görülen Entegrasyon Kalıpları

Kalıp 1: ERP Gönderir, Uygulama Yazdırır

ERP'niz siparişleri tutar. Bir paketleyici siparişi hazır olarak işaretlediğinde ERP, siparişin tasarımı ve değişkenleriyle POST /v1/print/jobs çağırır. LabelInn bulutu işi kuyruklar ve doğru yazıcıya iter. ERP'niz job.completed webhook'unu alır ve sipariş durumunu günceller. Uçtan uca gecikme tipik olarak yazıcı ısınmasına bağlı 1,5–4 saniyedir.

Kalıp 2: Eski Yazıcı Kodu için Sidecar Servisi

Yıllardır Zebra ZPL SDK üzerinden etiket yazdıran bir Windows servisiniz var. Değiştirmek riskli. Yerine LabelInn API'sini drop-in olarak kullanın: ZPL şablonlarınızı koruyun, "raw_zpl": "..." ile POST /v1/print/jobs üzerinden gönderin. İş mantığınıza dokunmadan filo görünümü, retry semantiği ve denetim izi kazanırsınız.

Kalıp 3: Çok Lokasyonlu Yönlendirme

Şirketinizin üç deposu var, her birinin kendi yazıcıları. LabelInn'de yazıcılarınızı lokasyon kimlikleriyle etiketleyin, sonra belirli bir printer_id yerine "site_id": "depo_b" ile iş gönderin — LabelInn'in edge router'ı o lokasyondaki en sağlıklı yazıcıyı seçer ve birincisi çevrimdışıysa en yakına failover yapar.

Kalıp 4: Denetim Yoğun Sektörler

Eczacılık, gıda izlenebilirliği, regüle elektronik. Hangi tasarım sürümünün hangi seri numarasını hangi fiziksel yazıcıya hangi zaman damgasıyla yazdırdığını kanıtlamanız gerekir. LabelInn'in tasarım snapshot mekanizması artı iş bazlı denetim günlüğü bunu kutudan çıkar çıkmaz sağlar. Seri numara havuzunuzu tasarıma değişken olarak takın, yayınlamayı QA akışınızın gerisine kapatın; API onaylanmış snapshot'tan sapanları yazdırmayı reddeder.

Webhook'lar: Polling Yapmayın

GET /v1/print/jobs/:id polling çalışır ama ölçeklenemez. İlk POST /v1/print/jobs çağrınızı bağladığınız gün job.completed ve job.failed üzerine webhook kurun. Node ile örnek alıcı:

app.post('/labelinn-webhook', (req, res) => {
  const sig = req.header('LabelInn-Signature');
  const computed = hmacSha256(req.rawBody, process.env.WEBHOOK_SECRET);
  if (!timingSafeEqual(sig, computed)) return res.sendStatus(401);

  const evt = JSON.parse(req.rawBody);
  if (evt.type === 'job.failed') {
    notifyOps(evt.data.job_id, evt.data.error);
  }
  res.sendStatus(200);
});

10 saniye içinde 200 dönün. Ağır işi arka planda yapın — webhook timeout'ları yeniden denemeyi tetikler ve bu da yinelenen işleme yol açar.

API'de Henüz Olmayanlar

• Gerçek zamanlı iş akışı — şimdilik webhook kullanın. Operasyon panelleri için WebSocket / Server-Sent-Events firehose 2026 yol haritasında.
• API ile çoklu para birimi faturalandırma — faturalandırma bugün yalnızca panelden; programatik fatura çekimi yıl içinde gelecek.
• Çapraz kiracı federasyonu — yönetilen servis sağlayıcılar için ana anahtar yetkilendirmesi: erken erişim için bizimle iletişime geçin.

Bugün API Anahtarınızı Alın

API erişimi Pro plan ve üzerinde gelir. 14 günlük Pro deneme API erişimini içerir — test anahtarı oluşturun, codegen'i OpenAPI spec'ine yöneltin, bir saatten az sürede ilk işinizi gönderin. Ölçeğiniz Business veya Enterprise sınırına yaklaşıyorsa ekibimiz entegrasyonda doğrudan yardım eder.