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.
API Taban Yolu
Harici API çağrıları için istekleri doğrudan https://api.quote3d.com/v2/... adresine gönderin (örneğin, GET https://api.quote3d.com/v2/user).
Yazılımınızda https://api.quote3d.com adresini API ana bilgisayarı/temel URL olarak ayarlayın ve /v2/user, /v2/file ve /v2/quotes gibi v2 yollarını çağırın.
1. Kimlik Doğrulama ve Güvenlik
Tüm API uç noktaları, Quote3D API token'ınızı kullanarak kimlik doğrulaması gerektirir. Harici çağrılar için https://api.quote3d.com/v2 temel rotasını kullanın. Bunu ya Authorization: Bearer <token> ya da X-API-Token olarak gönderin. Token'ları Quote3D panelinizden oluşturun ve gizli tutun.
Hatırlatma: API token'larınızı güvende tutun. Asla herkese açık olarak paylaşmayın veya sürüm kontrolüne kaydetmeyin.
2. Hesap Yönetimi
Hesabınızı, yüklemelerinizi ve kullanım istatistiklerinizi özel uç noktalar aracılığıyla yönetin:
GET /v2/userHesap bilgilerinizi 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. 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ını kullanın.:
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. - Bu rota kimlik doğrulaması gerektirmez. Dosyaları doğrudan depolama alanımı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 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.
- Sunucu tarafınızdan bir dosya yükleyin (kimlik doğrulama gerektirir, backend'den yüklemek istediğinizde kullanın):
POST /v2/file— Sunucu tarafınızdan bir dosya yükleyin (kimlik doğrulama 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
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:
- 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}— 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. - 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.:
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. - 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
Asenkron akış: POST /v2/file/quote/{file_id} önce bir iş kimliği döndürür. Tamamlanmış sonuç için GET /v2/jobs/{job_id} kullanın; mevcut olduğunda ayrıntılı ve kaydedilmiş teklif sonucu için ise GET /v2/quotes/{quote_id} endpoint'ini kullanı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. Ayrıca tüm parametrelerinizi Dashboard'daki belirli bir Yazıcı Profilinde ayarlayabilir ve sadece yazdırmak istediğiniz yazıcının 'printer_id' parametresini göndererek, ayarları tek tek girmeye gerek kalmadan kolayca hesaplama yaptırabilirsiniz.
Yapılandırma önceliği: V2 API isteğinde gönderilen değerler seçili kullanıcı profili değerlerini ezer; hâlâ eksik kalan alanlar ise kullanıcı/global varsayılan profillere düşer.
Kök Parametreler
| Parametre | Tür | Açıklama |
|---|---|---|
| printer_id | string | İsteğe bağlı. Varsayılan yazıcı yerine kullanılacak belirli bir yazıcının kimliği (ID). |
| quantity | number | İsteğe bağlı. Üretilmek istenen toplam parça adedi (Varsayılan: 1). |
Ü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.
Bu optimize edilmiş dizilim sayesinde, birden fazla parça tek bir operasyonda (batch) üretilebiliyorsa, ön ısıtma, soğuma veya katman değiştirme gibi sabit zaman/maliyet maliyetleri yalnızca gerekli operasyon (batch) sayısı kadar hesaplanır ve kullanıcıya çok daha gerçekçi ve ekonomik bir fiyat sunulur.
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.
| Parametre | Tür | Açıklama |
|---|---|---|
| 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 |
| SLA'ya özgü | ||
| sla_exposure_time | number | SLA: Katman başına ışıklama süresi (saniye) |
| sla_bottom_exposure_time | number | SLA: Alt katman ışıklama süresi (saniye) |
| sla_bottom_layer_count | number | SLA: Alt katman sayısı |
| sla_lift_distance | number | SLA: Kaldırma mesafesi (mm) |
| sla_lift_speed | number | SLA: Kaldırma hızı (mm/s) |
| sla_retract_speed | number | SLA: Geri çekme hızı (mm/s) |
| sla_cleaning_cost | number | SLA: Baskı başına sabit temizlik maliyeti (IPA, sarf malzemeleri) |
| SLS ÖZELLİKLERİ | ||
| sls_laser_speed | number | SLS: Lazer hızı (mm/s) |
| sls_hatch_spacing | number | SLS: Tarama aralığı (mm) |
| sls_layer_thickness | number | SLS: Katman kalınlığı (mm) |
| sls_layer_recoat_time | number | SLS: Toz serme süresi (saniye) |
| sls_preheat_time | number | SLS: Ön ısıtma süresi (saniye) |
| sls_cooling_time | number | SLS: Soğuma süresi (saniye) |
| sla_light_off_delay | number | SLA: Light-off delay for each layer (seconds). |
| sla_transition_layer_count | number | SLA: Number of transition layers. |
| sla_drain_holes | array | SLA: Drainage holes configuration to prevent suction cups. |
| sls_bb_multiplier | number | SLS Bounding Box cost multiplier. |
| max_volumetric_flow | number | Maximum volumetric flow rate in mm³/s. |
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.
| Parametre | Tür | Açıklama |
|---|---|---|
| filament_type | string | Filament type (PLA, ABS, PETG, etc.) |
| color | string | Renk adı (örn. 'Beyaz', 'Siyah', '#FFFFFF'). Not: SLA/SLS teknolojileri için renk, yalnızca 'post_processing' değeri 'painted' olarak ayarlandığında uygulanır. |
| density | number | Material density (g/cm³) |
| diameter | number | Filament diameter (mm) |
| powder_bulk_density | number | SLS: Bulk density of loose powder in g/cm³. Used for reusable powder and refresh calculations. |
| 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 |
| sls_refresh_factor | number | SLS Powder Refresh cost factor (e.g. 1.2). |
| max_volumetric_flow | number | Material specific volumetric flow limit in mm³/s. |
| min_layer_time | number | Minimum layer time in seconds for cooling. |
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.
| Parametre | Tür | Açıklama |
|---|---|---|
| currency | string | Currency code (USD, TRY, EUR, GBP, JPY, CNY, RUB). Defaults to your dashboard preference. |
| tax_rate | number | Tax rate percentage (0-100) |
| fixed_fee | number | Fixed fee per quote |
| energy_cost_per_kwh | number | Energy cost per kWh |
| hollowing | string | SLA/Reçineye özel: 'solid' (tam dolu), '2mm' veya '3mm' (Varsayılan: 'solid') |
| post_processing | string | SLA/SLS'ye özel: 'standard', 'sanding', 'painting' veya 'painted' (Varsayılan: 'standard') |
| enable_batch_system | boolean | Enable/disable batch calculation system (default: true) |
| material_wastage_factor | number | Factor for calculating material wastage (e.g. 1.10 for 10% wastage). |
İpucu: Fiyat teklifleri otomatik olarak hesabınıza kaydedilir. Bunlara fiyat teklifi geçmişi API uç noktaları 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. 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.
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 belirttiğiniz değerler en yüksek önceliğe sahiptir.
- Kullanıcı Profili - Eğer varsayılan olarak ayarlanmış kullanıcıya özel bir profiliniz varsa, sonraki olarak kullanılır.
- 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şturunGET /v2/webhooks- Tüm web kancalarınızı listeleyinGET /v2/webhooks/{webhook_id}- Web kancası ayrıntılarını ve teslimat istatistiklerini alınPUT /v2/webhooks/{webhook_id}- Web kancası ayarlarını güncelleyinDELETE /v2/webhooks/{webhook_id}- Bir web kancasını kaldırın
Desteklenen olaylar şunları içerir: quote.completed, quote.failed, job.status_changed, widget.added_to_cart, file.uploaded. Web kancaları, 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 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. 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 - Hız sınırlandığında, Retry-After başlığı ile birlikte 429 Too Many Requests yanıtı alırsınız.
- Aylık fiyat teklifi ve depolama kotası 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 yöntemleri kullanılır:
- Şema ve dokümantasyon için OpenAPI 3.1.0 standartlarını takip eder
- API değişiklik günlüğü şu adreste mevcuttur: