Temel Kavramlar: Dosyalar, Teklifler ve İşler

1. Kimlik Doğrulama ve Güvenlik

Her uç nokta Quote3D API token'ınızla kimlik doğrulaması gerektirir; tek istisna Dosya Yönetimi altında belgelenen genel yükleme rotasıdır. Harici çağrılar için https://api.quote3d.com/v2 temel rotasını kullanın. Token'ı ister Authorization: Bearer YOUR_TOKEN ister X-API-Token olarak gönderin. Token'ları Quote3D panelinizden oluşturun ve gizli tutun.

Token'lar kapsamlandırılabilir. Tam erişimli bir token her uç noktaya ulaşır, widget kapsamlı bir token ise yalnızca gömülü widget'ın ihtiyaç duyduğu uç noktalarla sınırlıdır. Bir token'ın kapsamı dışındaki her çağrı 403 döndürür. Bir token'ın kapsamını panelinizin Token'lar sayfasından görüp değiştirebilirsiniz.

2. Hesap Yönetimi

Hesabınızı, yüklemelerinizi ve kullanım istatistiklerinizi özel uç noktalar aracılığıyla yönetin:

• GET /v2/user Hesap bilgilerinizi, planınızı ve aylık kotalarınızı getirir — quotes_used, quotes_limit, storage_used, storage_limit ve reset_date burada bulunur
• GET /v2/user/uploads Hesabınıza yüklediğiniz tüm dosyaları listeleyin. Bunlar en yeni en eskiye doğru sıralanır.
• GET /v2/quota Hız limiti kotalarınızı getirir — genel limitin yanı sıra kalan çağrı ve sıfırlanma zamanlarıyla uç nokta bazlı döküm — bugün, bu ay, bu yıl ve tüm zamanlar için istek sayılarınızla birlikte
• GET /v2/usage Endpoint istatistikleri, malzeme kullanımı ve zamana dayalı trendler dahil detaylı kullanım analitiklerini alın
• GET /v2/config Hesabın açık teknolojileri, yazıcıları, renkleriyle (stokta olan ya da olmayan) malzemeleri ve fiyat varsayılanları; yani widget'ın sunduğu her şey. Widget kapsamlı token'lar da okuyabilir.

3. Dosya Yönetimi

3D model dosyalarınızı (STL, 3MF, OBJ, STEP formatları) yükleyin, indirin ve yönetin:

• GET /v2/file/upload-id — Yeni bir dosya yüklemek için geçici bir upload_id almak için genel yükleme rotasını kullanın.
• POST /v2/file/public/{upload_id} — Bu rota kimlik doğrulaması gerektirmez. Dosyaları doğrudan depolama alanımıza yüklemek için istemci tarafınızda kullanın.

  Public Upload rotasını kullanmak, büyük dosyaları backend sunucunuz üzerinden yönlendirmekten kaçınmanızı sağlar. Bu, API token'ınızı açığa çıkarmayı önler ve sunucu yükünü azaltır.

