Engine API

Tout ce que CutOptim fait dans votre navigateur part d’un seul calcul : avec ces pièces et ce stock, quelle est la meilleure façon de les découper ? L’Engine API expose exactement ce calcul sur Internet, pour qu’un autre programme puisse poser la question et récupérer la réponse — sans navigateur, sans clic, sans personne connectée.

C’est toute l’idée. Ce n’est pas un nouvel optimiseur, ni un meilleur optimiseur, ni un forfait supérieur. C’est le même moteur, joignable par un logiciel au lieu d’une personne.

Est-ce fait pour moi ?

Pour l’immense majorité des utilisateurs de CutOptim, la réponse honnête est non. Si votre journée de travail consiste à ouvrir CutOptim, saisir des pièces et du stock, puis imprimer ou exporter le plan, l’application est le produit et cette page ne vous concerne pas.

L’Engine API répond à une seule situation : des plans de découpe doivent apparaître dans un logiciel que vous utilisez déjà, sans que personne ne se rende sur CutOptim. En pratique, cela concerne l’une de ces deux personnes :

• Vous utilisez déjà un logiciel dans lequel le plan de découpe a sa place. Un ERP qui porte vos commandes, un outil de devis qui chiffre les chantiers, ou le logiciel propre à une machine. Au lieu qu’un opérateur ressaisisse la même liste de pièces dans CutOptim, ce programme interroge directement le moteur et affiche le plan là où le travail se fait déjà.
• Vous faites développer un logiciel pour vous. Par un développeur interne, une société informatique locale ou le fournisseur de votre machine. L’Engine API est ce à quoi il se connecte.

Si vous ne savez pas de quel côté de la frontière vous vous situez, voici un bon test : le plan pourrait-il apparaître sans que personne ne le demande ? Si oui, l’API est pertinente. Si c’est toujours une personne qui décide de créer un plan de découpe, l’application est déjà le bon outil.

Ce qu’elle fait

Votre logiciel envoie les deux mêmes choses que vous saisiriez dans l’application — une liste de pièces et une liste de stock — au format JSON. Le moteur renvoie une réponse complète :

• La disposition complète. Chaque pièce, positionnée sur un panneau ou une barre précis, en indiquant si elle a été tournée.
• Un plan de découpe. Pas seulement une image de rectangles : la véritable séquence de coupes guillotine, dans l’ordre, pour que le plan puisse être exécuté sur une scie à panneaux.
• Les chiffres. Combien de panneaux ou de barres le chantier demande, le pourcentage de rendement, le nombre de coupes nécessaires et le prix total de la matière utilisée. Pour les panneaux, vous obtenez en plus les deux décomptes honnêtes des coupes — les lignes de coupe, qui regroupent les coupes partageant un même réglage de butée, et les passes de scie, qui comptent chaque passe — ainsi que la longueur sciée totale.
• En option, le dessin. Demandez include: ["svg","csv","dxf"] et la réponse porte aussi la disposition sous forme de fichier prêt à l’emploi — un dessin SVG 2D autonome, un DXF R12/AC1009 ou une liste de coupe CSV — en ligne dans le JSON, sans stockage ni second appel. (SVG en 2D uniquement.)
• Vos propres identifiants, renvoyés. Attachez un objet meta — un numéro d’article, une ligne de commande, une référence client — à toute pièce ou ligne de stock, et il revient inchangé sur chaque pièce placée et chaque panneau ou barre, pour que le plan corresponde à votre propre système. C’est le champ à utiliser lorsque vous voulez envoyer tous vos panneaux, marquer chacun d’eux de votre propre code et relire quel panneau l’optimiseur a retenu — placez le code dans stock[].meta et il vous revient sur sheets[].meta. Il n’influence jamais le placement. N’utilisez pas le champ material pour identifier vos lignes : material est une partition stricte (une pièce n’est jamais découpée que dans du stock du même matériau), si bien qu’étiqueter chaque ligne de stock avec un matériau en laissant les pièces sans étiquette fait revenir toutes les pièces en unmatched, avec un résultat vide.

Il y a quatre modes d’optimisation, tous correspondant à l’application — un pour les panneaux 2D, un pour le matériau 1D linéaire (barres, profilés, tubes), un pour le bois, dont la matière possède une section, et l’imbrication par forme réelle (POST /v1/optimize/nest), qui imbrique des polygones arbitraires pour la découpe laser, plasma et jet d’eau (le mode Nesting de l’application). Chaque endpoint d’optimisation dispose aussi d’un endpoint de validation gratuit qui vérifie une requête sans la résoudre (voir ci-dessous).

Endpoints

L’URL de base est https://api.cutoptim.com. Les endpoints d’optimisation et d’usage portent une clé dans un en-tête Authorization: Bearer <key> ; les endpoints de validation et de disponibilité ne nécessitent aucune clé.

La plupart des appels reçoivent directement le résultat terminé. La seule exception est le moteur max asynchrone (voir Trois moteurs ci-dessous) : une soumission max renvoie un identifiant de travail, et vous interrogez GET /v1/jobs/{id} jusqu’à ce que le plan soit prêt.

Les endpoints de validation prennent le même corps que l’endpoint d’optimisation correspondant et le vérifient sans lancer la résolution : une requête mal formée revient sous forme de 400 nommant le champ fautif exact, et une requête bien formée renvoie valid: true accompagné d’avertissements de faisabilité (par exemple, une pièce qui ne tient dans aucun stock). Ils ne coûtent rien et ne nécessitent aucune clé : vous pouvez donc valider vos charges utiles pendant que vous construisez l’intégration — avant même de détenir une clé — et confirmer qu’une requête ne sera pas rejetée sans dépenser l’un de vos appels mensuels.

Pourquoi le bois a son propre endpoint

Le matériau linéaire ne connaît qu’une dimension, sa longueur : n’importe quelle barre peut donc fournir n’importe quelle pièce. Le bois ne fonctionne pas ainsi : une pièce 50×150 ne peut pas sortir d’une barre 50×100, quelle que soit la longueur restante. L’endpoint bois prend donc les deux côtés de la section sur chaque pièce et chaque ligne de stock, découpe le travail par section, associe à chaque section son propre stock et renvoie les sections séparément — chacune avec ses barres et ses totaux, à côté des chiffres du travail complet.

Deux détails à connaître avant de l’intégrer :

• Les deux côtés de la section peuvent être envoyés dans n’importe quel ordre. 50×100 et 100×50 sont la même poutre retournée et forment une seule section. Une différence dans la façon dont vos données ont été saisies ne peut donc pas faire disparaître de la matière.

• « Aucun stock de cette section » et « n’a pas tenu » sont signalés séparément. Le premier est un manque de matière, le second un problème de capacité, et ils ne se corrigent pas de la même façon — les mélanger dans une seule liste enverrait votre utilisateur chercher au mauvais endroit.

Vous pourriez approcher ce résultat avec plusieurs appels 1d de votre côté, en groupant les pièces vous-même. Cela coûterait une requête de votre quota par section au lieu d’une pour le travail, déplacerait la correspondance du stock dans votre code et produirait un total que vous devriez assembler — et qui ne correspondrait pas nécessairement à ce que l’application CutOptim affiche pour le même travail.

Des pièces depuis un fichier CAO

L’endpoint de nesting n’accepte pas que des coordonnées. Une pièce peut porter à la place un source — un document SVG ou DXF — et le serveur en extrait le contour, ainsi que les trous qu’il contient. C’est le même lecteur que celui de l’application lorsque vous déposez un dessin sur son mode Nesting : une bibliothèque de pièces qui existe déjà en fichiers CAO n’a donc pas à être réécrite en listes de coordonnées.

