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	Amac
GET /api/v1/xjdf	Discovery ve yuzey bilgisi
GET /api/v1/xjdf/openapi	OpenAPI 3.1 spesifikasyonu
GET /api/v1/xjdf/capabilities	Desteklenen urun, medya ve finishing yetenekleri
POST /api/v1/xjdf/validate	XJDF dokuman dogrulama
POST /api/v1/costing/calculate-xjdf	L4 otoritesi bagliysa costing (pre-live)

For an authoritative XJDF cost, include an exact ResourceSet media Media/@ID that exists in the server-resolved L4 snapshot. Media labels and grammage are descriptive only; they are never converted into a guessed Master Data ID or price. No-ID media is a manual-review/authority-required outcome.

---

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 accepts source=platform|organization, limit=1..100 and a safe-integer offset=0..100000, and requires master_data:read. When source is omitted, media defaults to organization. /api/v1/xjdf/devices accepts source=platform|organization, requires devices:read, and defaults to platform when source is omitted. Organization tenant identity always comes from the API credential; caller-supplied orgId is rejected. Empty tenant results stay empty, and repository/integrity or bounded-corpus overflow failures return 503/409 without platform fallback. Selected media and installed equipment are tenant projections/capabilities, not canonical L2 authority.

All credential-authenticated bridge responses, including errors, are private no-store and vary on X-API-Key plus Authorization. Duplicate canonical media or device identities return 409 rather than being silently collapsed. Organization device capabilities are schema- and semantic-validated: media dimensions come only from explicit print-area dimensions, never grammage. Per-device class and ICS claims are omitted until a governed evidence field exists; the response-level platform ICS metadata is not evidence for an individual installed device.

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 dokumani schema ve temel semantik kurallara gore 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 su sorulari cevaplar:

• schema gecerli mi?
• beklenen vocabulary kullaniliyor mu?
• desteklenmeyen alan veya kategori var mi?

---

XJMF ve webhook siniri

XJMF webhook'lari yalnizca harici vocabulary kabul eder. Ic workflow stage'leri dis Status alani icine yazilmaz.

Beklenen prensip:

• external XJMF status = partnerlar arasi mesajlasma dili
• internal workflow stage = platform ici event dili

Bu ayrim birlikte calisabilirlik icin zorunludur.

Inbound XJMF callback icin /api/v1/webhooks/xjmf kullanilir. Bu route X-XJMF-Signature, X-XJMF-Sender ve X-XJMF-Timestamp header'larini ister; sender server-side XJMF_SENDER_SECRETS registry'sinde kayitli olmali ve timestamp 5 dakikalik replay window icinde kalmalidir.

---

Guvenlik ve operasyon

• API erisimi API key veya uygun entegrasyonlarda mTLS ile korunur
• webhook ve signal alanlarinda signature dogrulamasi zorunludur
• unsupported veya dogrulanamayan source/compatibility durumlari confidence dusurur
• manual review gereken durumlar kesin quote gibi sunulmaz

---

Sik hata kodlari

HTTP	Kod	Aciklama
400	VALIDATION_ERROR	Gecersiz XJDF yapisi veya semantik sorun
400	INVALID_CATEGORY	Gecersiz master-data kategorisi
401	Authentication required	Authenticated organization session is required
401	MISSING_API_KEY	API key saglanmadi
401	INVALID_API_KEY	Gecersiz API key
403	Organization scope mismatch	Body organization cannot differ from the session
403	INSUFFICIENT_SCOPE	Yetersiz izin kapsami
409	COSTING_AUTHORITY_REQUIRED	Approved/effective L4 authority is unavailable
409	COSTING_MANUAL_REVIEW_REQUIRED	Result is not safe for unattended quoting
422	XJDF_COSTING_MEDIA_AUTHORITY_REQUIRED	ResourceSet media needs an exact Media/@ID
429	RATE_LIMIT_EXCEEDED	Hiz limiti asildi

---

Ilgili konular