OpenAPI Explorer ve Spec Referansı

Güncel RFQ oluşturma ve kuruluşa ait tekil RFQ/teklif okuma sözleşmesi /api/v1/marketplace/openapi.json adresinde üretilir. Eski /docs/api/openapi.yaml yayını farklı bir referanstır; iki belgenin eşit olduğunu varsaymayın. Ortam adresini ve etkin yetkileri onboarding sırasında doğrulayın.

Bu sayfayı NowToPrint makine tarafından okunabilir sözleşmeleri için tek genel dizin olarak kullanın. Her yüzeyin bir kanonik indirme URL'si ve operasyonel bağlam için eşleşen bir rehberi bulunur.

---

Yayınlanan Kaynaklar

Kaynak	Genel URL	Oluşturulan referans	En uygun kullanım
Partner REST API sözleşmesi	/api/v1/marketplace/openapi.json	Partner REST API	Postman import, SDK üretimi ve QA sözleşme incelemesi
XJDF / PrintTalk sözleşmesi	/docs/api/xjdf-openapi.yaml	XJDF & PrintTalk API	Standart entegrasyonlar ve yetenek araçları
Ön kontrol Engine sözleşmesi	/docs/api/preflight-openapi.yaml	Yalnız spesifikasyon — henüz referans sayfası yok	İş gönderimi ve durum sorgulama için kuyruğa alınmış PDF inceleme istemcileri
XJDF Swagger önizlemesi	/docs/api/swagger-ui.html	XJDF entegrasyon rehberi	XJDF sözleşmesinin tarayıcı tabanlı incelenmesi

---

Partner REST API

Genel Bakış

Üretilen Marketplace sözleşmesi RFQ oluşturma (201), kuruluşa ait tek RFQ (?id=) ve tekliflerini okuma işlemlerini içerir; RFQ listesi yoktur. Estimate/order adaptörleri kimlik ve dakika kotasından sonra kabiliyete özel 503 döndürür; fiyat veya sipariş üretmez.

• Base URL: https://api.nowtoprint.com/api/v1
• Kimlik Doğrulama: Authorization: Bearer <ntp_partner_v2_ kimlik bilgisi>
• En uygun kullanim: auth ve disabled-capability contract kontrolleri

Capability kontrolu

curl -X POST https://api.nowtoprint.com/api/v1/estimate \
  -H "Authorization: Bearer ntp_partner_v2_<issued-key-id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "business_cards",
    "quantity": 500,
    "specifications": {
      "paperType": "coated-matte"
    }
  }'

Sonraki okumalar

• Partner API genel bakış
• Başlangıç rehberi
• Kimlik doğrulama

---

XJDF / PrintTalk API

Genel Bakış

XJDF ve PrintTalk katmanı, MIS, ERP ve iş akışı sistemleriyle standart tabanlı birlikte çalışabilirlik için tasarlanmıştır.

• Route ailesi: https://api.nowtoprint.com/api/v1/xjdf
• Kimlik Doğrulama: public metadata anahtar istemez; costing oturumu ve XJMF sender doğrulaması ayrıdır
• En uygun kullanım: standart tabanlı iş alışverişi, yetenek keşfi ve harici iş akışı uyumu

Tarayıcıda keşfedin

Spec dosyasını import etmeden önce kullanıcı dostu bir sözleşme incelemesine ihtiyaç duyduğunuzda yayınlanan önizlemeyi kullanın:

• Swagger UI önizlemesi
• Entegrasyon rehberi
• Master data modeli

---

Ön Kontrol Engine API

Genel Bakış

POST /api/v1/preflight, Partner V2 RFQ işlemi değildir. Ayrı PDF_TOOLS_API_KEY bearer anahtarı, API kapsamı ve ücretli server-work yetkisi gerekir. Ortama bağlı rate-limit yapılandırması da uygulanabilir.

Örnek istek

Aşağıdaki URL şablonunu dağıtımın yapılandırılmış Firebase bucket URL'siyle değiştirin; rastgele CDN veya özel ağ URL'si kabul edilmez.

POST /api/v1/preflight HTTP/1.1
Host: api.nowtoprint.com
Authorization: Bearer <separate-server-preflight-key>
Content-Type: application/json

{
  "fileUrl": "https://storage.googleapis.com/<configured-bucket>/artwork.pdf",
  "options": { "profile": "default", "automationMode": "preserve_safe_only" }
}

Örnek yanıt yapısı

Kabul HTTP 200 ve success: true ile gelir; data içinde jobId (pq_job_...), traceId, status: queued, fileUrl, profile, autoFix, automationMode, proofingContextId ve mesaj bulunur. Bu tamamlanmış analiz veya üretime uygunluk kanıtı değildir. Job yazımı ile Cloud Task dispatch ayrı adımlardır; dispatch hatasında önce job durumunu uzlaştırın.

preserve_safe_only varsayılandır. Eski autoFix: true, allow_recommend_only anlamına gelir; belge değişikliği yalnız açık allow_document_mutation modunda etkinleşir. Bu mod renk dönüşümü, font, trapping veya flattening gibi her işlemi yetkilendirmez.

Makine tarafından okunabilir sözleşme

Yayımlanan referans /docs/api/preflight-openapi.yaml üzerinden erişilir. Public spec ile güncel kuyruk/worker davranışı arasında bilinen uyum açıkları vardır; job kabulünü, tamamlanmasını ve teknik bulguyu ayrı doğrulayın. Paket sürümü public /v3 rota kanıtı değildir. Studio yerel/WASM analizi ve PDF partner planning endpoint'leri de farklı sözleşmelerdir.

---

Sorun detayları ve yeniden denemeler

NowToPrint, entegrasyon hatalarını yapılandırılmış HTTP yanıtları aracılığıyla sunar. Genel olarak:

• 400 yük veya şema uyumsuzluğu anlamına gelir
• 401 eksik veya geçersiz kimlik bilgileri anlamına gelir
• 403 kapsam veya yetki uyumsuzluğu anlamına gelir
• 429 dönen reset bilgisini kullanın; varsa Retry-After başlığına uyun anlamına gelir
• 5xx geçici hata veya bağımlılık kesintisi anlamına gelir

Loglarda istek kimliklerini kullanın, yazma işlemlerini idempotent tutun ve üretime geçmeden önce webhook'ları bağlayın.

---

Değişiklik yönetimi

Güncel RFQ sözleşmesi marketplace-partner-api.v1 olarak üretilir. Static allowlist yayınlarını gerçek operation/schema ile karşılaştırın; dosya yayını tek başına runtime parity, CIP4 sertifikasyonu veya external GA kanıtı değildir. Kırıcı farkları entegrasyon sahibiyle uzlaştırıp istemciyi sonra güncelleyin.

---

İlgili: API Referansı | Partner API | XJDF API | Webhook Erişimi ve Teslimat