XJDF API Rehberi

NowToPrint XJDF yüzeyi, CIP4 uyumlu entegrasyonları modern API disipliniyle sunar. Bu katmanda XJDF 2.2, PrintTalk 2.2 ve harici mesajlaşma için XJMF kullanılır.

---

Temel endpoint'ler

Endpoint	Amaç
GET /api/v1/xjdf	Discovery ve yüzey bilgisi
GET /api/v1/xjdf/openapi	OpenAPI 3.1 spesifikasyonu
GET /api/v1/xjdf/capabilities	Desteklenen ürün, medya ve finishing yetenekleri
GET /api/v1/xjdf/media-catalog	Kanonik medya katalog görünümü
GET /api/v1/xjdf/master-data-export	XJDF ResourceSet bazlı master-data export
POST /api/v1/xjdf/validate	XJDF doküman doğrulama

---

Master data export

Export yüzeyi düz bir kağıt veya makine listesi dönmez. Kanonik modelden türetilen ResourceSet'leri sunar.

Ana aileler:

• paper veya media
• machine veya device
• ink
• lamination
• varnish
• plate
• adhesive
• electricity
• labor

Sık parametreler:

Parametre	Tip	Açıklama
category	string	Virgülle ayrılmış kategori listesi
includeValidation	boolean	Export ile birlikte validation özeti döner

Örnek:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.nowtoprint.com/api/v1/xjdf/master-data-export?category=paper,ink&includeValidation=true"

Master-data semantiği için ana referans: XJDF Master Data Modeli

---

Validation

POST /api/v1/xjdf/validate endpoint'i dokümanı schema ve temel semantik kurallara göre kontrol eder.

curl -X POST https://api.nowtoprint.com/api/v1/xjdf/validate \
  -H "Content-Type: application/json" \
  -d '{
    "@Version": "2.2",
    "ProductList": {
      "Product": { "@ProductType": "BusinessCard" }
    }
  }'

Validation şu soruları cevaplar:

• Schema geçerli mi?
• Beklenen vocabulary kullanılıyor mu?
• Desteklenmeyen alan veya kategori var mı?

---

XJMF ve webhook sınırı

XJMF webhook'ları yalnızca harici vocabulary kabul eder. İç workflow stage'leri dış Status alanı içine yazılmaz.

Beklenen prensip:

• external XJMF status = partnerlar arası mesajlaşma dili
• internal workflow stage = platform içi event dili

Bu ayrım birlikte çalışabilirlik için zorunludur.

---

Güvenlik ve operasyon

• API erişimi API key veya uygun entegrasyonlarda mTLS ile korunur
• webhook ve signal alanlarında signature doğrulaması zorunludur
• unsupported veya doğrulanamayan source/compatibility durumları confidence düşürür
• manual review gereken durumlar kesin quote gibi sunulmaz

---

Sık hata kodları

HTTP	Kod	Açıklama
400	VALIDATION_ERROR	Geçersiz XJDF yapısı veya semantik sorun
400	INVALID_CATEGORY	Geçersiz master-data kategorisi
401	MISSING_API_KEY	API key sağlanmadı
401	INVALID_API_KEY	Geçersiz API key
403	INSUFFICIENT_SCOPE	Yetersiz izin kapsamı
429	RATE_LIMIT_EXCEEDED	Hız limiti aşıldı

---

İlgili konular