Concepts fondamentaux
Cette page présente les idées et les modèles de base qui alimentent la plateforme. Comprendre ces concepts vous aidera à tirer le meilleur parti de l'API et à créer des intégrations robustes pour les flux de travail d'impression 3D.
Route de base de l'API
Pour les appels API externes, envoyez les requêtes directement à https://api.quote3d.com/v2/... (par exemple, GET https://api.quote3d.com/v2/user).
Dans votre logiciel, configurez https://api.quote3d.com comme hôte API/URL de base et appelez les chemins v2 tels que /v2/user, /v2/file et /v2/quotes.
1. Authentification et Sécurité
Tous les points de terminaison de l'API nécessitent une authentification à l'aide de votre jeton API Quote3D. Pour les appels externes, utilisez la route de base https://api.quote3d.com/v2. Envoyez-le soit sous la forme Authorization: Bearer <token>, soit via X-API-Token. Générez des jetons à partir de votre tableau de bord Quote3D et gardez-les secrets.
Rappel : Conservez vos API tokens en sécurité. Ne les partagez jamais publiquement ni ne les intégrez à un contrôle de version.
2. Gestion du compte
Gérez votre compte, vos téléversements et vos statistiques d'utilisation via des points de terminaison dédiés :
GET /v2/userRécupérer les détails de votre compteGET /v2/user/uploadsLister tous les fichiers que vous avez téléversés sur votre compte. Ils sont listés du plus récent au plus ancien.GET /v2/quotaObtenir vos limites de quota actuelles et votre utilisation pour les devis et le stockageGET /v2/usageObtenir des analyses d'utilisation détaillées, notamment les statistiques des points de terminaison, l'utilisation des matériaux et les tendances basées sur le temps
3. Gestion des fichiers
Téléchargez, téléchargez et gérez vos fichiers de modèles 3D (formats STL, 3MF, OBJ) :
- Obtenez un upload_id temporaire pour télécharger un nouveau fichier via la route de téléchargement public.:
GET /v2/file/upload-id- Obtenez un upload_id temporaire pour télécharger un nouveau fichier via la route de téléchargement public. - Cette route NE nécessite PAS d'authentification. Utilisez-la côté client pour télécharger des fichiers directement vers notre stockage.:
POST /v2/file/public/{upload_id}- Cette route NE nécessite PAS d'authentification. Utilisez-la côté client pour télécharger des fichiers directement vers notre stockage.L'utilisation de la route de téléchargement public vous permet d'éviter de router les fichiers volumineux via votre serveur backend. Cela empêche d'exposer votre jeton API et réduit la charge du serveur.
- Téléchargez un fichier depuis votre serveur (nécessite une authentification, utilisez ceci lorsque vous souhaitez télécharger depuis votre backend):
POST /v2/file— Téléchargez un fichier depuis votre serveur (nécessite une authentification, utilisez ceci lorsque vous souhaitez télécharger depuis votre backend) - Téléchargez un fichier en utilisant son file_id:
GET /v2/file/{file_id}— Téléchargez un fichier en utilisant son file_id - Supprimez un fichier dont vous n'avez plus besoin:
DELETE /v2/file/{file_id}— Supprimez un fichier dont vous n'avez plus besoin
4. Informations sur la pièce et analyse technique
Vérifiez si vos modèles sont imprimables, obtenez les dimensions de la pièce et des métriques techniques avancées :
POST /v2/printability/{file_id}Analyse Instantanée – Vérifiez les mesures, le volume, la surface et l'intégrité géométrique (bords ouverts/non-manifold) avant de générer un devis.
Quote3D va au-delà des simples vérifications de dimensions ; il analyse l'intégrité manifold du modèle et évalue le risque d'adhésion au plateau, critique pour l'impression 3D. Ces métriques sont fournies dans les réponses Printability et Quote.
5. Opérations de devis
Générez des devis instantanés pour vos impressions 3D et gérez l'historique des devis :
- Démarrez le calcul asynchrone d'un devis pour un modèle 3D. Renvoie un ID de tâche ; utilisez l'endpoint des tâches pour récupérer le résultat une fois terminé.:
POST /v2/file/quote/{file_id}— Démarrez le calcul asynchrone d'un devis pour un modèle 3D. Renvoie un ID de tâche ; utilisez l'endpoint des tâches pour récupérer le résultat une fois terminé. - Endpoint asynchrone alternatif pour les devis. Renvoie un ID de tâche que vous pouvez utiliser pour vérifier l'état et récupérer le résultat une fois terminé.:
POST /v2/file/quote/{file_id}/async— Endpoint asynchrone alternatif pour les devis. Renvoie un ID de tâche que vous pouvez utiliser pour vérifier l'état et récupérer le résultat une fois terminé. - Vérifiez l'état d'une tâche de devis asynchrone. Renvoie le pourcentage d'avancement et l'état d'achèvement.:
GET /v2/jobs/{job_id}— Vérifiez l'état d'une tâche de devis asynchrone. Renvoie le pourcentage d'avancement et l'état d'achèvement. - Récupérez tout votre historique de devis avec une prise en charge de la pagination:
GET /v2/quotes— Récupérez tout votre historique de devis avec une prise en charge de la pagination - Obtenez des informations détaillées sur un devis spécifique:
GET /v2/quotes/{quote_id}— Obtenez des informations détaillées sur un devis spécifique - Supprimez un devis de votre historique:
DELETE /v2/quotes/{quote_id}— Supprimez un devis de votre historique
Workflow asynchrone : POST /v2/file/quote/{file_id} renvoie d'abord un ID de tâche. Utilisez GET /v2/jobs/{job_id} pour le résultat compact une fois terminé, et GET /v2/quotes/{quote_id} pour la charge utile détaillée du devis stockée lorsqu'elle est disponible.
Paramètres de la demande de devis
Lors de la génération d'un devis, vous pouvez fournir une configuration personnalisée dans le corps de la requête. Tous les paramètres que vous ne spécifiez pas seront automatiquement extraits des paramètres de votre Profil de découpe du Tableau de bord. Cela vous permet de remplacer des paramètres spécifiques par devis tout en conservant les paramètres par défaut pour les autres.
Important : Si vous ne fournissez pas un paramètre dans votre requête, l'API utilisera la valeur de votre Profil de découpe du Tableau de bord (Profil d'imprimante, Profil de matériau ou Paramètres globaux). Assurez-vous de configurer vos profils par défaut dans le Tableau de bord pour des devis cohérents. Vous pouvez également configurer tous vos paramètres dans un Profil d'imprimante spécifique sur le Tableau de bord et simplement transmettre son 'printer_id' dans votre requête pour appliquer ces paramètres instantanément sans les transmettre individuellement.
Priorité de configuration : Les valeurs envoyées dans la requête de l'API V2 remplacent les valeurs du profil utilisateur sélectionné ; tout champ manquant revient ensuite aux profils par défaut utilisateur/global.
Paramètres racines
| Paramètre | Type | Description |
|---|---|---|
| printer_id | string | Facultatif. ID d'une imprimante spécifique à utiliser au lieu de l'imprimante par défaut. |
| quantity | number | Facultatif. Le nombre total de copies à produire (Par défaut : 1). |
Logique de quantité et de production en lots
Notre système utilise un algorithme d'emballage avancé basé sur la 'quantity' spécifiée :
- Technologie FDM : Les pièces sont placées côte à côte sur le plateau d'impression (axes X et Y) dans la mesure de l'espace disponible.
- Technologie SLA : Les pièces sont positionnées côte à côte dans le bac à résine (axes X et Y).
- Technologie SLS : Les pièces peuvent être empilées sur tous les axes (X, Y et Z) pour utiliser pleinement la capacité du lit de poudre.
Grâce à cet arrangement optimisé, si plusieurs pièces peuvent tenir dans un seul lot, les coûts fixes tels que le préchauffage, le refroidissement et les changements de couches ne sont appliqués que par lot requis. Cela garantit des prix réalistes et rentables pour les commandes en volume.
printer_config
Paramètres de configuration de l'imprimante. Tous les champs sont facultatifs et utiliseront les valeurs par défaut de votre Profil d'imprimante si non fournis.
| Paramètre | 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 |
| SPÉCIFIQUE SLA | ||
| sla_exposure_time | number | SLA : Temps d'exposition par couche (secondes) |
| sla_bottom_exposure_time | number | SLA : Temps d'exposition de base (secondes) |
| sla_bottom_layer_count | number | SLA : Nombre de couches de base |
| sla_lift_distance | number | SLA : Distance de levage (mm) |
| sla_lift_speed | number | SLA : Vitesse de levage (mm/s) |
| sla_retract_speed | number | SLA : Vitesse de rétraction (mm/s) |
| sla_cleaning_cost | number | SLA : Coût fixe de nettoyage par impression (IPA, consommables) |
| SPÉCIFIQUE SLS | ||
| sls_laser_speed | number | SLS : Vitesse du laser (mm/s) |
| sls_hatch_spacing | number | SLS : Espacement des hachures (mm) |
| sls_layer_thickness | number | SLS : Épaisseur de couche (mm) |
| sls_layer_recoat_time | number | SLS : Temps de réenduction de couche (secondes) |
| sls_preheat_time | number | SLS : Temps de préchauffage (secondes) |
| sls_cooling_time | number | SLS : Temps de refroidissement (secondes) |
| 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
Paramètres de configuration du matériau. Tous les champs sont facultatifs et utiliseront les valeurs par défaut de votre Profil de matériau si non fournis.
Intégration du profil de matériau : Le paramètre filament_type doit correspondre à un nom de matériau de votre Profil de matériau du Tableau de bord. Lorsque vous spécifiez un filament_type (par exemple, "PLA", "ABS", "PETG"), l'API charge automatiquement toutes les propriétés de ce Profil de matériau, y compris la densité, les températures, les paramètres de rétraction et les prix.
Précision des prix : Pour des calculs de coûts précis, assurez-vous de définir à la fois price_per_kg et price_per_gram dans votre Profil de matériau. L'API utilise ces valeurs pour calculer les coûts des matériaux en fonction du poids réel du filament utilisé dans l'impression. Si ces valeurs ne sont pas définies dans votre profil, vous pouvez les remplacer dans la requête API.
Exemple : Si vous avez un profil de matériau "PLA" dans votre Tableau de bord avec price_per_kg : 20.0 et price_per_gram : 0.02, vous pouvez simplement envoyer {"filament_type": "PLA"} dans votre requête, et tous les prix seront calculés automatiquement.
| Paramètre | Type | Description |
|---|---|---|
| filament_type | string | Filament type (PLA, ABS, PETG, etc.) |
| color | string | Nom de la couleur (ex. 'Blanc', 'Noir', '#FFFFFF'). Remarque : Pour les technologies SLA/SLS, la couleur n'est appliquée que si 'post_processing' est défini sur '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
Paramètres de configuration du calcul de devis. Tous les champs sont facultatifs et utiliseront vos valeurs de Paramètres globaux par défaut si non fournis. La devise est par défaut celle de votre tableau de bord (par exemple, 'USD', 'TRY', 'EUR').
| Paramètre | Type | Description |
|---|---|---|
| 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 | Spécifique SLA/Résine : 'solid', '2mm' ou '3mm' (Valeur par défaut : 'solid') |
| post_processing | string | Spécifique SLA/SLS : 'standard', 'ponçage', 'peinture' ou 'peint' (Valeur par défaut : '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). |
Conseil : Les devis sont automatiquement enregistrés dans votre compte. Vous pouvez y accéder à tout moment via les points de terminaison de l'historique des devis.
6. Profils d'imprimante et de devis
Configurez les paramètres de l'imprimante et les prix pour obtenir des devis précis. Vous pouvez gérer vos profils par défaut dans la section Profils de découpe du Tableau de bord, qui seront utilisés automatiquement lorsque vous ne spécifiez pas de paramètres dans les requêtes API.
Types de profils
- Profil d'imprimante - Configurez les paramètres de votre imprimante (taille du plateau, diamètre de la buse, vitesse d'impression, hauteur de couche, accélération, jerk, températures, etc.) pour correspondre à votre imprimante réelle. Définissez-le comme profil par défaut dans le Tableau de bord, et il sera utilisé pour toutes les demandes de devis, sauf si vous remplacez des paramètres spécifiques.
- Profil de matériau - Définissez les propriétés du matériau (type de filament, densité, diamètre, températures, vitesse du ventilateur, paramètres de rétraction, prix) pour chaque matériau que vous utilisez. L'API utilisera automatiquement le profil de matériau correspondant au filament_type que vous spécifiez dans la requête.
- Paramètres globaux - Configurez les paramètres globaux du devis tels que le taux de taxe, les frais fixes, les coûts énergétiques et la devise par défaut. Ces paramètres s'appliquent à tous les devis, sauf s'ils sont remplacés dans la requête.
Bonne pratique : Configurez vos profils par défaut dans la section Profils de découpe du Tableau de bord. De cette façon, vous pouvez effectuer des demandes de devis simples sans spécifier tous les paramètres, et l'API utilisera automatiquement vos paramètres configurés par défaut. Vous pouvez toujours remplacer n'importe quel paramètre par requête si nécessaire.
Fonctionnement de la fusion des profils
Lorsque vous effectuez une demande de devis, l'API fusionne vos paramètres de requête avec vos profils du Tableau de bord en utilisant cette priorité :
- Paramètres de la requête - Les valeurs que vous fournissez explicitement dans la requête API ont la priorité la plus élevée
- Profil utilisateur - Si vous avez un profil spécifique à l'utilisateur défini comme par défaut, il est utilisé ensuite
- Profil global - Si aucun profil utilisateur n'existe, le système revient aux paramètres globaux par défaut
Cela signifie que vous pouvez remplacer uniquement les paramètres dont vous avez besoin (par exemple, uniquement layer_height ou fill_density) tout en conservant tous les autres paramètres de vos profils du Tableau de bord.
7. Webhooks
Recevez des notifications en temps réel lorsque des événements se produisent dans votre compte :
POST /v2/webhooks- Créer un nouveau point de terminaison webhookGET /v2/webhooks- Lister tous vos webhooksGET /v2/webhooks/{webhook_id}- Obtenir les détails du webhook et les statistiques de livraisonPUT /v2/webhooks/{webhook_id}- Mettre à jour les paramètres du webhookDELETE /v2/webhooks/{webhook_id}- Supprimer un webhook
Événements pris en charge : quote.completed, quote.failed, job.status_changed, widget.added_to_cart, file.uploaded. Les webhooks incluent des signatures HMAC-SHA256 pour la vérification de la sécurité.
8. Analyses et Rapports
Obtenez des informations sur l'utilisation de votre API et les statistiques de devis :
GET /v2/analytics/quotes- Obtenez des statistiques complètes sur les devis, notamment le nombre total de devis, les prix moyens et les tendances de l'utilisation des matériauxGET /v2/analytics/popular- Visualisez vos matériaux et configurations d'imprimante les plus populairesGET /v2/analytics/cost-trends- Analysez l'évolution des coûts dans le temps (regroupement quotidien, hebdomadaire ou mensuel)GET /v2/analytics/export- Exportez vos devis et vos données d'utilisation au format CSV ou JSON
9. Limitation de débit et quotas
Quote3D utilise la limitation de débit pour garantir une utilisation équitable et la stabilité du système :
- Les limites de débit sont appliquées par jeton API et varient en fonction du point de terminaison
- Les informations de limitation de débit sont incluses dans les en-têtes de réponse :
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset - En cas de limitation de débit, vous recevrez une réponse 429 Trop de requêtes avec un en-tête Retry-After
- Les quotas mensuels pour les devis et le stockage sont basés sur votre plan d'abonnement
Bonne pratique : Implémentez un retour exponentiel lorsque vous gérez les erreurs de limitation de débit pour éviter de surcharger l'API.
10. API REST, versionnée
- Tous les points de terminaison sont versionnés (par exemple, /v2/)
- Utilise les méthodes HTTP standard :
- Respecte les normes OpenAPI 3.1.0 pour le schéma et la documentation
- Le journal des modifications de l'API est disponible à :