Concetti chiave: file, preventivi e lavori

1. Autenticazione e Sicurezza

Ogni endpoint richiede l'autenticazione con il tuo token API Quote3D, con un'eccezione: la rotta di caricamento pubblica documentata sotto Gestione file. Per le chiamate esterne usa la rotta base https://api.quote3d.com/v2. Invia il token come Authorization: Bearer YOUR_TOKEN oppure come X-API-Token. Genera i token dal tuo pannello Quote3D e mantienili segreti.

I token possono avere un ambito. Un token ad accesso completo raggiunge ogni endpoint, mentre un token con ambito widget è limitato agli endpoint necessari al widget integrato. Qualsiasi chiamata fuori dall'ambito di un token restituisce 403. Puoi vedere e modificare l'ambito di un token nella pagina Token del pannello.

2. Gestione Account

Gestisci il tuo account, i caricamenti e le statistiche di utilizzo tramite endpoint dedicati:

• GET /v2/user Recupera i dati del tuo account, il piano e i limiti mensili — qui si trovano quotes_used, quotes_limit, storage_used, storage_limit e reset_date
• GET /v2/user/uploads Elenca tutti i file che hai caricato sul tuo account. Questi sono elencati dal più recente al più vecchio.
• GET /v2/quota Recupera i tuoi limiti di frequenza — il limite globale più un dettaglio per endpoint con chiamate residue e orari di reset — insieme ai conteggi delle richieste di oggi, questo mese, quest'anno e di sempre
• GET /v2/usage Ottieni analisi dettagliate sull'utilizzo, incluse statistiche sugli endpoint, utilizzo dei materiali e tendenze basate sul tempo
• GET /v2/config Le tecnologie attive dell’account, le stampanti, i materiali con i loro colori (disponibili o no) e i valori di prezzo predefiniti: tutto ciò che offre il widget. Anche i token widget possono leggerlo.

3. Gestione file

Carica, scarica e gestisci i tuoi file di modelli 3D (formati STL, 3MF, OBJ, STEP):

• GET /v2/file/upload-id — Ottieni un upload_id temporaneo per caricare un nuovo file tramite la route di upload pubblico.
• 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.

• POST /v2/file — Carica un file dal tuo server (richiede autenticazione, utilizzalo quando vuoi caricare dal tuo backend)
• GET /v2/file/{file_id} — Scarica un file utilizzando il suo file_id
• DELETE /v2/file/{file_id} — Elimina un file di cui non hai più bisogno

Il caricamento viene rifiutato se il file non è un modello STL, 3MF, OBJ o STEP valido, oppure se supera il limite di dimensione della piattaforma (50 MB per impostazione predefinita). I file STEP (.step/.stp) vengono tassellati sul server con le stesse impostazioni di OrcaSlicer (deviazione lineare 0,003 mm, deviazione angolare 0,5 rad); tutti i corpi di un assieme vengono uniti e le lunghezze convertite in millimetri. Entrambe le rotte applicano gli stessi controlli.

Come vengono archiviati i tuoi file

I modelli caricati vengono archiviati in modo criptato e non sono mai accessibili pubblicamente — non esiste alcun link che serva direttamente un file archiviato. Il campo file_path nelle risposte è il percorso di download autenticato (GET /v2/file/{file_id}), non una posizione su disco, pertanto va trattato come un endpoint piuttosto che come un URL da condividere. L’eliminazione di un file lo rimuove dall’archiviazione, non solo dai tuoi elenchi.

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:

• 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.
• 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.
• GET /v2/jobs/{job_id} — Controlla lo stato di un lavoro di preventivo asincrono. Restituisce la percentuale di avanzamento e lo stato di completamento.
• GET /v2/quotes — Recupera tutta la tua cronologia dei preventivi con supporto per la paginazione
• GET /v2/quotes/{quote_id} — Ottieni informazioni dettagliate su un preventivo specifico
• DELETE /v2/quotes/{quote_id} — Rimuovi un preventivo dalla tua cronologia

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.

Le tabelle seguenti coprono i parametri che le integrazioni sovrascrivono più spesso. Non sono l'elenco completo — il motore accetta molti altri campi di stampante, materiale e prezzo, e ognuno di essi può essere impostato una volta nei Profili di slicing del pannello invece di essere inviato a ogni richiesta. Configura lì i profili e invia solo ciò che cambia da preventivo a preventivo; l'elenco completo dei campi è nello schema OpenAPI.

Request Validation

I campi numerici di printer_config, material_config e quote_config vengono verificati rispetto ai loro limiti prima che il lavoro venga messo in coda. Un valore fuori intervallo, un numero non finito (NaN, Infinity), un tipo errato oppure un numero negativo dove hanno senso solo lo zero e i valori superiori viene rifiutato con HTTP 400 e un VALIDATION_ERROR che indica il campo esatto. Lo zero continua a essere accettato ovunque abbia significato: una velocità o un'accelerazione di 0 per un dato ruolo significa «usa il valore predefinito della stampante», la stessa convenzione adottata da OrcaSlicer.

• Limiti di temperatura: le temperature del materiale (temperature e bed_temperature, sia inviate nella richiesta sia lette dal Profilo materiale) vengono confrontate con i valori min_hotend_temp / max_hotend_temp e min_bed_temp / max_bed_temp della stampante. Un materiale che richiede più calore di quanto la stampante selezionata possa fornire viene rifiutato anziché preventivato. Solo FDM: le tecnologie a resina e a polvere non hanno ugello né piano riscaldato. Lasciare i limiti della stampante non impostati per saltare il controllo.
• Tecnologie abilitate: se le tecnologie sono state limitate nelle Impostazioni globali, una richiesta di preventivo per una tecnologia disabilitata viene rifiutata. Lasciare l'impostazione vuota per accettare tutte le tecnologie.
• Campi di prezzo del materiale: price_per_gram è il valore che il motore addebita. Quando si salva un Profilo materiale, price_per_kg viene ricalcolato automaticamente a partire da esso (e price_per_gram viene derivato da price_per_kg quando viene fornito solo il prezzo al chilogrammo), così i due valori non possono mai discordare.

Parametri Principali

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.

printer_config

Parametri di configurazione della stampante. Tutti i campi sono opzionali e utilizzeranno i valori predefiniti del tuo Profilo Stampante se non forniti.

material_config

Parametri di configurazione del materiale. Tutti i campi sono opzionali e utilizzeranno i valori predefiniti del tuo Profilo Materiale se non forniti.

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'.

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, rapporto di flusso, impostazioni di retrazione, prezzi) per ogni materiale che utilizzi. L'API utilizzerà automaticamente il profilo del materiale corrispondente al filament_type 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.

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à:

1. Parametri di Richiesta - I valori che fornisci esplicitamente nella richiesta API hanno la priorità più alta
2. Profilo Utente - Se hai un profilo specifico per l'utente impostato come predefinito, viene utilizzato successivamente
3. 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 webhook
• GET /v2/webhooks - Elenca tutti i tuoi webhook
• GET /v2/webhooks/{webhook_id} - Ottieni i dettagli del webhook e le statistiche di consegna
• PUT /v2/webhooks/{webhook_id} - Aggiorna le impostazioni del webhook
• DELETE /v2/webhooks/{webhook_id} - Rimuovi un webhook
• POST /v2/webhooks/{webhook_id}/deliveries/{delivery_id}/resend - Invia di nuovo una consegna passata, per esempio dopo aver sistemato il tuo endpoint

Eventi supportati: quote.completed, quote.failed, file.uploaded, file.deleted, job.status_changed, widget.added_to_cart, usage.alert. I webhook includono firme HMAC-SHA256 per la verifica della sicurezza.

Riferimento webhook: struttura del payload, verifica della firma, tentativi e riconsegna

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 materiali
• GET /v2/analytics/popular - Visualizza i tuoi materiali e le configurazioni di stampante più popolari
• GET /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. Catalogo e scorte

Gestisci stampanti, materiali, colori, scorte per colore, prezzi e tecnologie propri dell’account con un token server. Il widget legge lo stesso catalogo, quindi una modifica arriva subito al modulo di preventivo. I token widget vengono rifiutati e queste chiamate non contano nella quota mensile di richieste:

• GET /v2/store/catalog - Tutto ciò che offre l’account, con lo stato di preparazione per tecnologia e i colori in esaurimento
• GET /v2/store/catalog/schema - I moduli stampante, materiale e prezzi della dashboard, con limiti, unità e testi di aiuto nella lingua richiesta
• POST /v2/store/catalog/adopt - Copia stampanti e materiali globali nell’account, con i colori, il prezzo e le scorte iniziali scelti
• POST /v2/store/catalog/materials - Crea un materiale, anche partendo da uno globale
• GET · PATCH · DELETE /v2/store/catalog/materials/{id} - Leggi, modifica o elimina un materiale, incluse le impostazioni delle scorte
• PUT /v2/store/catalog/materials/{id}/colors - Sostituisci l’elenco dei colori di un materiale; le scorte dei colori esistenti restano
• GET · PATCH · DELETE /v2/store/catalog/printers/{id} - Leggi, modifica o elimina una stampante
• GET · PATCH · DELETE /v2/store/catalog/pricing - Leggi, modifica o reimposta i prezzi; cambiare valuta cambia quella dell’account senza convertire gli importi
• GET · PUT /v2/store/catalog/technologies - Quali tecnologie consente il piano e quali sono attive
• GET · POST /v2/store/stock/movements - Registra un carico, un inventario o uno scarto ed elenca lo storico delle scorte
• POST /v2/store/stock/orders - Scala, restituisci o verifica il materiale di un ordine pagato, al massimo una volta per preventivo

I body PATCH contengono values e updated_at. values usa gli stessi nomi di campo snake_case dell’elenco del catalogo (un nome che il modulo non ha viene rifiutato con 400); se il profilo è cambiato dopo la tua lettura, la chiamata risponde 409 con error_key stale.

10. 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, X-RateLimit-Window
• Quando si raggiunge il limite di velocità, si riceverà una risposta 429 Too Many Requests con un'intestazione Retry-After
• Il tuo piano stabilisce una quota di preventivi, che si azzera a ogni periodo di fatturazione, e una quota di spazio, che non si azzera mai e si libera solo eliminando i file
• I limiti sono configurabili per installazione, quindi leggi i valori correnti invece di scriverli nel codice. Li riportano sia gli header di risposta sopra sia questo endpoint: GET /v2/quota

11. Risposte ed errori

Le risposte riuscite hanno due forme. Le chiamate di preventivo, job, dettaglio del preventivo salvato, webhook, analisi, utilizzo, quota e configurazione racchiudono il contenuto in success: true con il risultato in data. Le chiamate di file, ID di caricamento, utente, caricamenti, elenco preventivi, stampabilità e Catalogo e scorte restituiscono i loro campi al livello superiore. Il riferimento API mostra lo schema esatto di ogni chiamata. I download di file e le esportazioni CSV restituiscono il contenuto grezzo del file.

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

Paginazione e ordinamento

Gli endpoint di elenco come /v2/quotes e /v2/user/uploads sono paginati con i parametri limit e offset (50 risultati predefiniti, massimo 100). Accanto ai risultati restituiscono un oggetto pagination con total, limit, offset, has_more, page e total_pages: preferisci quindi has_more invece di ricalcolare da solo la fine dell'elenco. L'ordinamento usa un unico parametro ripetibile nella forma field:direction, ad esempio ?sort=created_at:desc&sort=total_price:asc; i caricamenti partono dai più recenti.

Risposte di errore

Ogni errore ha la stessa forma: un elenco detail che indica il parametro o il campo (loc, msg, code), un error_code come AUTH_001, un error_summary e, quando serve, recovery_suggestions e documentation_url. Decidi in base allo stato HTTP e all’error_code, non al testo, che può cambiare.

I preventivi asincroni sono diversi: la messa in coda riesce con un 202, e un calcolo che fallisce successivamente emerge come stato failed con un messaggio di errore sull'endpoint del lavoro, non come errore HTTP. Controlla sempre lo stato del lavoro, non solo il codice ottenuto all'avvio.

12. API RESTful e versionata

• Tutti gli endpoint sono versionati (es. /v2/)
• Utilizza i metodi HTTP standard: GET, POST, PUT, DELETE
• Descritta da uno schema OpenAPI 3.0.3 che puoi importare nei tuoi strumenti
• Le modifiche incompatibili e le aggiunte sono registrate nel changelog dell'API