Engine API

Mindaz, amit a CutOptim a böngésződben végez, egyetlen számításból indul ki: adott ez a darablista és ez az alapanyag — mi a legjobb módja felszabni őket? Az Engine API pontosan ezt a számítást teszi elérhetővé az interneten, hogy egy másik program is feltehesse a kérdést, és megkapja rá a választ — böngésző nélkül, kattintás nélkül, bejelentkezett felhasználó nélkül.

Ez a teljes lényeg. Nem új optimalizáló, nem jobb optimalizáló, és nem is egy nagyobb csomag. Ugyanaz a motor, amelyet ember helyett szoftver ér el.

Nekem szól ez?

A CutOptim felhasználóinak elsöprő többségénél az őszinte válasz: nem. Ha a munkanapod abból áll, hogy megnyitod a CutOptimot, beírod a darabokat és az alapanyagot, majd kinyomtatod vagy exportálod a tervet, akkor az app maga a termék, és ez az oldal nem érint téged.

Az Engine API egyetlen helyzetre szól: a vágástervnek egy olyan szoftverben kell megjelennie, amelyet már használsz, anélkül hogy bárki felkeresné a CutOptimot. A gyakorlatban ez kétféle embert jelent:

• Már használsz olyan szoftvert, amelybe a vágásterv tartozik. Egy ERP-t, amely a megrendeléseidet tartja nyilván, egy árazó eszközt, amely a munkákat kalkulálja, vagy magának a gépnek a szoftverét. Ahelyett, hogy egy kezelő újra begépelné ugyanazt a darablistát a CutOptimba, az a program közvetlenül a motort kérdezi meg, és ott mutatja a tervet, ahol a munka egyébként is zajlik.
• Szoftvert fejlesztetsz magadnak. Házon belüli fejlesztővel, egy helyi szoftvercéggel vagy a géped beszállítójával. Az Engine API az, amihez ők csatlakoznak.

Ha nem vagy biztos benne, melyik oldalon állsz, itt egy jó próba: megjelenhet-e a terv anélkül, hogy bárki kérné? Ha igen, akkor az API szóba jöhet. Ha mindig egy ember dönt úgy, hogy vágástervet készít, akkor az app már most is a megfelelő eszköz.

Mit ad

A szoftvered ugyanazt a két dolgot küldi be JSON formában, amit az appba is beírnál: a darabok listáját és az alapanyag listáját. A motor pedig teljes választ ad vissza:

• A teljes elrendezést. Minden darab a saját helyén, egy konkrét táblán vagy rúdon, azzal együtt, hogy el kellett-e forgatni.
• A vágástervet. Nem csak téglalapok képét: a tényleges guillotine vágási sorrendet, lépésenként, hogy a terv panelfűrészen végrehajtható legyen.
• A számokat. Hány táblát vagy rudat visz el a munka, mennyi a kihasználás százalékban, hány vágás kell hozzá, és mennyi a felhasznált anyag teljes ára. Lapoknál megkapod a kétféle őszinte vágásszámot is — a vágásvonalakat, amelyek összevonják az egy ütköző-beállításba eső vágásokat, és a fűrészeléseket, amelyek minden áthaladást számolnak —, valamint a teljes vágáshosszt.
• Opcionálisan a rajzot. Kérj include: ["svg","csv","dxf"] értéket, és a válasz kész fájlként is viszi az elrendezést — önálló 2D SVG rajzot, R12/AC1009 DXF-et vagy CSV vágásjegyzéket —, a JSON-ba ágyazva, tárolás és második hívás nélkül. (Az SVG csak 2D.)
• A saját azonosítóidat, visszaadva. Csatolj egy meta objektumot — egy cikkszámot, egy rendelés-sort, egy vevői hivatkozást — bármelyik darab- vagy alapanyag-sorhoz, és változatlanul visszakapod minden elhelyezett darabon és minden táblán vagy rúdon, így a terv egyezik a saját rendszereddel. Ezt a mezőt használd akkor is, ha az összes tábládat beküldöd, mindegyiket a saját kódoddal jelölöd meg, és vissza akarod olvasni, melyik táblát választotta az optimalizáló — tedd a kódot a stock[].meta mezőbe, és a sheets[].meta mezőn kapod vissza. Az elhelyezést soha nem befolyásolja. Azonosításra ne a material mezőt használd: a material kemény szétválasztás — egy darab kizárólag azonos material értékű alapanyagból vágódik ki —, így ha minden alapanyag-sort megjelölsz vele, de a darabokat nem, akkor minden darab unmatched státusszal jön vissza, az eredmény pedig üres lesz.

Négy számítás van, és mind a négy az app egy-egy módjának felel meg — egy a 2D lapokra, egy az 1D lineáris anyagra (rúd, profil, cső), egy a faanyagra, amelynek keresztmetszete van, és egy a true-shape neszelésre (POST /v1/optimize/nest), amely tetszőleges poligonokat illeszt össze lézer-, plazma- és vízsugárvágáshoz. Minden optimalizáló végponthoz tartozik egy ingyenes ellenőrző végpont is, amely megoldás nélkül ellenőrzi a kérést (lásd lentebb).

Végpontok

Az alap-URL a https://api.cutoptim.com. Az optimalizáló és a usage végpont egy kulcsot visz az Authorization: Bearer <key> fejlécben; a validate és a health végponthoz nem kell kulcs.

A legtöbb hívásra közvetlenül a kész eredmény a válasz. Az egyetlen kivétel az aszinkron max motor (lásd lentebb a Három motor szakaszt): egy max beküldés egy feladatazonosítót ad vissza, amelyet a GET /v1/jobs/{id} végponttal kérdezel le, amíg a terv el nem készül.

A validate végpontok ugyanazt a törzset veszik át, mint a hozzájuk tartozó optimalizáló végpont, és a megoldás lefuttatása nélkül ellenőrzik: egy hibás kérés 400-zal tér vissza, megnevezve a pontos hibás mezőt, egy jól formázott pedig valid: true értéket ad, plusz megvalósíthatósági figyelmeztetéseket (például egy darab, amely egyetlen alapanyagba sem fér bele). Semmibe nem kerülnek, és nem kell hozzájuk kulcs, tehát az integráció fejlesztése közben — még mielőtt egyáltalán kulcsod lenne — ellenőrizheted a törzseidet, és megbizonyosodhatsz róla, hogy egy kérést nem utasítunk el, anélkül hogy elköltenél egy havi hívást.

Miért van a fának saját végpontja

A lineáris anyag egy dimenziót ismer, a hosszt, tehát bármelyik rúd bármelyik darabot adhatja. A faanyagnál ez nem így van: egy 50×150-es darab nem jöhet ki egy 50×100-as rúdból, akármennyi hossz marad is rajta. A fa-végpont ezért minden darabnál és minden készlet-sornál átveszi a keresztmetszet mindkét oldalát, keresztmetszetenként szétválasztja a munkát, minden szekcióhoz a saját készletét párosítja, és a szekciókat külön adja vissza — mindegyiket a saját rúdjaival és a saját összesítésével, a teljes munka számai mellett.

Két részlet, amit érdemes tudni az integrálás előtt:

• A keresztmetszet két oldala tetszőleges sorrendben küldhető. Az 50×100 és a 100×50 ugyanaz a gerenda megfordítva, és egy szekcióba kerül. Így az, hogy az adataid éppen hogyan lettek felvéve, nem tüntethet el alapanyagot.

• A „nincs ilyen keresztmetszetű készlet” és a „nem fért el” külön jelenik meg. Az első hiányzó anyag, a második kapacitás-probléma, és másképp kell javítani — egy listába keverve rossz helyre küldenék a felhasználódat.

Ezt közelíthetnéd több saját 1d hívással is, ha magad csoportosítod a darabokat. Az keresztmetszetenként egy kérésbe kerülne a kvótádból egy helyett az egész munkára, a készlet-párosítást a te kódodba tolná, és olyan összesítést adna, amit magadnak kellene összeraknod — és ami nem feltétlenül egyezne azzal, amit a CutOptim app mutat ugyanarra a munkára.

Darabok CAD-fájlból

A nesting végpont nem csak koordinátákat fogad. Egy darab source mezőt is vihet helyettük — egy SVG- vagy DXF-dokumentumot —, és a szerver ebből olvassa ki a kontúrt és a benne lévő lyukakat. Ugyanaz a beolvasó, amit az alkalmazás használ, amikor a Nesting módjára ejtesz egy rajzot, tehát egy CAD-fájlokban már meglévő darab-könyvtárat nem kell előbb koordináta-listákká alakítani.

