Engine API

Alles, was CutOptim in Ihrem Browser tut, beginnt mit einer einzigen Berechnung: Wie schneidet man diese Teile aus diesem Ausgangsmaterial am besten zu? Die Engine API stellt genau diese Berechnung über das Internet bereit, sodass ein anderes Programm die Frage stellen und die Antwort zurückbekommen kann — kein Browser, kein Klicken, niemand angemeldet.

Das ist die ganze Idee. Es ist kein neuer Optimierer, kein besserer Optimierer und kein größerer Tarif. Es ist dieselbe Engine, erreichbar für Software statt für einen Menschen.

Ist das etwas für mich?

Für die überwältigende Mehrheit der CutOptim-Nutzer lautet die ehrliche Antwort nein. Wenn Ihr Arbeitstag darin besteht, CutOptim zu öffnen, Teile und Ausgangsmaterial einzutippen und den Plan zu drucken oder zu exportieren, dann ist die App das Produkt, und diese Seite ist für Sie ohne Belang.

Die Engine API ist für eine Situation gedacht: Schnittpläne sollen in Software erscheinen, die Sie bereits nutzen, ohne dass jemand CutOptim aufruft. In der Praxis heißt das eine von zwei Personen:

• Sie betreiben schon Software, in die der Schnittplan gehört. Ein ERP, das Ihre Aufträge führt, eine Angebotssoftware, die Aufträge kalkuliert, oder die Software einer Maschine. Anstatt dass eine Bedienerin oder ein Bediener dieselbe Teileliste erneut in CutOptim eintippt, fragt dieses Programm die Engine direkt und zeigt den Plan dort, wo die Arbeit ohnehin stattfindet.
• Sie lassen sich Software bauen. Von einem eigenen Entwickler, einem örtlichen Softwarehaus oder dem Lieferanten Ihrer Maschine. Die Engine API ist das, womit diese sich verbinden.

Wenn Sie nicht sicher sind, auf welcher Seite dieser Linie Sie stehen, hilft ein guter Test: Könnte der Plan entstehen, ohne dass ihn jemand anfordert? Wenn ja, ist die API relevant. Wenn immer ein Mensch entscheidet, einen Schnittplan zu erstellen, ist die App bereits das richtige Werkzeug.

Was sie leistet

Ihre Software sendet dieselben zwei Dinge, die Sie auch in der App eintippen würden — eine Liste von Teilen und eine Liste von Ausgangsmaterial — als JSON. Die Engine sendet eine vollständige Antwort zurück:

• Das komplette Layout. Jedes Teil, positioniert auf einer bestimmten Platte oder einem bestimmten Stab, inklusive der Angabe, ob es gedreht wurde.
• Einen Schnittplan. Nicht bloß ein Bild aus Rechtecken: die tatsächliche Guillotine-Schnittsequenz in der richtigen Reihenfolge, damit sich der Plan auf einer Plattensäge ausführen lässt.
• Die Zahlen. Wie viele Platten oder Stäbe der Auftrag braucht, die Auslastung in Prozent, wie viele Schnitte nötig sind und den Gesamtpreis des verwendeten Materials. Für Platten erhalten Sie zusätzlich die zwei ehrlichen Schnittzählungen — Schnittlinien, die Schnitte mit derselben Anschlagseinstellung zusammenfasst, und Sägedurchgänge, die jeden Durchgang zählt — sowie die gesamte gesägte Länge.
• Optional die Zeichnung. Fordern Sie include: ["svg","csv","dxf"] an, und die Antwort trägt das Layout zusätzlich als fertige Datei mit — eine eigenständige 2D-SVG-Zeichnung, ein DXF (R12/AC1009) oder eine CSV-Schnittliste — inline im JSON, ohne Speicherung und ohne zweiten Aufruf. (SVG nur in 2D.)
• Ihre eigenen Kennungen, zurückgegeben. Hängen Sie an jedes Teil oder jede Materialzeile ein meta-Objekt — eine Artikelnummer, eine Auftragsposition, eine Kundenreferenz — und es kommt bei jedem platzierten Stück und jeder Platte bzw. jedem Stab unverändert zurück, sodass der Plan mit Ihrem eigenen System zusammenpasst. Genau dieses Feld nehmen Sie, wenn Sie Ihr gesamtes Ausgangsmaterial senden, jede Zeile mit Ihrem eigenen Code kennzeichnen und zurücklesen möchten, welche Platte der Optimierer gewählt hat: Der Code gehört in stock[].meta und kommt auf sheets[].meta zurück. Auf die Platzierung wirkt er sich nie aus. Nutzen Sie zur Kennzeichnung nicht das Feld material: material ist eine harte Trennung — ein Teil wird ausschließlich aus Ausgangsmaterial desselben Materials geschnitten. Kennzeichnen Sie also jede stock-Zeile mit einem material, lassen die Teile aber ungekennzeichnet, kommt jedes Teil als unmatched zurück und das Ergebnis bleibt leer.

