Concetti Fondamentali
Questa pagina introduce le idee e i modelli fondamentali che alimentano la piattaforma. Comprendere questi concetti ti aiuterà a sfruttare al meglio l'API e a creare integrazioni robuste per i workflow di stampa 3D.
Percorso base API
Per le chiamate API esterne, invia le richieste direttamente a https://api.quote3d.com/v2/... (ad esempio, GET https://api.quote3d.com/v2/user).
Nel tuo software, imposta https://api.quote3d.com come host API/URL base e chiama i percorsi v2 come /v2/user, /v2/file e /v2/quotes.
1. Autenticazione e Sicurezza
Tutti gli endpoint API richiedono l'autenticazione tramite il tuo token API Quote3D. Per le chiamate esterne, utilizza la route di base https://api.quote3d.com/v2. Inviatelo come Authorization: Bearer <token> o X-API-Token. Genera i token dalla tua dashboard Quote3D e mantienili segreti.
Promemoria: Mantieni i tuoi token API al sicuro. Non condividerli pubblicamente né aggiungerli al controllo di versione.
2. Gestione Account
Gestisci il tuo account, i caricamenti e le statistiche di utilizzo tramite endpoint dedicati:
GET /v2/userRecupera i dettagli del tuo accountGET /v2/user/uploadsElenca tutti i file che hai caricato sul tuo account. Questi sono elencati dal più recente al più vecchio.GET /v2/quotaOttieni i tuoi limiti di quota correnti e l'utilizzo per preventivi e archiviazioneGET /v2/usageOttieni analisi dettagliate sull'utilizzo, incluse statistiche sugli endpoint, utilizzo dei materiali e tendenze basate sul tempo
3. Gestione file
Carica, scarica e gestisci i tuoi file di modelli 3D (formati STL, 3MF, OBJ):
- Ottieni un upload_id temporaneo per caricare un nuovo file tramite la route di upload pubblico.:
GET /v2/file/upload-id- Ottieni un upload_id temporaneo per caricare un nuovo file tramite la route di upload pubblico. - Questa route NON richiede autenticazione. Utilizzala sul tuo client per caricare direttamente i file nel nostro storage.:
POST /v2/file/public/{upload_id}- Questa route NON richiede autenticazione. Utilizzala sul tuo client per caricare direttamente i file nel nostro storage.L'utilizzo della route di Upload Pubblico ti permette di evitare di instradare file di grandi dimensioni attraverso il tuo server backend. Questo previene l'esposizione del tuo token API e riduce il carico del server.
- Carica un file dal tuo server (richiede autenticazione, utilizzalo quando vuoi caricare dal tuo backend):
POST /v2/file— Carica un file dal tuo server (richiede autenticazione, utilizzalo quando vuoi caricare dal tuo backend) - Scarica un file utilizzando il suo file_id:
GET /v2/file/{file_id}— Scarica un file utilizzando il suo file_id - Elimina un file di cui non hai più bisogno:
DELETE /v2/file/{file_id}— Elimina un file di cui non hai più bisogno
4. Informazioni sulla parte e analisi tecnica
Verifica se i tuoi modelli sono stampabili, ottieni le dimensioni della parte e metriche tecniche avanzate:
POST /v2/printability/{file_id}Analisi Istantanea – Verifica misure, volume, area superficiale e integrità geometrica (bordi aperti/non-manifold) prima di generare un preventivo.
Quote3D va oltre i semplici controlli dimensionali; analizza l'integrità manifold del modello e valuta il rischio di adesione al piano, critico per la stampa 3D. Queste metriche sono fornite sia nelle risposte Printability che Quote.
5. Operazioni di Preventivo
Genera preventivi istantanei per le tue stampe 3D e gestisci la cronologia dei preventivi:
- Avvia il calcolo asincrono del preventivo per un modello 3D. Restituisce un ID lavoro; utilizza l'endpoint jobs per recuperare il risultato completato.:
POST /v2/file/quote/{file_id}— Avvia il calcolo asincrono del preventivo per un modello 3D. Restituisce un ID lavoro; utilizza l'endpoint jobs per recuperare il risultato completato. - Endpoint asincrono alternativo per il preventivo. Restituisce un ID lavoro che puoi utilizzare per controllare lo stato e recuperare il risultato completato.:
POST /v2/file/quote/{file_id}/async— Endpoint asincrono alternativo per il preventivo. Restituisce un ID lavoro che puoi utilizzare per controllare lo stato e recuperare il risultato completato. - Controlla lo stato di un lavoro di preventivo asincrono. Restituisce la percentuale di avanzamento e lo stato di completamento.:
GET /v2/jobs/{job_id}— Controlla lo stato di un lavoro di preventivo asincrono. Restituisce la percentuale di avanzamento e lo stato di completamento. - Recupera tutta la tua cronologia dei preventivi con supporto per la paginazione:
GET /v2/quotes— Recupera tutta la tua cronologia dei preventivi con supporto per la paginazione - Ottieni informazioni dettagliate su un preventivo specifico:
GET /v2/quotes/{quote_id}— Ottieni informazioni dettagliate su un preventivo specifico - Rimuovi un preventivo dalla tua cronologia:
DELETE /v2/quotes/{quote_id}— Rimuovi un preventivo dalla tua cronologia
Workflow asincrono: POST /v2/file/quote/{file_id} restituisce innanzitutto un ID lavoro. Utilizzare GET /v2/jobs/{job_id} per il risultato compatto completato e GET /v2/quotes/{quote_id} per il payload di preventivo dettagliato memorizzato quando disponibile.
Parametri di Richiesta Preventivo
Quando generi un preventivo, puoi fornire configurazioni personalizzate nel corpo della richiesta. Qualsiasi parametro che non specifichi verrà automaticamente preso dalle impostazioni del tuo Profilo di Slicing nel Dashboard. Questo ti consente di sovrascrivere impostazioni specifiche per ogni preventivo mantenendo le impostazioni predefinite per gli altri.
Importante: Se non fornisci un parametro nella tua richiesta, l'API utilizzerà il valore dal tuo Profilo di Slicing nel Dashboard (Profilo Stampante, Profilo Materiale o Impostazioni Globali). Assicurati di impostare i tuoi profili predefiniti nel Dashboard per preventivi coerenti. Puoi anche configurare tutti i tuoi parametri in un Profilo Stampante specifico nel Dashboard e semplicemente passare il suo 'printer_id' nella tua richiesta per applicare quelle impostazioni istantaneamente senza passarle individualmente.
Precedenza della configurazione: I valori inviati nella richiesta API V2 sovrascrivono i valori del profilo utente selezionato; qualsiasi campo ancora mancante ricade quindi sui profili predefiniti utente/globali.
Parametri Principali
| Parametro | Tipo | Descrizione |
|---|---|---|
| printer_id | string | Opzionale. ID di una stampante specifica da utilizzare invece della stampante predefinita. |
| quantity | number | Opzionale. Il numero totale di copie da produrre (Predefinito: 1). |
Logica di Quantità e Produzione in Batch
Il nostro sistema utilizza un algoritmo di impacchettamento avanzato basato sulla 'quantity' specificata:
- Tecnologia FDM: Le parti vengono posizionate fianco a fianco sul piano di stampa (assi X e Y) secondo lo spazio disponibile.
- Tecnologia SLA: Le parti vengono posizionate fianco a fianco nella vasca di resina (assi X e Y).
- Tecnologia SLS: Le parti possono essere impilate su tutti gli assi (X, Y e Z) per utilizzare appieno la capacità del letto di polvere.
Grazie a questo imballaggio ottimizzato, se più parti possono entrare in un singolo batch, i costi fissi generali come il preriscaldamento, il raffreddamento e i cambi di strato vengono applicati solo per ogni batch richiesto. Questo garantisce prezzi realistici ed economici per ordini di grandi volumi.
printer_config
Parametri di configurazione della stampante. Tutti i campi sono opzionali e utilizzeranno i valori predefiniti del tuo Profilo Stampante se non forniti.
| Parametro | Tipo | Descrizione |
|---|---|---|
| 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 |
| SPECIFICO PER SLA | ||
| sla_exposure_time | number | SLA: Tempo di esposizione per livello (secondi) |
| sla_bottom_exposure_time | number | SLA: Tempo di esposizione di base (secondi) |
| sla_bottom_layer_count | number | SLA: Numero di livelli inferiori |
| sla_lift_distance | number | SLA: Distanza di sollevamento (mm) |
| sla_lift_speed | number | SLA: Velocità di sollevamento (mm/s) |
| sla_retract_speed | number | SLA: Velocità di retrazione (mm/s) |
| sla_cleaning_cost | number | SLA: Costo fisso di pulizia per stampa (IPA, materiali di consumo) |
| SPECIFICO PER SLS | ||
| sls_laser_speed | number | SLS: Velocità del laser (mm/s) |
| sls_hatch_spacing | number | SLS: Spaziatura tra le scansioni (mm) |
| sls_layer_thickness | number | SLS: Spessore dello strato (mm) |
| sls_layer_recoat_time | number | SLS: Tempo di ricopertura dello strato (secondi) |
| sls_preheat_time | number | SLS: Tempo di preriscaldamento (secondi) |
| sls_cooling_time | number | SLS: Tempo di raffreddamento (secondi) |
| 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
Parametri di configurazione del materiale. Tutti i campi sono opzionali e utilizzeranno i valori predefiniti del tuo Profilo Materiale se non forniti.
Integrazione Profilo Materiale: Il parametro filament_type deve corrispondere a un nome del materiale dal tuo Profilo Materiale nel Dashboard. Quando specifichi un filament_type (ad esempio, "PLA", "ABS", "PETG"), l'API carica automaticamente tutte le proprietà da quel Profilo Materiale, inclusa la densità, le temperature, le impostazioni di retrazione e i prezzi.
Precisione dei Prezzi: Per calcoli dei costi accurati, assicurati di impostare sia price_per_kg che price_per_gram nel tuo Profilo Materiale. L'API utilizza questi valori per calcolare i costi del materiale in base al peso effettivo del filamento utilizzato nella stampa. Se questi valori non sono impostati nel tuo profilo, puoi sovrascriverli nella richiesta API.
Esempio: Se hai un profilo materiale "PLA" nel tuo Dashboard con price_per_kg: 20.0 e price_per_gram: 0.02, puoi semplicemente inviare {"filament_type": "PLA"} nella tua richiesta e tutti i prezzi verranno calcolati automaticamente.
| Parametro | Tipo | Descrizione |
|---|---|---|
| filament_type | string | Filament type (PLA, ABS, PETG, etc.) |
| color | string | Opzionale: Nome del colore (es. 'Bianco', 'Nero', '#FFFFFF'). Nota: per le tecnologie SLA/SLS, il colore viene applicato solo se 'post_processing' è impostato su 'painted'. |
| 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
Parametri di configurazione del preventivo. Tutti i campi sono opzionali e utilizzeranno i valori delle Impostazioni Globali predefiniti se non forniti. La valuta predefinita è quella del tuo dashboard, ad esempio 'USD', 'TRY', 'EUR'.
| Parametro | Tipo | Descrizione |
|---|---|---|
| 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 | Specifico per SLA/Resina: 'solid', '2mm' o '3mm' (Impostazione predefinita: 'solid') |
| post_processing | string | Specifico per SLA/SLS: 'standard', 'sanding', 'painting' o 'painted' (Impostazione predefinita: '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). |
Suggerimento: I preventivi vengono salvati automaticamente nel tuo account. Puoi accedervi in qualsiasi momento tramite gli endpoint della cronologia dei preventivi.
6. Profili Stampante e Preventivo
Configura le impostazioni della stampante e i prezzi per ottenere preventivi accurati. Puoi gestire i tuoi profili predefiniti nella sezione Profili di slicing del Dashboard, che verranno utilizzati automaticamente quando non specifichi i parametri nelle richieste API.
Tipi di Profilo
- Profilo Stampante - Configura le impostazioni della tua stampante (dimensioni del piano di stampa, diametro dell'ugello, velocità di stampa, altezza dello strato, accelerazione, jerk, temperature, ecc.) per corrispondere alla tua stampante reale. Imposta questo come profilo predefinito nel Dashboard e verrà utilizzato per tutte le richieste di preventivo a meno che tu non sovrascriva parametri specifici.
- Profilo Materiale - Imposta le proprietà del materiale (tipo di filamento, densità, diametro, temperature, velocità della ventola, impostazioni di retrazione, prezzi) per ogni materiale che utilizzi. L'API utilizzerà automaticamente il profilo del materiale corrispondente al tipo di filamento che specifichi nella richiesta.
- Impostazioni Globali - Configura le impostazioni globali del preventivo come l'aliquota fiscale, le commissioni fisse, i costi energetici e la valuta predefinita. Queste impostazioni si applicano a tutti i preventivi a meno che non vengano sovrascritte nella richiesta.
Best Practice: Configura i tuoi profili predefiniti nella sezione Profili di Slicing del Dashboard. In questo modo, puoi effettuare richieste di preventivo semplici senza specificare tutti i parametri e l'API utilizzerà automaticamente i tuoi valori predefiniti configurati. Puoi comunque sovrascrivere qualsiasi parametro per ogni richiesta quando necessario.
Come Funziona l'Unione dei Profili
Quando effettui una richiesta di preventivo, l'API unisce i tuoi parametri di richiesta con i profili del Dashboard utilizzando questa priorità:
- Parametri di Richiesta - I valori che fornisci esplicitamente nella richiesta API hanno la priorità più alta
- Profilo Utente - Se hai un profilo specifico per l'utente impostato come predefinito, viene utilizzato successivamente
- Profilo Globale - Se non esiste un profilo utente, il sistema torna ai valori predefiniti globali
Ciò significa che puoi sovrascrivere solo i parametri di cui hai bisogno (ad esempio, solo layer_height o fill_density) mantenendo tutte le altre impostazioni dai tuoi profili del Dashboard.
7. Webhook
Ricevi notifiche in tempo reale quando si verificano eventi nel tuo account:
POST /v2/webhooks- Crea un nuovo endpoint webhookGET /v2/webhooks- Elenca tutti i tuoi webhookGET /v2/webhooks/{webhook_id}- Ottieni i dettagli del webhook e le statistiche di consegnaPUT /v2/webhooks/{webhook_id}- Aggiorna le impostazioni del webhookDELETE /v2/webhooks/{webhook_id}- Rimuovi un webhook
Eventi supportati: quote.completed, quote.failed, job.status_changed, widget.added_to_cart, file.uploaded. I webhook includono firme HMAC-SHA256 per la verifica della sicurezza.
8. Analisi e Report
Ottieni informazioni sull'utilizzo della tua API e sulle statistiche dei preventivi:
GET /v2/analytics/quotes- Ottieni statistiche complete sui preventivi, inclusi il numero totale di preventivi, i prezzi medi e le tendenze nell'utilizzo dei materialiGET /v2/analytics/popular- Visualizza i tuoi materiali e le configurazioni di stampante più popolariGET /v2/analytics/cost-trends- Analizza le tendenze dei costi nel tempo (raggruppamento giornaliero, settimanale o mensile)GET /v2/analytics/export- Esporta i tuoi preventivi e i dati di utilizzo come CSV o JSON
9. Limitazione della frequenza e quote
Quote3D utilizza la limitazione della velocità per garantire un utilizzo equo e la stabilità del sistema:
- I limiti di velocità sono applicati per token API e variano a seconda dell'endpoint
- Le informazioni sulla limitazione della frequenza sono incluse nelle intestazioni della risposta:
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset - Quando si raggiunge il limite di velocità, si riceverà una risposta 429 Too Many Requests con un'intestazione Retry-After
- Le quote mensili per preventivi e spazio di archiviazione si basano sul piano di abbonamento
Best Practice: Implementare un backoff esponenziale quando si gestiscono errori di limitazione della velocità per evitare di sovraccaricare l'API.
10. API RESTful e Versionata
- Tutti gli endpoint sono versionati (es. /v2/)
- Utilizza i metodi HTTP standard:
- Segue gli standard OpenAPI 3.1.0 per schema e documentazione
- Il changelog dell'API è disponibile all'indirizzo: