Temel Kavramlar
Bu sayfa platformu güçlendiren temel fikirleri ve kalıpları tanıtır. Bu kavramları anlamak, API'den en iyi şekilde yararlanmanıza ve 3D baskı iş akışları için sağlam entegrasyonlar oluşturmanıza yardımcı olacaktır.
1. Kimlik Doğrulama ve Güvenlik
Tüm API endpoint'leri Bearer JWT token kullanarak kimlik doğrulaması gerektirir. Token'ları Quote3D dashboard'unuzdan oluşturursunuz ve her isteğin Authorization başlığına dahil edersiniz.
Hatırlatma: API token'larınızı güvende tutun. Asla halka açık olarak paylaşmayın veya versiyon kontrolüne commit etmeyin.
2. Hesap Yönetimi
Özel endpoint'ler aracılığıyla hesabınızı, yüklemelerinizi ve kullanım istatistiklerinizi yönetin:
GET /v2/userHesap detaylarınızı alınGET /v2/user/uploadsHesabınıza yüklediğiniz tüm dosyaları listeleyin. Bunlar en yeni en eskiye doğru sıralanır.GET /v2/quotaFiyat teklifleri ve depolama için mevcut kota limitlerinizi ve kullanımınızı alınGET /v2/usageEndpoint istatistikleri, malzeme kullanımı ve zamana dayalı trendler dahil detaylı kullanım analitiklerini alın
3. Parça Bilgisi
Modellerinizin yazdırılabilir olup olmadığını kontrol edin ve parça boyutlarını alın:
POST /v2/printability/{file_id}Fiyat teklifi oluşturmadan önce yüklenen dosyanın ölçümlerini alarak parçanın yazıcıya sığacağını kontrol edin.
Three JS'e aşinaysanız, bunu web uygulamanızın istemci tarafında JavaScript ile hesaplayabilirsiniz, bu endpoint'i kullanma ihtiyacını ortadan kaldırır. Bu size daha fazla seçenek sunmak için alternatif olarak sağlanmıştır.
4. Dosya Yönetimi
3D model dosyalarınızı (STL, 3MF, OBJ formatları) yükleyin, indirin ve yönetin:
- Yeni bir dosya yüklemek için geçici bir upload_id almak için genel yükleme rotası ile.:
GET /v2/file/upload-id- Yeni bir dosya yüklemek için geçici bir upload_id almak için genel yükleme rotası ile. - Bu rota kimlik doğrulaması gerektirmez. Dosyaları doğrudan depolamamıza yüklemek için istemci tarafınızda kullanın.:
POST /v2/file/public/{upload_id}- Bu rota kimlik doğrulaması gerektirmez. Dosyaları doğrudan depolamamı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.
- Sunucu tarafınızdan bir dosya yükleyin (kimlik doğrulaması gerektirir, backend'den yüklemek istediğinizde kullanın):
POST /v2/file— Sunucu tarafınızdan bir dosya yükleyin (kimlik doğrulaması gerektirir, backend'den yüklemek istediğinizde kullanın) - file_id kullanarak bir dosyayı indirin:
GET /v2/file/{file_id}— file_id kullanarak bir dosyayı indirin - Artık ihtiyacınız olmayan bir dosyayı silin:
DELETE /v2/file/{file_id}— Artık ihtiyacınız olmayan bir dosyayı silin
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:
- Bir 3D model için anında fiyat teklifi oluşturun. Detaylı fiyatlandırma, malzeme kullanımı ve baskı süresi tahminleri döndürür.:
POST /v2/file/quote/{file_id}— Bir 3D model için anında fiyat teklifi oluşturun. Detaylı fiyatlandırma, malzeme kullanımı ve baskı süresi tahminleri döndürür. - Asenkron olarak bir fiyat teklifi oluşturun. Durumu kontrol etmek için kullanabileceğiniz bir iş ID'si döndürür.:
POST /v2/file/quote/{file_id}/async— Asenkron olarak bir fiyat teklifi oluşturun. Durumu kontrol etmek için kullanabileceğiniz bir iş ID'si döndürür. - Asenkron fiyat teklifi işinin durumunu kontrol edin. İlerleme yüzdesi ve tamamlanma durumu 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. - Sayfalama desteği ile tüm fiyat teklifi geçmişinizi alın:
GET /v2/quotes— Sayfalama desteği ile tüm fiyat teklifi geçmişinizi alın - Belirli bir fiyat teklifi hakkında detaylı bilgi alın:
GET /v2/quotes/{quote_id}— Belirli bir fiyat teklifi hakkında detaylı bilgi alın - Geçmişinizden bir fiyat teklifini kaldırı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.
Önemli: İsteğinizde bir parametre sağlamazsanız, API Dashboard Slice Profile'dan (Yazıcı Profili, Malzeme Profili veya Global Ayarlar) değeri kullanacaktır. Tutarlı fiyat teklifleri için Dashboard'da varsayılan profillerinizi ayarladığınızdan emin olun.
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.
| Parameter | Type | Description |
|---|---|---|
| bed_size_x | number | Build volume X dimension (mm) |
| bed_size_y | number | Build volume Y dimension (mm) |
| bed_size_z | number | Build volume Z dimension (mm) |
| nozzle_diameter | number | Nozzle diameter (mm) |
| nozzle_count | number | Number of nozzles |
| print_speed | number | Default print speed (mm/s) |
| max_print_speed | number | Maximum print speed (mm/s) |
| travel_speed | number | Travel speed (mm/s) |
| first_layer_speed | number | First layer speed (mm/s) |
| layer_height | number | Layer height (mm) |
| min_layer_height | number | Minimum layer height (mm) |
| max_layer_height | number | Maximum layer height (mm) |
| perimeters | number | Number of perimeters/walls |
| top_solid_layers | number | Top solid layers count |
| bottom_solid_layers | number | Bottom solid layers count |
| min_wall_count | number | Minimum wall count |
| max_wall_count | number | Maximum wall count |
| fill_density | number | Infill density (0-100%) |
| infill_pattern | string | Infill pattern. Options: rectilinear, alignedrectilinear, zigzag, crosszag, lockedzag, line, grid, triangles, trihexagon, cubic, adaptivecubic, supportcubic, honeycomb, honeycomb3d, lateralhoneycomb, gyroid, monotonic, monotonicline, lightning. Default: rectilinear |
| support_material | boolean | Enable support material |
| support_overhang_angle | number | Support overhang angle (degrees) |
| support_density | number | Support density (0-100%) |
| acceleration_print | number | Print acceleration (mm/s²) |
| acceleration_travel | number | Travel acceleration (mm/s²) |
| acceleration_retraction | number | Retraction acceleration (mm/s²) |
| jerk_print | number | Print jerk (mm/s) |
| jerk_travel | number | Travel jerk (mm/s) |
| jerk_retraction | number | Retraction jerk (mm/s) |
| min_hotend_temp | number | Minimum hotend temperature (°C) |
| max_hotend_temp | number | Maximum hotend temperature (°C) |
| min_bed_temp | number | Minimum bed temperature (°C) |
| max_bed_temp | number | Maximum bed temperature (°C) |
| hourly_cost | number | Machine hourly cost |
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.
Malzeme Profili Entegrasyonu: filament_type parametresi Dashboard Malzeme Profilinizden bir malzeme adıyla eşleşmelidir. Bir filament_type (örn. "PLA", "ABS", "PETG") belirttiğinizde, API otomatik olarak o Malzeme Profilinden tüm özellikleri yükler, yoğunluk, sıcaklıklar, geri çekme ayarları ve fiyatlandırma dahil.
Fiyatlandırma Doğruluğu: Doğru maliyet hesaplamaları için, Malzeme Profilinizde hem price_per_kg hem de price_per_gram değerlerini ayarladığınızdan emin olun. API, baskıda kullanılan gerçek filament ağırlığına göre malzeme maliyetlerini hesaplamak için bu değerleri kullanır. Profilinizde bu değerler ayarlanmamışsa, API isteğinde bunları geçersiz kılabilirsiniz.
Örnek: Dashboard'unuzda price_per_kg: 20.0 ve price_per_gram: 0.02 ile bir "PLA" malzeme profiliniz varsa, isteğinizde sadece {"filament_type": "PLA"} gönderebilirsiniz ve tüm fiyatlandırma otomatik olarak hesaplanacaktır.
| Parameter | Type | Description |
|---|---|---|
| filament_type | string | Filament type (PLA, ABS, PETG, etc.) |
| density | number | Material density (g/cm³) |
| diameter | number | Filament diameter (mm) |
| temperature | number | Print temperature (°C) |
| print_temp_min | number | Minimum print temperature (°C) |
| print_temp_max | number | Maximum print temperature (°C) |
| bed_temperature | number | Bed temperature (°C) |
| bed_temp_min | number | Minimum bed temperature (°C) |
| bed_temp_max | number | Maximum bed temperature (°C) |
| fan_speed | number | Fan speed (0-100%) |
| min_fan_speed | number | Minimum fan speed (0-100%) |
| retraction_distance | number | Retraction distance (mm) |
| retraction_speed | number | Retraction speed (mm/s) |
| price_per_kg | number | Price per kilogram |
| price_per_gram | number | Price per gram |
| support_cost_multiplier | number | Support material cost multiplier |
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.
| Parameter | Type | Description |
|---|---|---|
| currency | string | Currency code (USD, EUR, etc.) |
| tax_rate | number | Tax rate percentage (0-100) |
| fixed_fee | number | Fixed fee per quote |
| energy_cost_per_kwh | number | Energy cost per kWh |
İpucu: Fiyat teklifleri otomatik olarak hesabınıza kaydedilir. Bunlara fiyat teklifi geçmişi endpoint'leri aracılığıyla istediğiniz zaman erişebilirsiniz.
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. Dashboard Slice Profiles bölümünde varsayılan profillerinizi yönetebilirsiniz, bu da API isteklerinde parametre belirtmediğinizde otomatik olarak kullanılacaktır.
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 katman yükseklikleri 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.
En İyi Uygulama: Dashboard Slice Profiles bölümünde varsayılan profillerinizi ayarlayın. Bu şekilde, tüm parametreleri belirtmeden basit fiyat teklifi istekleri yapabilirsiniz ve API otomatik olarak yapılandırılmış varsayılanlarınızı kullanacaktır. Gerektiğinde herhangi bir parametreyi istek başına hala geçersiz kılabilirsiniz.
Profil Birleştirmenin Nasıl Çalıştığı
Fiyat teklifi isteği yaptığınızda, API istek parametrelerinizi Dashboard profillerinizle şu öncelikle birleştirir:
- İstek Parametreleri - API isteğinde açıkça sağladığınız değerler en yüksek önceliğe sahiptir
- Kullanıcı Profili - Varsayılan olarak ayarlanmış kullanıcıya özel bir profiliniz varsa, sonraki olarak kullanılır
- Global Profil - Kullanıcı profili yoksa, sistem global varsayılanlara geri 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. Webhooks
Hesabınızda olaylar meydana geldiğinde gerçek zamanlı bildirimler alın:
POST /v2/webhooks- Yeni bir webhook endpoint'i oluşturunGET /v2/webhooks- Tüm webhook'larınızı listeleyinGET /v2/webhooks/{webhook_id}- Webhook detaylarını ve teslimat istatistiklerini alınPUT /v2/webhooks/{webhook_id}- Webhook ayarlarını güncelleyinDELETE /v2/webhooks/{webhook_id}- Bir webhook'u kaldırın
Desteklenen olaylar: quote.completed, quote.failed, file.uploaded. Webhooks, güvenlik doğrulaması için HMAC-SHA256 imzaları içerir.
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, malzeme kullanım trendleri dahil kapsamlı fiyat teklifi istatistiklerini alınGET /v2/analytics/popular- En popüler malzemelerinizi ve yazıcı yapılandırmalarınızı görünGET /v2/analytics/cost-trends- Zaman içindeki maliyet trendlerini 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. 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 bilgisi yanıt başlıklarında yer alır:
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset - Hız sınırlandığında, bir Retry-After başlığı ile 429 Too Many Requests yanıtı alırsınız
- Fiyat teklifleri ve depolama için aylık kotlar abonelik planınıza göre belirlenir
En İyi Uygulama: Hız limiti hatalarını işlerken API'yi bunaltmaktan kaçınmak için üstel geri çekme uygulayın.
10. RESTful, Versiyonlu API
- Tüm endpoint'ler versiyonludur (örn. /v2/)
- Standart HTTP metodlarını kullanır:
- Şema ve dokümantasyon için OpenAPI 3.1.0 standartlarını takip eder
- API değişiklik günlüğü şu adreste mevcuttur: