Kernkonzepte: Dateien, Angebote und Jobs

1. Authentifizierung & Sicherheit

Jeder Endpunkt erfordert eine Authentifizierung mit Ihrem Quote3D-API-Token, mit einer Ausnahme: der öffentlichen Upload-Route, die unter Dateiverwaltung dokumentiert ist. Verwenden Sie für externe Aufrufe die Basisroute https://api.quote3d.com/v2. Senden Sie das Token entweder als Authorization: Bearer YOUR_TOKEN oder als X-API-Token. Erstellen Sie Token in Ihrem Quote3D-Dashboard und halten Sie sie geheim.

Token können Scopes zugewiesen werden. Ein Token mit vollem Zugriff erreicht jeden Endpunkt, während ein Widget-Scoped-Token auf die Endpunkte beschränkt ist, die das eingebettete Widget benötigt. Aufrufe außerhalb des Scopes eines Tokens geben 403 zurück. Sie können den Scope eines Tokens auf der Seite „Tokens“ in Ihrem Dashboard einsehen und ändern.

2. Kontoverwaltung

Verwalten Sie Ihr Konto, Uploads und Nutzungsstatistiken über dedizierte Endpunkte:

• GET /v2/user Ruft Ihre Kontodaten, Ihren Tarif und Ihre monatlichen Kontingente ab — hier liegen quotes_used, quotes_limit, storage_used, storage_limit und reset_date
• GET /v2/user/uploads Zeigen Sie alle in Ihr Konto hochgeladenen Dateien an. Diese werden vom neuesten zum ältesten sortiert.
• GET /v2/quota Ruft Ihre Ratenbegrenzungen ab — das globale Limit plus eine Aufschlüsselung je Endpunkt mit verbleibenden Aufrufen und Zurücksetzungszeiten — zusammen mit Ihren Anfragezahlen für heute, diesen Monat, dieses Jahr und insgesamt
• GET /v2/usage Erhalten Sie detaillierte Nutzungsanalysen, einschließlich Endpunktstatistiken, Materialverbrauch und zeitbasierten Trends
• GET /v2/config Die aktivierten Technologien, Drucker, Materialien mit ihren Farben (vorrätig oder nicht) und Preisvorgaben des Kontos, also alles, was das Widget anbietet. Auch Widget-Tokens dürfen es lesen.

3. Dateiverwaltung

Laden Sie Ihre 3D-Modelldateien hoch, laden Sie sie herunter und verwalten Sie sie (STL, 3MF, OBJ, STEP-Formate):

• GET /v2/file/upload-id — Erhalten Sie eine temporäre upload_id, um eine neue Datei über den öffentlichen Upload-Pfad hochzuladen.
• POST /v2/file/public/{upload_id} — Dieser Pfad erfordert KEINE Authentifizierung. Verwenden Sie diesen auf Ihrer Client-Seite, um Dateien direkt in unseren Speicher hochzuladen.

  Die Verwendung des öffentlichen Upload-Pfads ermöglicht es Ihnen, das Routing großer Dateien über Ihren Backend-Server zu vermeiden. Dies verhindert die Offenlegung Ihres API-Tokens und reduziert die Serverlast.

• POST /v2/file — Laden Sie eine Datei von Ihrer Serverseite hoch (erfordert Authentifizierung, verwenden Sie diese, wenn Sie von Ihrem Backend hochladen möchten)
• GET /v2/file/{file_id} — Laden Sie eine Datei unter Verwendung ihrer file_id herunter
• DELETE /v2/file/{file_id} — Löschen Sie eine Datei, die Sie nicht mehr benötigen

Der Upload wird abgelehnt, wenn die Datei kein gültiges STL-, 3MF-, OBJ- oder STEP-Modell ist oder wenn sie das Dateigrößenlimit der Plattform überschreitet (standardmäßig 50 MB). STEP-Dateien (.step/.stp) werden auf dem Server mit denselben Einstellungen wie in OrcaSlicer trianguliert (lineare Abweichung 0,003 mm, Winkelabweichung 0,5 rad); alle Körper einer Baugruppe werden zusammengeführt und Längen in Millimeter umgerechnet. Beide Upload-Routen wenden dieselben Prüfungen an.

Wie Ihre Dateien gespeichert werden

Hochgeladene Modelle werden verschlüsselt gespeichert und sind niemals öffentlich erreichbar — es gibt keinen Link, der eine gespeicherte Datei direkt bereitstellt. Das Feld file_path in den Antworten ist der authentifizierte Download-Pfad (GET /v2/file/{file_id}), kein Speicherort auf der Festplatte; behandeln Sie ihn daher als Endpunkt und nicht als eine URL, die Sie teilen können. Das Löschen einer Datei entfernt sie aus dem Speicher, nicht nur aus Ihren Einträgen.

4. Teileinformationen & Technische Analyse

Überprüfen Sie, ob Ihre Modelle druckbar sind, erhalten Sie Teilabmessungen und erweiterte technische Metriken:

• POST /v2/printability/{file_id} Sofort-Analyse – Überprüfen Sie Maße, Volumen, Oberfläche und geometrische Integrität (offene Kanten/Non-Manifold) vor der Angebotserstellung.

Quote3D geht über einfache Maßkontrollen hinaus; es analysiert die Manifold-Integrität des Modells und bewertet das für den 3D-Druck kritische Haftungsrisiko. Diese Metriken sind sowohl in Printability- als auch in Quote-Antworten enthalten.

5. Angebotsoperationen

Erstellen Sie sofortige Angebote für Ihre 3D-Drucke und verwalten Sie den Angebotsverlauf:

• POST /v2/file/quote/{file_id} — Starten Sie die asynchrone Angebotsberechnung für ein 3D-Modell. Es wird eine Job-ID zurückgegeben; verwenden Sie den Jobs-Endpunkt, um das vollständige Ergebnis abzurufen.
• POST /v2/file/quote/{file_id}/async — Alternativer asynchroner Angebotsendpunkt. Gibt eine Job-ID zurück, die Sie verwenden können, um den Status zu überprüfen und das vollständige Ergebnis abzurufen.
• GET /v2/jobs/{job_id} — Überprüfen Sie den Status eines asynchronen Angebotsauftrags. Gibt den Fortschritt in Prozent und den Abschlussstatus zurück.
• GET /v2/quotes — Rufen Sie Ihren gesamten Angebotsverlauf mit Unterstützung für Paginierung ab.
• GET /v2/quotes/{quote_id} — Rufen Sie detaillierte Informationen zu einem bestimmten Angebot ab.
• DELETE /v2/quotes/{quote_id} — Entfernen Sie ein Angebot aus Ihrem Verlauf

Anfrageparameter für Angebote

Beim Erstellen eines Angebots können Sie eine benutzerdefinierte Konfiguration im Anfragekörper angeben. Alle Parameter, die Sie nicht angeben, werden automatisch aus Ihren Slice-Profileinstellungen im Dashboard übernommen. Dies ermöglicht es Ihnen, bestimmte Einstellungen pro Angebot zu überschreiben, während Sie die Standardeinstellungen für andere beibehalten.

Die untenstehenden Tabellen decken die Parameter ab, die am häufigsten durch Integrationen überschrieben werden. Dies ist nicht die vollständige Liste – die Angebots-Engine akzeptiert viele weitere Drucker-, Material- und Preisfelder, und jedes einzelne davon kann einmalig in Ihren Dashboard Slice-Profilen festgelegt werden, anstatt bei jeder Anfrage gesendet zu werden. Konfigurieren Sie Ihre Profile dort und senden Sie nur das, was pro Angebot variiert; die vollständige Feldliste befindet sich im OpenAPI-Schema.

Request Validation

Numerische Felder in printer_config, material_config und quote_config werden vor dem Einreihen des Auftrags auf ihre Grenzwerte geprüft. Ein Wert außerhalb seines Bereichs, eine nicht endliche Zahl (NaN, Infinity), ein falscher Typ oder eine negative Zahl dort, wo nur null und höher sinnvoll ist, wird mit HTTP 400 und einem VALIDATION_ERROR abgelehnt, der das genaue Feld benennt. Null wird weiterhin überall dort akzeptiert, wo sie sinnvoll ist – eine rollenbezogene Geschwindigkeit oder Beschleunigung von 0 bedeutet „Druckerstandard verwenden“, dieselbe Konvention, die auch OrcaSlicer verwendet.

• Temperaturgrenzen: Die Materialtemperaturen (temperature und bed_temperature, ob in der Anfrage übermittelt oder aus dem Materialprofil gelesen) werden gegen min_hotend_temp / max_hotend_temp und min_bed_temp / max_bed_temp des Druckers geprüft. Ein Material, das mehr Hitze benötigt, als der gewählte Drucker liefern kann, wird abgelehnt statt kalkuliert. Nur FDM – Harz- und Pulvertechnologien haben weder Düse noch beheiztes Bett. Lassen Sie die Druckergrenzen leer, um die Prüfung zu überspringen.
• Aktivierte Technologien: Wenn Sie die Technologien in Ihren globalen Einstellungen eingeschränkt haben, wird eine Angebotsanfrage für eine deaktivierte Technologie abgelehnt. Lassen Sie die Einstellung leer, um alle Technologien zu akzeptieren.
• Materialpreisfelder: price_per_gram ist der Wert, den die Engine berechnet. Beim Speichern eines Materialprofils wird price_per_kg automatisch daraus neu berechnet (und price_per_gram wird aus price_per_kg abgeleitet, wenn nur der Kilogrammpreis angegeben wird), sodass die beiden nie voneinander abweichen können.

Stammparameter

Logik für Menge und Batch-Produktion

Unser System verwendet einen fortschrittlichen Packalgorithmus basierend auf der angegebenen 'quantity':

• FDM-Technologie: Teile werden nebeneinander auf der Bauplatte (X- und Y-Achse) platziert, soweit der Platz es zulässt.
• SLA-Technologie: Teile werden nebeneinander im Harzbehälter (X- und Y-Achse) positioniert.
• SLS-Technologie: Teile können in allen Achsen (X, Y und Z) gestapelt werden, um die Kapazität des Pulverbettes voll auszunutzen.

printer_config

Druckerkonfigurationsparameter. Alle Felder sind optional und verwenden Ihre Standardwerte aus dem Druckerprofil, falls nicht angegeben.

material_config

Materialkonfigurationsparameter. Alle Felder sind optional und verwenden Ihre Standardwerte aus dem Materialprofil, falls nicht angegeben.

quote_config

Konfigurationsparameter für die Angebotsberechnung. Alle Felder sind optional und verwenden Ihre Standardwerte aus den globalen Einstellungen, falls nicht angegeben. Die Währung ist standardmäßig auf Ihre Dashboard-Präferenz eingestellt (z. B. "USD", "TRY", "EUR").

6. Drucker- & Angebotsprofile

Konfigurieren Sie Druckereinstellungen und Preise, um genaue Angebote zu erhalten. Sie können Ihre Standardprofile im Dashboard im Bereich 'Slice-Profile' verwalten, die automatisch verwendet werden, wenn Sie in API-Anfragen keine Parameter angeben.

Profiltypen

• Druckerprofil – Konfigurieren Sie Ihre Druckereinstellungen (Bettgröße, Düsendurchmesser, Druckgeschwindigkeit, Schichthöhe, Beschleunigung, Jerk, Temperaturen usw.), um sie an Ihren tatsächlichen Drucker anzupassen. Legen Sie dieses als Ihr Standardprofil im Dashboard fest, und es wird für alle Angebotsanfragen verwendet, es sei denn, Sie überschreiben bestimmte Parameter.
• Materialprofil – Legen Sie Materialeigenschaften (Filamenttyp, Dichte, Durchmesser, Temperaturen, Lüftergeschwindigkeit, Retraktionseinstellungen, Preise) für jedes von Ihnen verwendete Material fest. Die API verwendet automatisch das Materialprofil, das dem von Ihnen in der Anfrage angegebenen filament_type entspricht.
• Globale Einstellungen – Konfigurieren Sie globale Angebotseinstellungen wie Mehrwertsteuersatz, feste Gebühren, Energiekosten und Standardwährung. Diese Einstellungen gelten für alle Angebote, es sei denn, sie werden in der Anfrage überschrieben.

Wie die Profilzusammenführung funktioniert

Wenn Sie eine Angebotsanfrage stellen, führt die API Ihre Anfrageparameter mit Ihren Dashboard-Profilen zusammen, wobei diese Priorität gilt:

1. Anfrageparameter – Werte, die Sie explizit in der API-Anfrage angeben, haben die höchste Priorität
2. Benutzerprofil – Wenn Sie ein benutzerspezifisches Profil als Standard festgelegt haben, wird dieses als Nächstes verwendet
3. Globales Profil – Wenn kein Benutzerprofil vorhanden ist, greift das System auf globale Standardwerte zurück

Das bedeutet, dass Sie nur die Parameter überschreiben können, die Sie benötigen (z. B. nur layer_height oder fill_density), während alle anderen Einstellungen aus Ihren Dashboard-Profilen beibehalten werden.

7. Webhooks

Echtzeitbenachrichtigungen erhalten, wenn Ereignisse in Ihrem Konto auftreten:

• POST /v2/webhooks - Einen neuen Webhook-Endpunkt erstellen
• GET /v2/webhooks - Ihre Webhooks auflisten
• GET /v2/webhooks/{webhook_id} - Webhook-Details und Lieferstatistiken abrufen
• PUT /v2/webhooks/{webhook_id} - Webhook-Einstellungen aktualisieren
• DELETE /v2/webhooks/{webhook_id} - Webhook entfernen
• POST /v2/webhooks/{webhook_id}/deliveries/{delivery_id}/resend - Eine frühere Zustellung erneut senden, etwa nachdem Sie Ihren Endpunkt repariert haben

Unterstützte Ereignisse: quote.completed, quote.failed, file.uploaded, file.deleted, job.status_changed, widget.added_to_cart, usage.alert. Webhooks enthalten HMAC-SHA256-Signaturen zur Sicherheitsüberprüfung.

Webhooks-Referenz: Payload-Struktur, Signaturverifizierung, Wiederholungsversuche und erneute Zustellung

8. Analysen & Berichte

Erhalten Sie Einblicke in Ihre API-Nutzung und Angebotsstatistiken:

• GET /v2/analytics/quotes - Erhalten Sie umfassende Angebotsstatistiken, einschließlich der Gesamtzahl der Angebote, durchschnittliche Preise und Trends bei der Materialverwendung.
• GET /v2/analytics/popular - Sehen Sie Ihre beliebtesten Materialien und Drucker-Konfigurationen.
• GET /v2/analytics/cost-trends - Analysieren Sie Kostentrends im Zeitverlauf (tägliche, wöchentliche oder monatliche Gruppierung).
• GET /v2/analytics/export - Exportieren Sie Ihre Angebote und Nutzungsdaten als CSV oder JSON.

9. Katalog & Bestand

Verwalten Sie die eigenen Drucker, Materialien, Farben, den Farbbestand, die Preise und Technologien des Kontos mit einem Server-Token. Das Widget liest denselben Katalog, eine Änderung erreicht das Angebotsformular also sofort. Widget-Tokens werden abgelehnt, und diese Aufrufe zählen nicht zum monatlichen Anfragekontingent:

• GET /v2/store/catalog - Alles, was das Konto anbietet, mit Bereitschaft je Technologie und knapp werdenden Farben
• GET /v2/store/catalog/schema - Die Drucker-, Material- und Preisformulare des Dashboards mit Grenzen, Einheiten und Hilfetexten in der gewünschten Sprache
• POST /v2/store/catalog/adopt - Globale Drucker und Materialien mit den gewählten Farben, Preisen und dem Anfangsbestand ins Konto kopieren
• POST /v2/store/catalog/materials - Ein Material anlegen, wahlweise ausgehend von einem globalen
• GET · PATCH · DELETE /v2/store/catalog/materials/{id} - Ein Material samt Bestandseinstellungen lesen, ändern oder löschen
• PUT /v2/store/catalog/materials/{id}/colors - Die Farbliste eines Materials ersetzen; der Bestand vorhandener Farben bleibt erhalten
• GET · PATCH · DELETE /v2/store/catalog/printers/{id} - Einen Drucker lesen, ändern oder löschen
• GET · PATCH · DELETE /v2/store/catalog/pricing - Die Preiseinstellungen lesen, ändern oder zurücksetzen; eine andere Währung ändert die Kontowährung, ohne Beträge umzurechnen
• GET · PUT /v2/store/catalog/technologies - Welche Technologien der Tarif erlaubt und welche aktiv sind
• GET · POST /v2/store/stock/movements - Zugang, Inventur oder Ausschuss erfassen und den Bestandsverlauf auflisten
• POST /v2/store/stock/orders - Das Material einer bezahlten Bestellung abbuchen, zurückbuchen oder prüfen, höchstens einmal je Angebot