Es gibt vier Optimierungsmodi, alle entsprechen der App — einen für 2D-Platten, einen für 1D-Linearmaterial wie Stäbe, Profile und Rohre, einen für Holz, dessen Material einen Querschnitt hat, und True-Shape-Nesting (POST /v1/optimize/nest), das beliebige Polygone für Laser-, Plasma- und Wasserstrahlschneiden verschachtelt (der Nesting-Modus der App). Jeder Optimize-Endpoint hat außerdem einen kostenlosen Validierungs-Endpoint, der eine Anfrage prüft, ohne sie zu lösen (siehe unten).

Endpoints

Die Basis-URL ist https://api.cutoptim.com. Die Optimize- und Usage-Endpoints führen einen Schlüssel im Header Authorization: Bearer <key> mit; die Validate- und Health-Endpoints benötigen keinen Schlüssel.

Die meisten Aufrufe werden direkt mit dem fertigen Ergebnis beantwortet. Die einzige Ausnahme ist die asynchrone Engine max (siehe Drei Engines weiter unten): Eine max-Übermittlung gibt eine Job-ID zurück, und Sie fragen GET /v1/jobs/{id} ab, bis der Plan fertig ist.

Die Validate-Endpoints nehmen denselben Body wie der jeweils passende Optimize-Endpoint entgegen und prüfen ihn, ohne die Berechnung auszuführen: Eine fehlerhafte Anfrage kommt als 400 zurück und benennt genau das fehlerhafte Feld, eine wohlgeformte liefert valid: true samt Machbarkeitswarnungen (etwa ein Teil, das in kein Ausgangsmaterial passt). Sie kosten nichts und brauchen keinen Schlüssel, sodass Sie Ihre Payloads schon während des Aufbaus der Anbindung validieren können — noch bevor Sie überhaupt einen Schlüssel besitzen — und sicherstellen, dass eine Anfrage nicht abgewiesen wird, ohne einen Ihrer monatlichen Aufrufe zu verbrauchen.

Warum Holz einen eigenen Endpoint hat

Linearmaterial kennt nur eine Dimension, seine Länge — also kann jeder Stab jedes Teil liefern. Bei Holz ist das nicht so: Ein Teil 50×150 lässt sich aus einem Stab 50×100 nicht herausschneiden, wie viel Länge auch übrig bleibt. Der Holz-Endpoint nimmt deshalb bei jedem Teil und jeder Materialzeile beide Querschnittsseiten entgegen, teilt den Auftrag nach Querschnitt auf, ordnet jedem Abschnitt sein eigenes Material zu und gibt die Abschnitte getrennt zurück — jeden mit eigenen Stäben und eigenen Summen, neben den Zahlen für den gesamten Auftrag.

Zwei Details, die man vor der Anbindung kennen sollte:

• Die beiden Querschnittsseiten dürfen in beliebiger Reihenfolge kommen. 50×100 und 100×50 sind derselbe umgedrehte Balken und werden als ein Abschnitt behandelt. Ein Unterschied darin, wie Ihre Daten nun einmal erfasst sind, kann also kein Material verschwinden lassen.

• „Kein Material dieses Querschnitts“ und „hat nicht gepasst“ werden getrennt gemeldet. Das erste ist eine Materialmeldung, das zweite ein Kapazitätsproblem, und beide verlangen eine andere Lösung — in einer Liste vermischt schicken sie Ihren Anwender an die falsche Stelle.

Sie könnten das mit mehreren eigenen 1d-Aufrufen annähern, indem Sie die Teile selbst gruppieren. Das kostet pro Querschnitt eine Anfrage aus Ihrem Kontingent statt einer für den Auftrag, verlagert die Materialzuordnung in Ihren Code und liefert eine Auftragssumme, die Sie selbst zusammensetzen müssten — und die nicht zwangsläufig mit dem übereinstimmt, was die CutOptim-App für denselben Auftrag anzeigt.

Teile aus einer CAD-Datei

Der Nesting-Endpoint nimmt nicht nur Koordinaten entgegen. Ein Teil darf stattdessen ein source tragen — ein SVG- oder DXF-Dokument —, und der Server liest dessen Umriss samt aller Löcher aus der Datei heraus. Es ist derselbe Leser, den die App verwendet, wenn Sie eine Zeichnung auf ihren Nesting-Modus ziehen; eine Teilebibliothek, die bereits als CAD-Dateien vorliegt, muss also nicht erst in Koordinatenlisten umgeschrieben werden.