Le fichier ne remplace que la géométrie. Quantité, matériau, rotations autorisées et vos propres métadonnées restent des champs ordinaires de la ligne de pièce, exactement comme lorsque vous envoyez des coordonnées. Un fichier décrit une pièce ; lorsqu’un même dessin contient plusieurs composants distincts, POST /v1/import/nest le découpe d’abord en lignes de pièces prêtes à l’emploi — et cet appel exige une clé mais ne consomme aucune requête de votre quota mensuel.

Rien n’est conservé. Le fichier n’existe que comme la requête elle-même : il est lu en mémoire et disparaît au moment où la réponse est écrite. Aucune copie ne reste sur un disque ou dans une base de données, rien n’atterrit dans un journal, et il n’y a rien à supprimer ensuite. Nous traitons les unités de la même façon — un DXF peut déclarer des millimètres ou des pouces et nous rapportons ce qu’il a déclaré, mais les coordonnées ne sont jamais converties, car aucune valeur de cette API ne porte d’unité.

La même réponse à chaque fois

Le moteur est déterministe : une même entrée produit toujours le même résultat. Il n’y a aucun aléatoire et aucune horloge dans l’algorithme.

Cela peut sembler théorique, mais c’est justement la raison pratique de construire dessus. Les résultats peuvent être mis en cache — si vous avez déjà posé la question pour exactement ce chantier, vous pouvez réutiliser la réponse en toute sécurité au lieu de la redemander. Cela signifie aussi que l’intégration peut être testée : un plan peut être comparé à un résultat connu comme bon, et un écart est un véritable écart, pas du bruit. Un logiciel qui annonce un prix à un client le lundi annoncera le même prix le vendredi.

Trois moteurs

L’API propose plusieurs moteurs au choix. Les deux premiers s’exécutent de façon synchrone ; le troisième est asynchrone. La différence n’est pas une question de qualité : c’est un compromis entre la vitesse, le fait que le résultat soit réalisable ou non sur une scie à panneaux, et sa proximité avec le minimum théorique.

• heuristic est le moteur par défaut, celui-là même qu’utilise l’application. Il produit des dispositions guillotine : le meilleur rendement, toute disposition sciable sur une scie à panneaux, et toujours un plan de découpe complet. Synchrone.
• balanced s’active explicitement. Il utilise à la place une imbrication libre, beaucoup plus rapide sur les très gros chantiers — mesurée à environ 25× plus rapide sur un chantier de 2 000 pièces — au prix d’un rendement légèrement plus faible. La réserve importante : ses dispositions ne peuvent souvent pas être coupées de rive à rive, et dans ce cas il ne renvoie aucun plan de découpe. Synchrone.
• max s’active explicitement et fonctionne uniquement en 2D. C’est une recherche arborescente côté serveur qui atteint l’optimum prouvé sur bien plus de travaux que le moteur par défaut, et ses dispositions restent coupables en guillotine. Le prix est le temps : un calcul max prend de quelques secondes à une minute, il ne répond donc pas dans la réponse. À la place, POST /v1/optimize/2d avec engine: "max" renvoie un identifiant de travail, et vous interrogez GET /v1/jobs/{id} jusqu’à ce qu’il soit prêt. Il reste déterministe. Réservez-le aux gros chantiers de valeur pour lesquels attendre en vaut la peine, afin de gagner les derniers panneaux. Il modélise un seul format de stock en pleine dimension et en quantité illimitée : une requête qui porte en plus un deuxième format de stock, un trim par côté, un stock limité (respectStock), des matériaux ou des groupes de fil est refusée d’emblée par un 400 qui nomme précisément ce qu’il ne sait pas faire — avant qu’un appel ne soit facturé. Envoyez ces travaux à heuristic, qui les modélise tous.

Limites

Chaque requête est bornée, pour qu’un chantier qui déraille échoue clairement au lieu de rester bloqué :

