Concepts clés : fichiers, devis et travaux

1. Authentification et Sécurité

Chaque point de terminaison exige une authentification avec votre jeton d'API Quote3D, à une exception près : la route d'envoi publique documentée sous Gestion des fichiers. Pour les appels externes, utilisez la route de base https://api.quote3d.com/v2. Envoyez le jeton soit comme Authorization: Bearer YOUR_TOKEN, soit comme X-API-Token. Générez vos jetons depuis votre tableau de bord Quote3D et gardez-les secrets.

Les jetons peuvent être limités par portée. Un jeton à accès complet atteint tous les points de terminaison, tandis qu'un jeton de portée widget est restreint à ceux dont le widget intégré a besoin. Tout appel hors de la portée d'un jeton renvoie 403. Vous pouvez consulter et modifier la portée d'un jeton sur la page Jetons de votre tableau de bord.

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/user Récupère les informations de votre compte, votre offre et vos quotas mensuels — c'est ici que se trouvent quotes_used, quotes_limit, storage_used, storage_limit et reset_date
• GET /v2/user/uploads Lister 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/quota Récupère vos limites de débit — la limite globale ainsi qu'un détail par point de terminaison avec les appels restants et les heures de réinitialisation — accompagnées de vos volumes de requêtes pour aujourd'hui, ce mois, cette année et depuis toujours
• GET /v2/usage Obtenir 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) :

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

• 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)
• GET /v2/file/{file_id} — Téléchargez un fichier en utilisant son file_id
• DELETE /v2/file/{file_id} — Supprimez un fichier dont vous n'avez plus besoin

L'envoi est refusé si le fichier n'est pas un modèle STL, 3MF ou OBJ valide, ou s'il dépasse la taille maximale de la plateforme (50 Mo par défaut). Les deux routes d'envoi appliquent les mêmes contrôles.

Comment vos fichiers sont stockés

Les modèles téléchargés sont stockés de manière chiffrée et ne sont jamais accessibles publiquement — il n’existe aucun lien permettant de servir directement un fichier stocké. Le champ file_path dans les réponses est le chemin de téléchargement authentifié (GET /v2/file/{file_id}), et non un emplacement sur le disque ; traitez-le donc comme un endpoint plutôt que comme une URL que vous pouvez partager. La suppression d’un fichier le retire du stockage, et pas seulement de vos listes.

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 :

• 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é.
• 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é.
• 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.
• GET /v2/quotes — Récupérez tout votre historique de devis avec une prise en charge de la pagination
• GET /v2/quotes/{quote_id} — Obtenez des informations détaillées sur un devis spécifique
• DELETE /v2/quotes/{quote_id} — Supprimez un devis de votre historique

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.

Les tableaux ci-dessous couvrent les paramètres que les intégrations redéfinissent le plus souvent. Ce n'est pas la liste complète — le moteur de devis accepte bien d'autres champs d'imprimante, de matériau et de tarification, et chacun d'eux peut être défini une fois dans vos Profils de découpe du tableau de bord au lieu d'être envoyé à chaque requête. Configurez-y vos profils et n'envoyez que ce qui varie d'un devis à l'autre ; la liste complète des champs figure dans le schéma OpenAPI.

Request Validation

Les champs numériques de printer_config, material_config et quote_config sont vérifiés par rapport à leurs bornes avant la mise en file d'attente de la tâche. Une valeur hors plage, un nombre non fini (NaN, Infinity), un type incorrect ou un nombre négatif là où seules les valeurs à partir de zéro ont un sens est rejeté avec un HTTP 400 et une VALIDATION_ERROR nommant le champ exact. Zéro reste accepté partout où il a un sens : une vitesse ou une accélération de 0 pour un rôle donné signifie « utiliser la valeur par défaut de l'imprimante », la même convention que celle d'OrcaSlicer.