Die Datei ersetzt nur die Geometrie. Menge, Material, erlaubte Drehungen und Ihre eigenen Metadaten bleiben gewöhnliche Felder der Teilezeile, genau wie beim Senden von Koordinaten. Eine Datei beschreibt ein Teil; enthält eine einzelne Zeichnung mehrere getrennte Bauteile, zerlegt POST /v1/import/nest sie zuerst in fertige Teilezeilen — und dieser Aufruf braucht einen Schlüssel, verbraucht aber keine Anfrage aus Ihrem Monatskontingent.

Nichts wird gespeichert. Die Datei existiert ausschließlich als die Anfrage selbst: sie wird im Arbeitsspeicher gelesen und ist fort, sobald die Antwort geschrieben ist. Es bleibt keine Kopie auf einer Festplatte oder in einer Datenbank, nichts landet in einem Log, und es gibt hinterher nichts zu löschen. Mit Einheiten verfahren wir ebenso — eine DXF-Datei kann Millimeter oder Zoll angeben, und wir melden, was sie sagte, rechnen Koordinaten aber nie um, denn kein Wert in dieser API trägt eine Einheit.

Jedes Mal dieselbe Antwort

Die Engine ist deterministisch: Dieselbe Eingabe liefert immer dieselbe Ausgabe. Es gibt keinen Zufall und keine Uhr im Algorithmus.

Das klingt akademisch, ist aber der praktische Grund, darauf aufzubauen. Es bedeutet, dass Ergebnisse gecacht werden können — wenn Sie genau diesen Auftrag schon einmal gefragt haben, können Sie die Antwort bedenkenlos wiederverwenden, statt erneut zu fragen. Es bedeutet außerdem, dass sich die Anbindung testen lässt: Ein Plan kann mit einem als korrekt bekannten Ergebnis verglichen werden, und ein Unterschied ist ein echter Unterschied, kein Rauschen. Software, die einem Kunden am Montag einen Preis nennt, nennt am Freitag denselben Preis.

Drei Engines

Die API bietet die Wahl zwischen dreien — zwei synchronen und einer asynchronen —, und der Unterschied ist keine Frage der Qualität: Er ist ein Kompromiss zwischen Geschwindigkeit und der Frage, ob sich das Ergebnis auf einer Plattensäge schneiden lässt.

• heuristic ist der Standard und dieselbe Engine, die auch die App verwendet. Sie erzeugt Guillotine-Layouts: höchste Auslastung, jedes Layout auf der Plattensäge schneidbar und immer ein vollständiger Schnittplan. Synchron.
• balanced ist optional und muss ausdrücklich angefordert werden. Sie nutzt stattdessen freie Verschachtelung, was bei sehr großen Aufträgen dramatisch schneller ist — gemessen rund 25× schneller bei einem Auftrag mit 2.000 Teilen — auf Kosten einer geringfügig niedrigeren Auslastung. Der wichtige Haken: Ihre Layouts lassen sich häufig nicht von Kante zu Kante schneiden, und für diese gibt sie überhaupt keinen Schnittplan zurück. Synchron.
• max ist optional und nur 2D. Es ist eine serverseitige Baumsuche, die das bewiesene Optimum bei weit mehr Aufträgen erreicht als der Standard, und ihre Layouts lassen sich weiterhin auf einer Plattensäge schneiden. Der Preis ist Zeit: Eine max-Berechnung dauert Sekunden bis zu einer Minute, sie antwortet also nicht in der Response. Stattdessen gibt POST /v1/optimize/2d mit engine: "max" eine Job-ID zurück, und Sie fragen GET /v1/jobs/{id} ab, bis sie fertig ist. Es ist weiterhin deterministisch. Greifen Sie dazu, wenn bei einem großen, wertvollen Auftrag das Warten auf die letzten paar Platten sich lohnt. Sie modelliert ein Bestandsformat in voller Plattengröße mit unbegrenztem Vorrat. Enthält die Anfrage zusätzlich ein zweites Bestandsformat, seitenweisen trim, begrenzten Bestand (respectStock), Materialien oder Faserrichtungsgruppen, wird sie vorab mit einem 400 abgelehnt, das genau benennt, was sie nicht kann — bevor ein Aufruf berechnet wird. Schicken Sie solche Aufträge an heuristic, das alles davon abbildet.

Limits

Jede Anfrage ist begrenzt, damit ein aus dem Ruder gelaufener Auftrag klar fehlschlägt statt hängen zu bleiben:

Zugang erhalten