PATCH-Bodys enthalten values und updated_at. values nutzt dieselben snake_case-Feldnamen wie die Katalogliste (ein Name, den das Formular nicht hat, wird mit 400 abgelehnt); wurde das Profil seit Ihrem Lesen geändert, antwortet der Aufruf mit 409 und error_key stale.

10. Ratenbegrenzung und Kontingente

Quote3D verwendet Ratenbegrenzung, um eine faire Nutzung und Systemstabilität zu gewährleisten.

• Ratenbegrenzungen werden pro API-Token angewendet und variieren je nach Endpunkt.
• Informationen zur Ratenbegrenzung sind in den Antwort-Headern enthalten. X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Window
• Wenn die Ratenbegrenzung erreicht ist, erhalten Sie eine 429 Too Many Requests-Antwort mit einem Retry-After-Header.
• Ihr Plan legt ein Angebotskontingent fest, das in jedem Abrechnungszeitraum zurückgesetzt wird, und ein Speicherkontingent, das nie zurückgesetzt wird und nur durch Löschen von Dateien frei wird
• Limits sind pro Deployment konfigurierbar, lesen Sie daher die aktuellen Werte aus, anstatt sie hart zu codieren. Sowohl die oben genannten Response-Header als auch dieser Endpoint melden diese: GET /v2/quota

11. Antworten & Fehler

Erfolgreiche Antworten haben zwei Formen. Aufrufe zu Angeboten, Jobs, gespeicherten Angebotsdetails, Webhooks, Analysen, Nutzung, Kontingent und Konfiguration verpacken ihre Nutzdaten als success: true mit dem Ergebnis unter data. Aufrufe zu Dateien, Upload-ID, Benutzer, Uploads, Angebotsliste, Druckbarkeit sowie Katalog & Bestand liefern ihre Felder auf oberster Ebene. Das genaue Schema jedes Aufrufs steht in der API-Referenz. Dateidownloads und CSV-Exporte liefern den reinen Dateiinhalt.

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

Pagination & Sortierung

List-Endpunkte wie /v2/quotes und /v2/user/uploads sind mittels der Query-Parameter limit und offset paginiert (Standard: 50 Ergebnisse, maximal 100). Neben den Ergebnissen geben sie ein Pagination-Objekt zurück, das total, limit, offset, has_more, page und total_pages enthält; verwenden Sie daher vorzugsweise has_more, anstatt das Ende der Liste selbst neu zu berechnen. Die Sortierung verwendet einen einzelnen, wiederholbaren Parameter im Format field:direction, zum Beispiel ?sort=created_at:desc&sort=total_price:asc; bei Uploads erfolgt die Sortierung standardmäßig nach dem neuesten zuerst.

Fehlerantworten

Jeder Fehler hat dieselbe Form: eine detail-Liste, die Parameter oder Feld benennt (loc, msg, code), ein error_code wie AUTH_001, eine error_summary und, wo sinnvoll, recovery_suggestions und documentation_url. Verzweigen Sie nach HTTP-Status und error_code, nicht nach dem Text, der sich ändern kann.

Asynchrone Angebote verhalten sich anders: Das Einreihen des Jobs in die Warteschlange ist mit 202 erfolgreich, und eine Berechnung, die danach fehlschlägt, erscheint als fehlerhafter Status mit einer Fehlermeldung am Job-Endpunkt – nicht als HTTP-Fehler. Überprüfen Sie immer den Job-Status und nicht nur den Statuscode, den Sie beim Start erhalten haben.

12. RESTful, versionierte API

• Alle Endpunkte sind versioniert (z.B. /v2/)
• Verwendet standardmäßige HTTP-Methoden: GET, POST, PUT, DELETE
• Beschrieben durch ein OpenAPI-3.0.3-Schema, das Sie in Ihre eigenen Werkzeuge importieren können
• Breaking Changes und Ergänzungen werden festgehalten im API-Changelog