XJDF API Rehberi

NowToPrint XJDF yuzeyi, private-beta ve dark-launch kullanimi icin standart referansli bir readiness katmanidir. Bu katmanda XJDF 2.2, PrintTalk 2.2 ve harici mesajlasma icin XJMF kullanilir; bu sayfa CIP4 sertifikasyonu, yasal uygunluk veya external GA iddiasi degildir.

---

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
POST /api/v1/xjdf/validate	XJDF doküman doğrulama
POST /api/v1/costing/calculate-xjdf	L4 otoritesi bağlıysa costing (pre-live)

Authoritative XJDF costing için server tarafından çözülen L4 snapshot içinde var olan kesin bir ResourceSet media Media/@ID gönderilmelidir. Media etiketi ve gramaj yalnızca açıklayıcıdır; tahmini Master Data ID veya fiyat üretilmez. ID olmayan media manual-review/authority-required sonucudur.

---

Master Data-backed internal bridge

Master Data-backed XJDF bridge route'lari public contract degildir. Kodda route'lar var olabilir, ancak /api/v1/xjdf/media-catalog, /api/v1/xjdf/master-data-export ve /api/v1/xjdf/devices internal-only kabul edilir; public discovery ve public OpenAPI tarafinda yayinlanmaz.

/api/v1/xjdf/media-catalog, source=platform|organization, limit=1..100 ve yalnızca güvenli tamsayı olan offset=0..100000 parametrelerini kabul eder ve master_data:read scope'u ister. source verilmezse medya organization değerini kullanır. /api/v1/xjdf/devices, source=platform|organization kabul eder, devices:read ister ve source verilmezse platform değerini kullanır. Organization tenant kimliği daima API credential'ından alınır; istemcinin gönderdiği orgId reddedilir. Boş tenant sonucu boş kalır; repository/integrity veya bounded-corpus taşması platform verisine düşmeden 503/409 döner. Seçili medya ve kurulu ekipman tenant projection/capability verisidir; kanonik L2 otoritesi değildir.

Hatalar dahil credential ile doğrulanan tüm bridge yanıtları private no-store kullanır ve X-API-Key ile Authorization başlıklarına göre farklılaşır. Yinelenen kanonik medya veya cihaz kimlikleri sessizce birleştirilmez, 409 döner. Organizasyon cihaz yetenekleri schema ve semantik olarak doğrulanır: medya boyutları yalnızca açık print-area ölçülerinden gelir, gramajdan üretilmez. Governed bir evidence alanı oluşana kadar cihaz bazında class ve ICS iddiası yayınlanmaz; response seviyesindeki platform ICS metadata'sı tek bir kurulu cihaz için evidence değildir.

Internal bridge su ailelerde kanonik modelden ResourceSet uretir:

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

External kullanicilar bu route'lara dogrudan baglanmamalidir. Master-data semantigi icin 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	Authentication required	Authenticated organizasyon session'ı zorunlu
401	MISSING_API_KEY	API key sağlanmadı
401	INVALID_API_KEY	Geçersiz API key
403	Organization scope mismatch	Body organizasyonu session organizasyonundan farklı
403	INSUFFICIENT_SCOPE	Yetersiz izin kapsamı
409	COSTING_AUTHORITY_REQUIRED	Approved/effective L4 otoritesi kullanılamıyor
409	COSTING_MANUAL_REVIEW_REQUIRED	Sonuç unattended teklif için güvenli değil
422	XJDF_COSTING_MEDIA_AUTHORITY_REQUIRED	ResourceSet media kesin Media/@ID içermeli
429	RATE_LIMIT_EXCEEDED	Hız limiti aşıldı

---

İlgili konular