Beginnen Sie auf der Engine-API-Seite. Die Engine API wird getrennt von den App-Tarifen abgerechnet, und kein Tarif-Upgrade schaltet sie frei.

1. Abonnieren oder anfragen. Der Abschluss auf der Engine-API-Seite ist der schnellste Weg — sie läuft mit einer Testphase, und der Zugang landet von selbst auf Ihrem Konto. Möchten Sie Ihre Anbindung lieber vorher beschreiben oder brauchen Sie ein Volumen über dem Standardtarif, nehmen Sie stattdessen Kontakt auf und sagen Sie, was Sie anbinden möchten und wie viele Schnittpläne pro Monat das ungefähr braucht.
2. Der Zugang wird Ihrem Konto hinzugefügt. Sonst ändert sich an Ihrem Konto nichts.
3. Legen Sie einen Schlüssel an. Sobald Ihr Konto API-Zugang hat, erscheint in Ihrem Dashboard eine Karte API-Schlüssel. Dort erstellen, benennen und löschen Sie Schlüssel selbst.
4. Kopieren Sie den Schlüssel sofort. Der vollständige Schlüssel wird genau ein einziges Mal angezeigt, in dem Moment, in dem Sie ihn erstellen.

Behandeln Sie einen Schlüssel wie ein Passwort: Er gehört in die Konfiguration Ihrer Software, nicht in eine E-Mail, eine Tabelle oder einen Screenshot.

Was die API-Schlüssel-Karte im Dashboard tut

Drei Bedienelemente — und es lohnt sich, genau zu sagen, was jedes bewirkt, besonders das letzte, von dem viele annehmen, es berühre die Abrechnung. Tut es nicht.

• Schlüssel erstellen. Erzeugt einen neuen Schlüssel und zeigt ihn einmal an, direkt dort. Der Name (ERP-Anbindung, Staging) dient nur dazu, die Schlüssel später auseinanderzuhalten. Bis zu 10 aktive Schlüssel pro Konto.
• Der Verbrauchsbalken. Zwei Zahlen: der Gesamtverbrauch Ihres Kontos im Kalendermonat gegenüber dem Kontingent, und je Schlüssel, wie viel dieser verbraucht hat. Die Zahl pro Schlüssel beantwortet, welche Anbindung das Kontingent aufbraucht — sie ist kein eigenes Budget.
• Widerrufen. Setzt genau diesen Schlüssel ab dem nächsten Aufruf außer Kraft. Die Zeile bleibt sichtbar, damit die Historie nicht verloren geht.

Ein Kontingent für das Konto, nicht eines je Schlüssel

Jeder aktive Schlüssel Ihres Kontos schöpft aus demselben monatlichen Kontingent. Ein zweiter Schlüssel schafft kein zweites Kontingent — Schlüssel gibt es, damit Sie Staging von Produktion trennen, jeder Anbindung ein eigenes Zugangsmittel geben und einen davon widerrufen können, ohne die anderen zu stören.

GET /v1/usage meldet den Stand des Kontos (used, limit, remaining) und beantwortet damit die Frage, die Sie tatsächlich haben — wie viel bleibt, bevor Aufrufe fehlschlagen — unabhängig davon, mit welchem Schlüssel Sie gefragt haben. Ist das Kontingent aufgebraucht, antwortet jeder Schlüssel mit 402, nicht nur der, der es verbraucht hat.

Preis und Kontingent

Die Engine API wird getrennt von den App-Tarifen abgerechnet, mit einer festen Anzahl von Anfragen pro Monat. Der aktuelle Preis, das monatliche Anfragekontingent und die Länge der Testphase stehen alle auf der Engine-API-Seite — diese Seite liest sie aus unserer Preiskonfiguration, es ist also immer die zutreffende Zahl.

Für die technischen Details — die genaue Struktur von Request und Response, jede Option, alle Fehlercodes und wie die Versionierung funktioniert — siehe die API-Referenz.

Was sich dadurch nicht ändert

Das sei ausdrücklich gesagt, denn die Engine API wird leicht als Änderung am Produkt missverstanden:

• Der Optimierer in der App ist unverändert. Er läuft weiterhin in Ihrem Browser, genau wie bisher.
• Free, Pro und Werkstatt sind unberührt. Sie enthalten weiterhin den Optimierer in der App, mit denselben Limits wie bisher. Es wurde nichts hinter die API verlegt.
• Nichts, was Sie in der App tun, verbraucht API-Anfragen. Das monatliche API-Kontingent wird ausschließlich von Aufrufen berührt, die Ihre eigene Software macht.

Die Engine API ist eine Ergänzung für Menschen, die CutOptim in andere Software einbinden. Wenn Sie das nicht sind, hat sich nichts geändert.