A fájl csak a geometriát váltja ki. A darabszám, az anyag, az engedélyezett forgatások és a saját metaadatod ugyanolyan mezők maradnak a darab során, mint amikor koordinátákat küldesz. Egy fájl egy darabot ír le; ha egyetlen rajz több különálló alkatrészt tartalmaz, a POST /v1/import/nest előbb kész darab-sorokra bontja — és ez a hívás kulcsot igényel, de nem fogyaszt kérést a havi keretedből.

Semmi nem tárolódik. A fájl kizárólag magaként a kérésként létezik: a memóriában olvassuk be, és mire a válasz megíródik, megszűnik. Nem marad másolat lemezen vagy adatbázisban, nem kerül naplóba, és utólag nincs mit törölni. A mértékegységgel ugyanígy bánunk — egy DXF deklarálhat millimétert vagy hüvelyket, és mi jelentjük, amit mondott, de a koordinátákat sosem váltjuk át, mert ebben az API-ban egyetlen érték sem hordoz mértékegységet.

Mindig ugyanaz a válasz

A motor determinisztikus: ugyanaz a bemenet mindig ugyanazt a kimenetet adja. Nincs véletlenszerűség, és nincs óra az algoritmusban.

Ez elméletinek hangzik, de éppen ez a gyakorlati oka annak, hogy érdemes rá építeni. Azt jelenti, hogy az eredmények cache-elhetők — ha ugyanerre a munkára már rákérdeztél, biztonsággal újrahasználhatod a választ ahelyett, hogy megint megkérdeznéd. Azt is jelenti, hogy az integráció tesztelhető: egy terv összehasonlítható egy ismerten helyes eredménnyel, és ha eltérés van, az valódi eltérés, nem zaj. Az a szoftver, amely hétfőn árat ad a vevőnek, pénteken is ugyanazt az árat fogja adni.

Három motor

Az API motorválasztást kínál. Az első kettő szinkron módon fut; a harmadik aszinkron. A különbség nem minőségi kérdés: kompromisszum a sebesség, aközött, hogy az eredmény felszabható-e panelfűrészen, és aközött, hogy mennyire közelíti meg az elméleti minimumot.

• A heuristic az alapértelmezett, és ugyanaz, amit az app is használ. Guillotine elrendezéseket ad: legjobb kihasználás, minden elrendezés fűrésszel vágható, és mindig teljes vágásterv. Szinkron.
• A balanced külön kérésre kapcsol be. Helyette szabad beágyazást használ, ami nagy munkákon jóval gyorsabb — 2000 darabos munkán mérve körülbelül 25× — kissé rosszabb kihasználás árán. A fontos csavar: az elrendezései gyakran nem vághatók éltől élig, ezért azoknál egyáltalán nem ad vágástervet. Szinkron.
• A max külön kérésre kapcsol be, és csak 2D. Szerver-oldali fakeresés, amely az alapértelmezettnél jóval több munkán éri el a bizonyított optimumot, és az elrendezései továbbra is guillotine-vághatók. Az ára az idő: egy max számítás másodpercektől egy percig tart, ezért nem a válaszban felel. Helyette a POST /v1/optimize/2d az engine: "max" értékkel egy feladatazonosítót ad vissza, amelyet a GET /v1/jobs/{id} végponttal kérdezel le, amíg el nem készül. Továbbra is determinisztikus. Akkor nyúlj hozzá, ha egy nagy, értékes munkánál megéri várni az utolsó néhány tábláért. Egyetlen készlet-formátumot modellez, teljes lapméreten, korlátlan darabszámmal, ezért ha a kérés ezen felül második készlet-formátumot, oldalankénti trim-et, korlátozott készletet (respectStock), anyagot vagy szálirány-csoportot is visz, azt előre elutasítja egy 400-zal, ami pontosan megnevezi, mit nem tud — még mielőtt a hívás terhelődne. Az ilyen munkákat küldd a heuristic motornak, az mindegyiket kezeli.

Korlátok

Minden kérésnek van felső határa, így egy elszaladó munka világosan elbukik, nem pedig lefagy:

Hogyan kapok hozzáférést