Obtenir un accès

Commencez par la page Engine API. L’Engine API est facturée séparément des offres de l’application, et aucun changement d’offre ne l’active.

1. Abonnez-vous, ou écrivez-nous. S’abonner depuis la page Engine API est la voie la plus rapide : elle propose une période d’essai, et l’accès arrive tout seul sur votre compte. Si vous préférez décrire d’abord votre intégration, ou s’il vous faut un volume au-delà de l’offre standard, écrivez-nous en indiquant ce que vous voulez connecter et combien de plans de découpe par mois cela représente environ.
2. L’accès est ajouté à votre compte. Rien d’autre ne change sur votre compte.
3. Créez une clé. Une carte Clés API apparaît sur votre tableau de bord dès que votre compte dispose de l’accès API. Vous y créez, nommez et supprimez vos clés vous-même.
4. Copiez la clé immédiatement. La clé complète n’est affichée qu’une seule fois, au moment où vous la créez.

Traitez une clé comme un mot de passe : sa place est dans la configuration de votre logiciel, pas dans un e-mail, un tableur ou une capture d’écran.

Ce que fait la carte Clés API de votre tableau de bord

Trois commandes, et il vaut la peine de préciser ce que chacune change — surtout la dernière, dont beaucoup pensent qu’elle touche la facturation. Ce n’est pas le cas.

• Créer une clé. Génère une nouvelle clé et l’affiche une seule fois, sur place. Le nom (Intégration ERP, staging) sert uniquement à les distinguer par la suite. Jusqu’à 10 clés actives par compte.
• La barre d’utilisation. Deux chiffres : le total de votre compte pour le mois calendaire face au quota, et par clé, ce qu’elle a consommé. Le chiffre par clé répond à quelle intégration consomme l’enveloppe — ce n’est pas un budget distinct.
• Révoquer. Met cette clé hors service dès l’appel suivant. La ligne reste visible pour ne pas perdre son historique.

Un quota pour le compte, pas un par clé

Chaque clé active de votre compte puise dans la même enveloppe mensuelle. Créer une deuxième clé ne crée pas un deuxième quota — les clés servent à séparer la préproduction de la production, à donner à chaque intégration son propre identifiant, et à en révoquer une sans perturber les autres.

GET /v1/usage renvoie la position du compte (used, limit, remaining) et répond donc à la question que vous vous posez vraiment — combien reste-t-il avant que les appels échouent — quelle que soit la clé utilisée pour demander. Une fois l’enveloppe épuisée, toutes les clés renvoient 402, pas seulement celle qui l’a consommée.

Tarif et quota

L’Engine API est facturée séparément des forfaits de l’application, avec un nombre fixe de requêtes par mois. Le tarif actuel, le quota mensuel de requêtes et la durée de l’essai sont tous indiqués sur la page Engine API — cette page les lit dans notre configuration tarifaire, la valeur qui y figure est donc toujours exacte.

Pour le détail technique — la structure exacte de la requête et de la réponse, toutes les options, tous les codes d’erreur et le fonctionnement du versionnage — voir la documentation de l’API.

Ce que cela ne change pas

Cela vaut la peine d’être dit clairement, car l’Engine API se prête facilement au malentendu d’un changement dans le produit :

• L’optimiseur de l’application est inchangé. Il s’exécute toujours dans votre navigateur, exactement comme avant.
• Gratuit, Pro et Atelier ne sont pas touchés. Ces forfaits incluent toujours l’optimiseur intégré à l’application, avec les mêmes limites qu’avant. Rien n’a été déplacé derrière l’API.
• Rien de ce que vous faites dans l’application ne consomme de requêtes API. Le quota mensuel de l’API n’est entamé que par les appels que votre propre logiciel effectue.

L’Engine API est un ajout destiné aux personnes qui intègrent CutOptim dans d’autres logiciels. Si ce n’est pas votre cas, rien n’a changé.