• Limites de température : les températures du matériau (temperature et bed_temperature, qu'elles soient envoyées dans la requête ou lues depuis le profil de matériau) sont comparées aux valeurs min_hotend_temp / max_hotend_temp et min_bed_temp / max_bed_temp de l'imprimante. Un matériau nécessitant plus de chaleur que l'imprimante sélectionnée ne peut fournir est rejeté au lieu d'être chiffré. FDM uniquement : les technologies résine et poudre n'ont ni buse ni plateau chauffant. Laissez les limites de l'imprimante non renseignées pour ignorer ce contrôle.
• Technologies activées : si vous avez restreint les technologies dans vos paramètres globaux, toute demande de devis portant sur une technologie désactivée est rejetée. Laissez le paramètre vide pour accepter les trois.
• Champs de prix du matériau : price_per_gram est la valeur facturée par le moteur. Lors de l'enregistrement d'un profil de matériau, price_per_kg est automatiquement recalculé à partir de celle-ci (et price_per_gram est déduit de price_per_kg lorsque seul le prix au kilogramme est fourni), de sorte que les deux ne peuvent jamais diverger.

Paramètres racines

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.

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.

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.

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

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.

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

1. Paramètres de la requête - Les valeurs que vous fournissez explicitement dans la requête API ont la priorité la plus élevée
2. Profil utilisateur - Si vous avez un profil spécifique à l'utilisateur défini comme par défaut, il est utilisé ensuite
3. 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 webhook
• GET /v2/webhooks - Lister tous vos webhooks
• GET /v2/webhooks/{webhook_id} - Obtenir les détails du webhook et les statistiques de livraison
• PUT /v2/webhooks/{webhook_id} - Mettre à jour les paramètres du webhook
• DELETE /v2/webhooks/{webhook_id} - Supprimer un webhook

Événements pris en charge : quote.completed, quote.failed, file.uploaded, file.deleted, job.status_changed, widget.added_to_cart. Les webhooks incluent des signatures HMAC-SHA256 pour la vérification de la sécurité.

Référence des webhooks : structure de la charge utile, vérification de signature, reprises et relivraison

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ériaux
• GET /v2/analytics/popular - Visualisez vos matériaux et configurations d'imprimante les plus populaires
• GET /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, X-RateLimit-Window
• 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
• Les limites sont configurables par déploiement : lisez les valeurs courantes plutôt que de les coder en dur. Les en-têtes de réponse ci-dessus comme ce point de terminaison les indiquent : GET /v2/quota

10. Réponses et erreurs

Chaque réponse JSON utilise la même enveloppe. Un appel réussi renvoie success: true avec la charge utile du point de terminaison sous data, afin que votre client lise partout une structure cohérente. Les téléchargements de fichiers et les exports CSV font exception : ils renvoient le corps brut du fichier au lieu de l'enveloppe.

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

Pagination et tri

Les points de terminaison de liste tels que /v2/quotes et /v2/user/uploads sont paginés avec les paramètres limit et offset (50 résultats par défaut, 100 au maximum). À côté des résultats, ils renvoient un objet pagination contenant total, limit, offset, has_more, page et total_pages : préférez donc has_more plutôt que de recalculer vous-même la fin de la liste. Le tri utilise un paramètre unique et répétable au format field:direction, par exemple ?sort=created_at:desc&sort=total_price:asc ; les envois sont triés du plus récent au plus ancien par défaut.

Réponses d'erreur

Les échecs renvoient success: false avec un message d'erreur lisible et le code de statut HTTP correspondant. Basez toujours votre logique sur le code de statut plutôt que sur le texte du message, qui peut être reformulé.

Les devis asynchrones sont différents : la mise en file d'attente réussit avec un 202, et un calcul qui échoue ensuite se manifeste par un statut failed accompagné d'un message d'erreur sur le point de terminaison du travail — et non par une erreur HTTP. Inspectez toujours le statut du travail, pas seulement le code obtenu au démarrage.

11. API RESTful et versionnée

• Tous les points de terminaison sont versionnés (par exemple, /v2/)
• Utilise les méthodes HTTP standard : GET, POST, PUT, DELETE
• Décrite par un schéma OpenAPI 3.0.3 que vous pouvez importer dans vos propres outils
• Les ruptures de compatibilité et les ajouts sont consignés dans le journal des modifications de l'API