Kezdd az Engine API oldalon. Az Engine API az app csomagjaitól külön számlázódik, és nincs olyan csomagváltás, amely bekapcsolná.

1. Fizess elő, vagy kérdezz. Az Engine API oldalon történő előfizetés a leggyorsabb út — próbaidőszakkal indul, és a hozzáférés magától felkerül a fiókodra. Ha inkább előbb leírnád az integrációdat, vagy a standard csomagnál nagyobb mennyiség kell, vedd fel velünk a kapcsolatot, és írd le, mit szeretnél összekötni, és körülbelül hány vágástervre lesz szüksége havonta.
2. A hozzáférés felkerül a fiókodra. A fiókodon semmi más nem változik.
3. Készíts kulcsot. Amint a fiókod API-hozzáférést kapott, egy API-kulcsok kártya jelenik meg az irányítópultodon. A kulcsokat ott magad készíted el, nevezed el és törlöd.
4. Másold ki a kulcsot azonnal. A teljes kulcsot pontosan egyszer mutatjuk meg: a létrehozás pillanatában.

A kulcsot kezeld úgy, mint egy jelszót: a szoftvered konfigurációjában van a helye, nem e-mailben, táblázatban vagy képernyőképen.

Mit csinál az API-kulcsok kártya az irányítópultodon

Három vezérlő — és érdemes pontosan kimondani, melyik mit változtat, különösen az utolsót, amiről sokan azt hiszik, a számlázáshoz nyúl. Nem nyúl.

• Kulcs létrehozása. Létrehoz egy új kulcsot, és egyetlen egyszer meg is mutatja, ott helyben. A név (ERP-integráció, staging) kizárólag arra való, hogy később meg tudd különböztetni a kulcsaidat. Fiókonként legfeljebb 10 aktív kulcs.
• A használati sáv. Két szám: a fiókod havi összesített felhasználása a kvótához mérve, és kulcsonként az, hogy az a kulcs mennyit fogyasztott. A kulcsonkénti szám arra válaszol, hogy melyik integráció eszi a keretet — nem külön költségvetés.
• Visszavonás. A következő hívástól kezdve leállítja azt az egy kulcsot. A sor látható marad, hogy az előzménye ne vesszen el.

Egy kvóta a fiókra, nem kulcsonként egy

A fiókod minden aktív kulcsa ugyanabból a havi keretből fogyaszt. Egy második kulcs nem hoz létre második kvótát — a kulcsok arra valók, hogy szétválaszd a stagingot az élestől, minden integrációnak saját azonosítót adj, és egyet visszavonhass anélkül, hogy a többit zavarnád.

A GET /v1/usage a fiók állását adja vissza (used, limit, remaining), tehát arra a kérdésre válaszol, ami valóban érdekel — mennyi maradt, mielőtt a hívások elkezdenek elhasalni —, függetlenül attól, melyik kulccsal kérdeztél. Ha elfogy a keret, minden kulcs 402-t ad, nem csak az, amelyik elhasználta.

Ár és kvóta

Az Engine API-t az app csomagjaitól külön számlázzuk, fix havi kéréskerettel. Az aktuális árat, a havi kéréskvótát és a próbaidő hosszát az Engine API oldal tartalmazza — az az oldal az árazási konfigurációnkból olvassa ki őket, tehát ott mindig a pontos szám szerepel.

A technikai részletekhez — a pontos kérés- és válaszszerkezethez, minden beállításhoz, az összes hibakódhoz és a verziózás működéséhez — lásd az API-referenciát.

Amit ez nem változtat meg

Érdemes világosan kimondani, mert az Engine API-t könnyű a termék megváltozásának félreolvasni:

• Az appban futó optimalizáló változatlan. Ugyanúgy a böngésződben fut, mint eddig.
• Az Ingyenes, a Pro és a Műhely csomagot nem érinti. Továbbra is tartalmazzák az appban futó optimalizálót, a korábbi korlátokkal. Semmi nem került az API mögé.
• Amit az appban teszel, az nem fogyaszt API-kérést. A havi API-kvótához csak a saját szoftvered hívásai nyúlnak hozzá.

Az Engine API azoknak szóló kiegészítés, akik a CutOptimot más szoftverbe illesztik. Ha nem közéjük tartozol, számodra semmi nem változott.