XJDF API Rehberi

XJDF katmanı standart referanslı discovery ve doğrulama ile ayrı korunan costing ve dış mesajlaşma sunar. Public metadata CIP4 sertifikasyonu, yasal uygunluk, üretimde yürütme veya external GA kanıtı değildir. Platform vocabulary'si XJDF 2.2, XJMF ve PrintTalk 2.2'dir; legacy JDF/JMF connector kenarında kalır.

Temel endpoint'ler

Endpoint	Amaç ve otorite
GET /api/v1/xjdf	Public discovery
GET /api/v1/xjdf/openapi	Public generated metadata
GET /api/v1/xjdf/capabilities	Static ürün/medya/finishing vocabulary; kuruluş stoğu veya canlı cihaz uygunluğu değildir
POST /api/v1/xjdf/validate	Public temel CIP4 JSON zarf kontrolü
POST /api/v1/costing/calculate-xjdf	Kuruluş oturumu ve sunucuda çözülen etkin L4 otoritesiyle costing

Public metadata/doğrulama Partner anahtarı veya mTLS istemez. Güncel süreç içi IP limiti dakikada 30 istektir; Retry-After ile 429 XJDF_RATE_LIMIT_EXCEEDED dönebilir. Kalıcı kuruluş kotası değildir.

Costing kuruluş oturumu ister; gövdede farklı kuruluş reddedilir. Onaylı/etkin L4 maliyet otoritesini sunucu çözer; istemci bağlamı yetki sağlamaz. Eksik otorite 409 COSTING_AUTHORITY_REQUIRED döndürür. Manual-review çıktı müşteri teklifi veya gözetimsiz AutoBid otoritesi değildir.

Otoritatif costing için çözülen snapshot'ta bulunan tam ResourceSet Media/@ID referansları gerekir. Etiket/gramaj tahmini ID veya fiyata çevrilmez. Costing isteği kendi @Version/ProductList temsilini kullanır; aşağıdaki public doğrulayıcı zarfıyla değiştirilemez.

Validation

Content-Type: application/json gönderin. Doğrulayıcı CIP4 JSON XJDF kökü bekler:

curl -X POST https://api.nowtoprint.com/api/v1/xjdf/validate \
  -H 'Content-Type: application/json' \
  -d '{"XJDF":{"Version":"2.2","JobID":"example-job"}}'

Bu üretim job ticket'ı değil, asgari zarf örneğidir. Güncel doğrulayıcı kök, Version ve JobID varlığını kontrol eder; eksik ProductList veya 2.x dışı sürüm için uyarı üretir. Tam XSD/JSON-Schema veya kapsamlı semantik doğrulama değildir. Eksik content type 415, bozuk JSON veya geçersiz içerik 400, geçerli doğrulama 200 döner. Sonuç ve issues alanlarını kontrol edin. Doğrulamanın geçmesi workflow yürütmez, stok kanıtlamaz, yetkili fiyat oluşturmaz veya belgeyi sertifikalandırmaz.

XJMF ve webhook sınırı

Dış XJMF status vocabulary'si iç workflow stage'lerinden ayrıdır. Gelen callback /api/v1/webhooks/xjmf üzerinden X-XJMF-Signature, X-XJMF-Sender, X-XJMF-Timestamp ile gönderilir. Sender sunucudaki XJMF_SENDER_SECRETS içinde kayıtlı, timestamp beş dakika içinde olmalıdır.

İmza ham gövdenin çıplak hex HMAC-SHA256 değeridir; timestamp ayrıca kontrol edilir. Güncel replay cache on dakika boyunca süreç içidir; kalıcı exactly-once teslimat sağlamaz. Başarılı callback makbuzu dış işlemin üretimde tamamlandığını kanıtlamaz. Bu başlıklar Marketplace Standard Webhooks teslimatından farklıdır.

Güvenlik ve operasyon

• Public metadata, costing oturumu ve sender HMAC yetkisini ayırın.
• Üretim devrinde immutable resolved snapshot referansını koruyun.
• Desteklenmeyen/belirsiz kaynakları ve manual-review sonuçlarını açık kanıt olarak değerlendirin.
• Etkiyi tekrarlamadan önce belirsiz teslimat veya costing sonucunu uzlaştırın.

Sık hata kodları

HTTP	Kod veya durum	Anlamı
400	Geçersiz JSON/XJDF	Doğrulayıcı zarfı ve raporlanan sorunları düzeltin
401	Authentication required	Costing kuruluş oturumu ister
403	Organization scope mismatch	Gövdedeki kuruluş oturumdan farklı olamaz
409	COSTING_AUTHORITY_REQUIRED	Onaylı/etkin L4 otoritesi yok
409	COSTING_MANUAL_REVIEW_REQUIRED	Sonuç gözetimsiz teklif için uygun değil
422	XJDF_COSTING_MEDIA_AUTHORITY_REQUIRED	Tam otoritatif medya referansı gerekir
429	XJDF_RATE_LIMIT_EXCEEDED	Public metadata/doğrulama limiti doldu

İlgili konular