• POST /v2/file — Sunucu tarafınızdan bir dosya yükleyin (kimlik doğrulama gerektirir, backend'den yüklemek istediğinizde kullanın)
• GET /v2/file/{file_id} — file_id kullanarak bir dosyayı indirin
• DELETE /v2/file/{file_id} — Artık ihtiyacınız olmayan bir dosyayı silin

Dosya geçerli bir STL, 3MF, OBJ veya STEP modeli değilse ya da platform dosya boyutu limitini (varsayılan 50 MB) aşıyorsa yükleme reddedilir. STEP dosyaları (.step/.stp) sunucuda OrcaSlicer ile aynı ayarlarla (doğrusal sapma 0,003 mm, açısal sapma 0,5 rad) üçgenlere bölünür; bir montajdaki tüm gövdeler birleştirilir ve uzunluklar milimetreye çevrilir. Her iki yükleme rotası da aynı kontrolleri uygular.

Dosyalarınızın nasıl saklandığı

Yüklenen modeller şifrelenmiş olarak saklanır ve asla herkese açık şekilde erişilemez — saklanan bir dosyayı doğrudan sunan bir bağlantı bulunmamaktadır. Yanıtlardaki file_path alanı, disk üzerindeki bir konum değil, kimlik doğrulaması yapılmış indirme yoludur (GET /v2/file/{file_id}); bu nedenle bunu paylaşabileceğiniz bir URL yerine bir uç nokta olarak değerlendirin. Bir dosyayı silmek, onu sadece listelemelerinizden değil, depolama alanından da kaldırır.

4. Parça Bilgisi ve Teknik Analiz

Modellerinizin yazdırılabilir olup olmadığını kontrol edin, parça boyutlarını ve gelişmiş teknik metrikleri alın:

• POST /v2/printability/{file_id} Anlık Analiz - Fiyat teklifi oluşturmadan önce yüklenen dosyanın ölçümlerini, hacmini, yüzey alanını ve geometri bütünlüğünü (çatlak/açık kenar) kontrol edin.

Quote3D, sadece boyut kontrolü yapmaz; modelin geometri hatlarını (manifold integrity) ve 3D baskı için kritik olan yatak tutunma riskini (adhesion risk) analiz eder. Bu veriler hem Printability hem de Quote yanıtlarında sağlanır.

5. Fiyat Teklifi İşlemleri

3D baskılarınız için anında fiyat teklifleri oluşturun ve fiyat teklifi geçmişini yönetin:

• POST /v2/file/quote/{file_id} — Bir 3D model için asenkron fiyat teklifi hesaplamasını başlatın. Bir iş kimliği döndürür; tamamlanan sonucu jobs endpoint'i üzerinden alırsınız.
• POST /v2/file/quote/{file_id}/async — Alternatif asenkron fiyat teklifi endpoint'i. Durumunu kontrol etmek ve tamamlanan sonucu almak için kullanabileceğiniz bir iş kimliği döndürür.
• GET /v2/jobs/{job_id} — Asenkron fiyat teklifi işinin durumunu kontrol edin. İlerleme yüzdesi ve tamamlanma durumu döndürür.
• GET /v2/quotes — Sayfalama desteği ile tüm fiyat teklifi geçmişinizi alın
• GET /v2/quotes/{quote_id} — Belirli bir fiyat teklifi hakkında detaylı bilgi alın
• DELETE /v2/quotes/{quote_id} — Geçmişinizden bir fiyat teklifini kaldırın

Fiyat Teklifi İstek Parametreleri

Fiyat teklifi oluştururken, istek gövdesinde özel yapılandırma sağlayabilirsiniz. Belirtmediğiniz parametreler otomatik olarak Dashboard Slice Profile ayarlarınızdan alınacaktır. Bu, diğerleri için varsayılanları korurken fiyat teklifi başına belirli ayarları geçersiz kılmanıza olanak tanır.

Aşağıdaki tablolar entegrasyonların en sık geçersiz kıldığı parametreleri kapsar. Tam liste değildir — teklif motoru çok daha fazla yazıcı, malzeme ve fiyatlandırma alanı kabul eder ve bunların her biri her istekte gönderilmek yerine Panel Dilimleme Profillerinizde bir kez ayarlanabilir. Profillerinizi orada yapılandırın ve yalnızca teklife göre değişenleri gönderin; alanların tam listesi OpenAPI şemasındadır.

İstek Doğrulaması

printer_config, material_config ve quote_config içindeki sayısal alanlar, iş kuyruğa alınmadan önce sınır kontrolünden geçer. Aralığın dışındaki bir değer, sonlu olmayan bir sayı (NaN, Infinity), yanlış bir tür veya yalnızca sıfır ve üzerinin mantıklı olduğu durumlarda negatif bir sayı, HTTP 400 hatası ve tam alanı belirten bir VALIDATION_ERROR ile reddedilir. Sıfır, anlamlı olduğu her yerde kabul edilir; örneğin, role özel 0 hızı veya ivmesi, OrcaSlicer’ın kullandığı kurala benzer şekilde "yazıcı varsayılanını kullan" anlamına gelir.

• Sıcaklık limitleri: malzeme sıcaklıkları (istekte gönderilen veya Material Profile’dan okunan temperature ve bed_temperature), yazıcının min_hotend_temp / max_hotend_temp ve min_bed_temp / max_bed_temp değerlerine göre kontrol edilir. Seçilen yazıcının sağlayabileceğinden daha fazla ısı gerektiren bir malzeme, teklif oluşturulmak yerine reddedilir. Yalnızca FDM için geçerlidir; reçine ve toz teknolojilerinde nozul veya ısıtılmış tabla bulunmaz. Kontrolü atlamak için yazıcı limitlerini boş bırakın.
• Etkin teknolojiler: Global Settings kısmında teknolojileri kısıtladıysanız, devre dışı bırakılmış bir teknoloji için yapılan teklif isteği reddedilir. Tüm teknolojileri kabul etmek için ayarı boş bırakın.
• Malzeme fiyat alanları: price_per_gram, motorun ücretlendirdiği değerdir. Bir Material Profile kaydettiğinizde, price_per_kg otomatik olarak ondan yeniden hesaplanır (ve yalnızca kilogram fiyatı sağlandığında price_per_gram, price_per_kg’den türetilir), böylece bu iki değer asla birbiriyle çelişmez.

Kök Parametreler

Üretim Adedi ve Toplu Üretim Mantığı

Sistemimiz, belirtilen 'quantity' (adet) değerine göre gelişmiş bir yerleştirme algoritması kullanır:

• FDM Teknolojisi: Parçalar, yazıcının tabla genişliği (X ve Y) elverdiği ölçüde yan yana dizilir.
• SLA Teknolojisi: Parçalar, reçine havuzunda X ve Y eksenlerinde yan yana konumlandırılır.
• SLS Teknolojisi: Parçalar hem X, hem Y, hem de Z ekseninde (üst üste) konumlandırılarak toz yatağının tam kapasite kullanılması sağlanır.

printer_config

Yazıcı yapılandırma parametreleri. Tüm alanlar isteğe bağlıdır ve sağlanmazsa varsayılan Yazıcı Profili değerlerinizi kullanacaktır.

material_config

Malzeme yapılandırma parametreleri. Tüm alanlar isteğe bağlıdır ve sağlanmazsa varsayılan Malzeme Profili değerlerinizi kullanacaktır.

quote_config

Fiyat teklifi fiyatlandırma yapılandırma parametreleri. Tüm alanlar isteğe bağlıdır ve sağlanmazsa varsayılan Global Ayarlar değerlerinizi kullanacaktır. Para birimi varsayılan olarak dashboard tercihinizden (örn. 'USD', 'TRY', 'EUR') alınır.

6. Yazıcı ve Fiyat Teklifi Profilleri

Doğru fiyat teklifleri almak için yazıcı ayarlarını ve fiyatlandırmayı yapılandırın. API isteklerinde parametre belirtmediğinizde otomatik olarak kullanılacak olan varsayılan profillerinizi Dashboard Slice Profiles bölümünde yönetebilirsiniz.

Profil Türleri

• Yazıcı Profili - Gerçek yazıcınıza uyacak şekilde yazıcı ayarlarınızı (yatak boyutu, nozul çapı, baskı hızı, katman yüksekliği, ivme, jerk, sıcaklıklar, vb.) yapılandırın. Bunu Dashboard'da varsayılan profil olarak ayarlayın ve belirli parametreleri geçersiz kılmadığınız sürece tüm fiyat teklifi istekleri için kullanılacaktır.
• Malzeme Profili - Kullandığınız her malzeme için malzeme özelliklerini (filament türü, yoğunluk, çap, sıcaklıklar, fan hızı, geri çekme ayarları, fiyatlandırma) ayarlayın. API, istekte belirttiğiniz filament_type ile eşleşen malzeme profilini otomatik olarak kullanacaktır.
• Global Ayarlar - Vergi oranı, sabit ücretler, enerji maliyetleri ve varsayılan para birimi gibi global fiyat teklifi ayarlarını yapılandırın. Bu ayarlar, istekte geçersiz kılınmadığı sürece tüm fiyat tekliflerine uygulanır.

Profil Birleştirmenin Nasıl Çalıştığı

Fiyat teklifi isteği yaptığınızda, API istek parametrelerinizi Dashboard profillerinizle şu öncelikle birleştirir:

1. İstek Parametreleri - API isteğinde açıkça belirttiğiniz değerler en yüksek önceliğe sahiptir.
2. Kullanıcı Profili - Eğer varsayılan olarak ayarlanmış kullanıcıya özel bir profiliniz varsa, sonraki olarak kullanılır.
3. Global Profil - Eğer kullanıcı profili yoksa, sistem global varsayılanlara döner.

Bu, ihtiyacınız olan parametreleri (örn. sadece layer_height veya fill_density) geçersiz kılarken, Dashboard profillerinizden diğer tüm ayarları koruyabileceğiniz anlamına gelir.

7. Web Kancaları

Hesabınızda bir olay gerçekleştiğinde gerçek zamanlı bildirimler alın:

• POST /v2/webhooks - Yeni bir web kancası uç noktası oluşturun
• GET /v2/webhooks - Tüm web kancalarınızı listeleyin
• GET /v2/webhooks/{webhook_id} - Web kancası ayrıntılarını ve teslimat istatistiklerini alın
• PUT /v2/webhooks/{webhook_id} - Web kancası ayarlarını güncelleyin
• DELETE /v2/webhooks/{webhook_id} - Bir web kancasını kaldırın
• POST /v2/webhooks/{webhook_id}/deliveries/{delivery_id}/resend - Geçmiş bir gönderimi yeniden yollayın; örneğin uç noktanızı düzelttikten sonra

Desteklenen olaylar şunları içerir: quote.completed, quote.failed, file.uploaded, file.deleted, job.status_changed, widget.added_to_cart, usage.alert. Web kancaları, güvenlik doğrulaması için HMAC-SHA256 imzaları içerir.

Webhook referansı: yük yapısı, imza doğrulama, yeniden denemeler ve yeniden teslimat

8. Analitik ve Raporlama

API kullanımınız ve fiyat teklifi istatistikleriniz hakkında bilgi edinin:

• GET /v2/analytics/quotes - Toplam fiyat teklifleri, ortalama fiyatlar ve malzeme kullanım trendleri dahil kapsamlı fiyat teklifi istatistiklerini edinin.
• GET /v2/analytics/popular - En popüler malzemelerinizi ve yazıcı yapılandırmalarınızı görüntüleyin.
• GET /v2/analytics/cost-trends - Maliyet trendlerini zaman içinde analiz edin (günlük, haftalık veya aylık gruplama).
• GET /v2/analytics/export - Fiyat tekliflerinizi ve kullanım verilerinizi CSV veya JSON olarak dışa aktarın.

9. Katalog ve Stok

Hesabın kendi yazıcılarını, malzemelerini, renklerini, renk stoğunu, fiyatlandırmasını ve teknolojilerini sunucu token'ıyla yönetin. Widget aynı kataloğu okur, yani değişiklik teklif formuna hemen yansır. Widget kapsamlı token'lar reddedilir ve bu çağrılar aylık istek kotasından düşmez:

• GET /v2/store/catalog - Hesabın sunduğu her şey; teknoloji başına hazırlık durumu ve azalan renklerle
• GET /v2/store/catalog/schema - Paneldeki yazıcı, malzeme ve fiyatlandırma formları; sınırlar, birimler ve istenen dildeki yardım metinleriyle
• POST /v2/store/catalog/adopt - Global yazıcı ve malzemeleri, seçtiğiniz renkler, fiyat ve başlangıç stoğuyla hesaba kopyalayın
• POST /v2/store/catalog/materials - İsterseniz bir global malzemeden başlayarak yeni malzeme oluşturun
• GET · PATCH · DELETE /v2/store/catalog/materials/{id} - Tek bir malzemeyi stok ayarlarıyla birlikte okuyun, değiştirin ya da silin
• PUT /v2/store/catalog/materials/{id}/colors - Bir malzemenin renk listesini değiştirin; mevcut renklerin stoğu korunur
• GET · PATCH · DELETE /v2/store/catalog/printers/{id} - Tek bir yazıcıyı okuyun, değiştirin ya da silin
• GET · PATCH · DELETE /v2/store/catalog/pricing - Fiyatlandırma ayarlarını okuyun, değiştirin ya da sıfırlayın; para birimini değiştirmek hesabın para birimini değiştirir, tutarlar çevrilmez
• GET · PUT /v2/store/catalog/technologies - Planın hangi teknolojilere izin verdiği ve hangilerinin açık olduğu
• GET · POST /v2/store/stock/movements - Stok girişi, sayım ya da fire kaydedin ve stok geçmişini listeleyin
• POST /v2/store/stock/orders - Ödenmiş bir siparişin malzemesini düşün, geri ekleyin ya da yeterli mi diye bakın; teklif başına en fazla bir kez

PATCH gövdesi values ve updated_at taşır. values, katalog listesindeki snake_case alan adlarını kullanır (formda olmayan ad 400 ile reddedilir); profil siz okuduktan sonra değiştiyse çağrı error_key stale ile 409 döner.

10. Hız Sınırlama ve Kotlar

Quote3D, adil kullanım ve sistem kararlılığını sağlamak için hız sınırlaması kullanır:

• Hız limitleri API token başına uygulanır ve endpoint'e göre değişir
• Hız limiti bilgileri yanıt başlıklarında bulunur: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Window
• Hız sınırlandığında, Retry-After başlığı ile birlikte 429 Too Many Requests yanıtı alırsınız.
• Planınız her fatura döneminde sıfırlanan bir teklif hakkı ve hiç sıfırlanmayan, yalnız dosya silinince boşalan bir depolama alanı belirler.
• Limitler dağıtım başına yapılandırılabilir, bu yüzden değerleri koda gömmek yerine güncel değerleri okuyun. Hem yukarıdaki yanıt başlıkları hem de bu uç nokta bunları raporlar: GET /v2/quota

11. Yanıtlar ve Hatalar

Başarılı yanıtların iki biçimi var. Teklif, iş, kayıtlı teklif ayrıntısı, webhook, analitik, kullanım, kota ve config çağrıları yükü success: true ile sarar ve sonucu data altına koyar. Dosya, yükleme kimliği, kullanıcı, yüklemeler, teklif listesi, basılabilirlik ve Katalog ve Stok çağrıları alanlarını en üst düzeyde döndürür. Her çağrının tam şeması API başvurusundadır. Dosya indirmeleri ve CSV dışa aktarımları ham dosya gövdesini döndürür.

{
  "success": true,
  "data": { "...": "endpoint-specific payload" }
}

Sayfalama ve Sıralama

/v2/quotes ve /v2/user/uploads gibi liste uç noktaları limit ve offset sorgu parametreleriyle sayfalanır (varsayılan 50 sonuç, en fazla 100). Sonuçların yanında total, limit, offset, has_more, page ve total_pages barındıran bir pagination nesnesi döndürürler; bu yüzden listenin sonunu kendiniz hesaplamak yerine has_more değerini tercih edin. Sıralama, field:direction biçiminde tek ve tekrarlanabilir bir parametre kullanır, örneğin ?sort=created_at:desc&sort=total_price:asc; yüklemeler varsayılan olarak en yeniden başlar.

Hata Yanıtları

Her hata aynı biçimdedir: parametreyi ya da alanı adıyla gösteren bir detail listesi (loc, msg, code), AUTH_001 gibi bir error_code, bir error_summary ve gerektiğinde recovery_suggestions ile documentation_url. Değişebilecek metne değil, HTTP durum koduna ve error_code'a göre dallanın.

Asenkron teklifler farklıdır: işin kuyruğa alınması 202 ile başarılı olur ve sonrasında başarısız olan bir hesaplama, HTTP hatası olarak değil, iş uç noktasında bir hata mesajıyla failed durumu olarak ortaya çıkar. Yalnızca başlatırken aldığınız durum koduna değil, her zaman iş durumuna bakın.

12. RESTful, Sürümlenmiş API

• Tüm endpoint'ler versiyonludur (örn. /v2/)
• Standart HTTP yöntemleri kullanılır: GET, POST, PUT, DELETE
• Kendi araçlarınıza aktarabileceğiniz bir OpenAPI 3.0.3 şemasıyla tanımlanmıştır
• Kırıcı değişiklikler ve eklemeler şurada kayıt altına alınır: API değişiklik günlüğü