Engine API

Sve što CutOptim radi u vašem pregledniku počinje jednim izračunom: s obzirom na ove dijelove i ovu zalihu, koji je najbolji način da ih izrežemo? Engine API izlaže upravo taj izračun preko interneta, tako da neki drugi program može postaviti pitanje i dobiti odgovor natrag — bez preglednika, bez klikanja, bez ikoga prijavljenog.

To je cijela zamisao. To nije novi optimizator, nije bolji optimizator i nije veći plan. To je isti engine, dostupan softveru umjesto osobi.

Je li ovo za mene?

Za veliku većinu korisnika CutOptima, iskren odgovor je ne. Ako se vaš radni dan sastoji od otvaranja CutOptima, upisivanja dijelova i zalihe te ispisa ili izvoza plana, aplikacija je proizvod, a ova stranica vam je nevažna.

Engine API je za jednu situaciju: planovi rezanja moraju se pojaviti unutar softvera koji već koristite, bez da itko posjeti CutOptim. U praksi to znači jednu od dvije osobe:

• Već pokrećete softver kojemu plan rezanja pripada iznutra. ERP koji drži vaše narudžbe, alat za izradu ponuda koji cijeni poslove ili vlastiti softver stroja. Umjesto da operater ponovno upisuje isti popis dijelova u CutOptim, taj program izravno pita engine i prikazuje plan ondje gdje se posao već odvija.
• Softver se izrađuje za vas. Od strane internog razvijatelja, lokalne softverske tvrtke ili dobavljača vašeg stroja. Engine API je ono na što se oni povezuju.

Ako niste sigurni na kojoj strani te crte se nalazite, dobar test: može li se plan pojaviti bez da ga itko zatraži? Ako da, API je relevantan. Ako osoba uvijek odlučuje izraditi plan rezanja, aplikacija je već pravi alat.

Što radi

Vaš softver šalje iste dvije stvari koje biste upisali u aplikaciju — popis dijelova i popis zalihe — kao JSON. Engine šalje natrag potpun odgovor:

• Cijeli raspored. Svaki dio, postavljen na određenu ploču ili šipku, uključujući je li zakrenut.
• Plan rezanja. Ne samo sliku pravokutnika: stvarni giljotinski slijed rezanja, po redu, tako da se plan može izvesti na formatnoj pili.
• Brojke. Koliko ploča ili šipki posao zahtijeva, postotak iskoristivosti, koliko je rezova potrebno i ukupnu cijenu upotrijebljenog materijala. Za ploče dobivate i dva iskrena broja rezova — linije rezanja, koje spajaju rezove koji dijele jednu postavku graničnika, i prolaze pilom, koji broje svaki prolaz — uz ukupnu ispiljenu duljinu.
• Neobavezno, crtež. Zatražite include: ["svg","csv","dxf"] i odgovor također nosi raspored kao gotovu datoteku — samostalni 2D SVG crtež, R12/AC1009 DXF ili CSV popis rezanja — ugrađen u JSON, bez pohrane i bez drugog poziva. (SVG je samo 2D.) Uz 2D zahtjeve možete tražiti i labels (podatke naljepnica po komadu), planHash (otisak plana), pdf (PDF plana rezanja) i labelsPdf (PDF naljepnica) — PDF-ovi kodirani u base64, nacrtani istim kodom kao u aplikaciji.
• Vaši vlastiti identifikatori, vraćeni. Priložite meta objekt — broj artikla, redak narudžbe, referencu kupca — bilo kojem retku dijela ili zalihe i vraća se nepromijenjen na svakom postavljenom komadu i svakoj ploči ili šipki, pa se plan podudara s vašim vlastitim sustavom. To je polje koje treba upotrijebiti kad želite poslati sve svoje ploče, svaku označiti vlastitom šifrom i pročitati natrag koju je ploču optimizator odabrao — stavite šifru u stock[].meta i vraća se na sheets[].meta. Nikad ne utječe na postavljanje. Nemojte koristiti polje material za identifikaciju: material je čvrsta podjela (dio se reže samo iz zalihe istog materijala), pa označavanje svakog retka zalihe materijalom uz dijelove koji ostaju neoznačeni čini da se svaki dio vrati kao unmatched, a rezultat bude prazan.

Postoje četiri načina optimizacije, svi odgovaraju aplikaciji — jedan za 2D ploče, jedan za 1D linearni materijal poput šipki, profila i cijevi, jedan za građu, gdje materijal ima poprečni presjek, i nesting po stvarnom obliku (POST /v1/optimize/nest), koji slaže proizvoljne poligone za lasersko, plazma i rezanje vodenim mlazom (Nesting način aplikacije). Svaki endpoint optimizacije također ima besplatan validacijski endpoint koji provjerava zahtjev bez rješavanja (vidi niže).

Endpoints

Osnovni URL je https://api.cutoptim.com. Endpointi za optimizaciju i potrošnju nose ključ u zaglavlju Authorization: Bearer <key>; validacijskim i health endpointima ne treba ključ.

Na većinu poziva izravno se odgovara gotovim rezultatom. Jedina je iznimka asinkroni max engine (vidi Tri enginea u nastavku): predaja max posla vraća id posla, a vi ispitujete GET /v1/jobs/{id} dok plan ne bude spreman.

Validacijski endpointi uzimaju isto tijelo kao pripadajući endpoint za optimizaciju i provjeravaju ga bez pokretanja rješavanja: neispravno oblikovan zahtjev vraća se kao 400 s imenom točno pogrešnog polja, a ispravno oblikovan vraća valid: true uz upozorenja o izvedivosti (na primjer, dio koji ne stane ni u jednu zalihu). Ne koštaju ništa i ne trebaju ključ, pa možete validirati svoje payloade dok gradite integraciju — prije nego što uopće imate ključ — i potvrditi da zahtjev neće biti odbijen bez trošenja jednog od svojih mjesečnih poziva.

Smjer vlakana na pločama

Šperploče i furnirane ploče imaju vlakna, a vidljivi dio mora se izrezati tako da vlakna teku u pravom smjeru. Na POST /v1/optimize/2d pošaljite grain na retku zalihe — "w" ili "h", strana ploče uz koju teku vlakna — te grain na dijelu, stranu dijela uz koju moraju teći. Svaki takav dio postavlja se tako da njegova vlakna teku uz vlakna njegove ploče: okrenut za 90° kad je to potrebno (rotated: true na postavljenom dijelu, kao i kod svakog okretanja), a rotatable se za njega zanemaruje. Dio bez grain i dalje se slobodno rotira, i na retku zalihe bez grain (MDF, melamin); dio S grain i na takvom retku zadržava orijentaciju koju mu daju retci s vlaknima — material razdvaja ploče s vlaknima od glatkih. Dio koji bi stao samo okrenut za 90° protiv vlakana vraća se u unplaced u poslanoj veličini, redak u warnings ga imenuje, a POST /v1/validate/2d to javlja prije nego što se potroši poziv.

U jednom zahtjevu mogu stajati retci zalihe čija vlakna teku u različitim smjerovima — 2440 × 1220 s "w" i 1220 × 2440 s "h" — a svaka ploča vraća se u orijentaciji svojeg retka, s grain u sheets[]. Uz material dio je vezan uz vlakna samo kad njegov vlastiti materijal ima ploču s vlaknima. grain dijela bez ploče s vlaknima u zahtjevu nema učinka, a redak u warnings to navodi. options.trim i prisiljeni options.firstCut primjenjuju se na svaku ploču u orijentaciji vlastitog retka, i na retku čija vlakna teku u drugom smjeru. Način Smjer vlakana u aplikaciji CutOptim izvodi isti kod. (od 2026-10-02.)

Usklađivanje žice na pločama (matched sets)

Smjer vlakana drži žicu svakog dijela u pravom smjeru. Neke fronte trebaju više od toga: fronta ladice iznad dvoja vrata čiji se uzorak nastavlja s jednog na drugi, kao da su sva tri još uvijek jedna ploča. Na POST /v1/optimize/2d tim redcima dijelova dodajte id i imenujte ih u matchedSets:

{
  "parts": [
    { "id": "DF", "name": "Drawer front", "w": 48.125, "h": 6 },
    { "id": "DOOR", "name": "Door", "w": 24, "h": 30, "qty": 2 },
    { "name": "Shelf", "w": 22.5, "h": 11.25, "qty": 4 }
  ],
  "stock": [{ "w": 96, "h": 48, "qty": 2, "grain": "w" }],
  "options": { "kerf": 0.125 },
  "matchedSets": [
    { "id": "base-1", "name": "Base cabinet fronts", "grain": "w",
      "layout": { "dir": "rows", "lines": [["DF"], ["DOOR", "DOOR"]] } }
  ]
}

• Što je set. layout.lines navodi članove prema parts[].id. Uz dir: "rows" svaka linija je red članova jedan uz drugoga, a redovi se slažu odozgo prema dolje, pa je [["DF"], ["DOOR", "DOOR"]] fronta ladice iznad dvoja vrata; uz "cols" svaka linija je stupac, a stupci stoje jedan uz drugoga. Dio se u jednom setu može pojaviti više puta (Door, Door), ali može pripadati samo jednom setu. qty (zadano 1) je koliko primjeraka trebate — tri jednaka elementa su qty: 3 — a qty samih dijelova mora pokriti svaki primjerak. Set ima najmanje 2 i najviše 24 člana, a jedan zahtjev prima najviše 50 setova.
• Kako se reže. Set prolazi kroz optimizator kao jedan pravokutnik — blok — i vraća se kao njegovi članovi, razmaknuti točno za jedan kerf, iz jednog komada ploče. grain seta ("w" ili "h", uz širinu ili visinu bloka) određuje smjer svakog člana; vlastiti grain člana ne koristi se unutar seta, a upozorenje imenuje svakog člana koji se nadjačava. Bez grain seta blok se smije okretati kad je svaki član rotatable. installGap je razmak između članova na elementu (zadano: kerf); na ploči i dalje stoje jedan kerf udaljeni.
• Što se vraća. Svaki postavljeni član nosi matchedSet: id seta, koji je instance i njegov position redoslijedom čitanja na prednjoj strani elementa — odozgo prema dolje, slijeva nadesno, od 1 — te hint poput "left" ili "right" gdje je to jednoznačno. Odgovor dodaje sažetak matchedSets, jedan unos po setu: njegov letter (A, B … redoslijedom u zahtjevu), koliko je primjeraka rezano kao jedan blok (asBlock), podijeljeno ili ostavljeno nepostavljeno, veličinu bloka i warnings seta. Kad blok ne stane ni na jednu ploču zalihe, onMiss: "split" (zadano) postavlja članove jedan po jedan uz upozorenje, a onMiss: "unplaced" ih navodi u unplaced.
• Upozorenja, a ne pogreške. Veličina koja se ne podudara upozorenje je na setu, a ne odbijanje. Svaki redak počinje svojim kodom — align: (linije nisu poravnate), gap: (kerf je širi od installGap), grain:, split:, unplaced:, unmatched: (nema zalihe materijala seta), priority: i grainGroup: — a align i gap ocjenjuju se na 1/64 vaše jedinice ili četvrtini kerfa, što god je manje. Set koji se uopće ne može složiti — id člana koji nijedan dio ne nosi, referencirani id na dva dijela, manje od dva člana, premalo dijelova za qty — je 400 koji imenuje točno polje, prije nego što se poziv naplati.
• parts[].id je sigurno slati. Provjerava se samo id na koji se set poziva (neprazan ispisiv niz od najviše 64 znaka ili cijeli broj, na točno jednom dijelu). Svaki drugi id zanemaruje se, što god sadržavao, pa brojevi artikala iz vašeg ERP-a mogu ostati na redcima. A ništa se ne mijenja za zahtjev bez setova: značajku uključuje samo neprazan niz matchedSets — odsutan, null, [] ili bilo koja vrijednost koja nije niz dobiva odgovor točno kao prije.
• Izvozi. Sa setovima csv dobiva stupce Set i Position na kraju, svg ispisuje oznaku pozicije (A1, A2 …) u oznakama dijelova i crta okvir svakog seta u zasebnoj grupi matched-sets — options.setOutlines: false izostavlja tu grupu — a dxf nosi oznaku pozicije na sloju LABELS. pdf i labelsPdf ne označavaju setove: crtaju članove kao obične dijelove, a warnings to navodi; oznake setova nalaze se u sheets[].parts[].matchedSet, csv i svg.
• Motori i endpointi. Motori heuristic i balanced slažu setove (balanced ne rangira priority, pa pod respectStock set ondje može izgubiti svoje mjesto, uz upozorenje priority:). Motor max odbija neprazan matchedSets kodom 400 čiji details.unsupported to imenuje, prije nego što se poziv naplati; prazan je obični max posao. matchedSets i parts[].id samo su za 2D: endpointi 1D, wood i nest ih zanemaruju.
• grainGroup je zastarjelo. I dalje se prihvaća i radi točno kao prije: dijelovi koji dijele grupu drže se na jednoj ploči. Nikada ih nije postavljao jedan uz drugoga, pa ne daje neprekinutu žicu preko njih — za to koristite matchedSets.

Funkcija Usklađivanje žice u aplikaciji CutOptim slaže setove istom jezgrom.

Zašto građa ima vlastiti endpoint

Linearni materijal poznaje jednu dimenziju, svoju duljinu, pa bilo koja šipka može poslužiti bilo kojem dijelu. Građa ne radi tako: dio 50×150 ne može izaći iz šipke 50×100, koliko god duljine u njoj ostalo. Wood endpoint stoga uzima obje stranice poprečnog presjeka na svakom dijelu i svakom retku zalihe, dijeli posao po poprečnom presjeku, podudara svaku sekciju s vlastitom zalihom i vraća sekcije zasebno — svaku s vlastitim šipkama i vlastitim zbrojevima, uz brojke za cijeli posao.

Dvije pojedinosti koje vrijedi znati prije nego što je integrirate:

• Dvije stranice poprečnog presjeka mogu se poslati bilo kojim redoslijedom. 50×100 i 100×50 su ista šipka okrenuta, pa se podudaraju kao jedna sekcija. To znači da razlika u tome kako su vaši podaci slučajno uneseni ne može učiniti da materijal nestane.
• “Nema zalihe ovog poprečnog presjeka” i “nije stalo” prijavljuju se zasebno. Prvo je izvještaj o nedostatku materijala, drugo je problem kapaciteta, i imaju različita rješenja — pa bi njihovo miješanje u jedan popis poslalo vašeg korisnika da traži na pogrešnom mjestu.

Ovo biste mogli aproksimirati s nekoliko vlastitih 1d poziva, grupirajući dijelove sami. Koštalo bi vas jednog zahtjeva iz kvote po poprečnom presjeku umjesto jednog za posao, stavilo bi podudaranje zalihe u vaš kod i proizvelo zbroj posla koji biste morali sastaviti sami — takav koji se ne bi nužno slagao s onim što CutOptim aplikacija prikazuje za isti posao.

Dijelovi iz CAD datoteke

Nesting endpoint ne prima samo koordinate. Dio umjesto njih može nositi source — SVG ili DXF dokument — a poslužitelj iz datoteke čita njegov obris i rupe u njemu. To je isti čitač koji aplikacija koristi kad crtež ispustite na njezin Nesting način, pa knjižnicu dijelova koja već postoji kao CAD datoteke nije potrebno najprije prepisati u popise koordinata.

Datoteka zamjenjuje samo geometriju. Količina, materijal, dopuštene rotacije i vaši vlastiti metapodaci ostaju obična polja retka dijela, jednako kao kad šaljete koordinate. Jedna datoteka opisuje jedan dio; kad jedan crtež sadrži više odvojenih komponenti, POST /v1/import/nest ga prvo razdvaja u gotove retke — a taj poziv traži ključ, ali ne troši zahtjev iz vaše mjesečne kvote.

Ništa se ne pohranjuje. Datoteka postoji samo kao sam zahtjev: čita se u memoriji i nestaje u trenutku kad je odgovor ispisan. Ne ostaje kopija na disku ni u bazi podataka, ništa ne završava u dnevniku i poslije nema što obrisati. S jedinicama postupamo jednako — DXF može deklarirati milimetre ili inče i mi javljamo što je rekao, ali koordinate se nikad ne pretvaraju, jer nijedna vrijednost u ovom API-ju ne nosi jedinicu.

Isti odgovor svaki put

Engine je determinističan: isti ulaz uvijek proizvodi isti izlaz. Nema nasumičnosti ni sata unutar algoritma.

To zvuči akademski, ali je praktičan razlog da se na tome gradi. Znači da se rezultati mogu keširati — ako ste već pitali za ovaj točan posao, možete sigurno ponovno upotrijebiti odgovor umjesto da pitate ponovno. Također znači da se integracija može testirati: plan se može usporediti s poznato-ispravnim rezultatom, a razlika je stvarna razlika, a ne šum. Softver koji kupcu ponudi cijenu u ponedjeljak ponudit će istu cijenu u petak.

Postoji jedna opcionalna iznimka, i ona to kaže: max engine za ugnježđivanje (niže) troši fiksni vremenski proračun tražeći, pa koliko daleko dođe ovisi o tome koliko posla stane u to vrijeme. Njegovi odgovori nose deterministic: false. Svaki drugi engine — uključujući zadani engine ugnježđivanja, lbf — determinističan je.

Sigurno ponavljanje. Ako se veza prekine, ne znate je li zahtjev stigao. Pošaljite zaglavlje Idempotency-Key — vrijednost koju odaberete za svaki posao — i ponovite s istim ključem: unutar 24 sata isti zahtjev vraća spremljeni odgovor, označen s Idempotency-Replayed: true, i ne naplaćuje se drugi put. Ni posao max ne stavlja se u red dvaput. Javni demo ključ zanemaruje ovo zaglavlje. (Od 2026-10-15.)

Webhookovi za asinkrone poslove. Umjesto provjeravanja GET /v1/jobs/{id} registrirajte krajnju točku (URL https://) na nadzornoj ploči i dobit ćete potpisani POST — job.succeeded ili job.failed — kad asinkroni posao max završi. Provjerite zaglavlje CutOptim-Signature primljenom tajnom, odgovorite unutar 10 sekundi, a plan pročitajte s GET /v1/jobs/{id}. Neuspjela isporuka se ponavlja: 8 pokušaja tijekom 24 sata. (Od 2026-10-19.)

Službeni SDK-ovi. Klijenti otvorenog koda za TypeScript, Python i PHP — npm install @cutoptim/engine, pip install cutoptim, composer require cutoptim/engine — s tipiziranim zahtjevima, ponavljanjima koja se nikad ne naplaćuju dvaput (svaki poziv nosi Idempotency-Key), pomoćnikom za čekanje asinkronih poslova i provjerom webhookova. Izvorni kod na GitHubu; pojedinosti u vodiču za SDK (na engleskom).

MCP poslužitelj za AI asistente. Claude Code, Cursor, VS Code i Claude Desktop mogu pozivati motor kao alate preko hostiranog Model Context Protocol poslužitelja na https://api.cutoptim.com/mcp, s istim API ključem (Authorization: Bearer …) i iz iste kvote: jedan poziv alata je jedan API poziv, a alati validate_* su besplatni. Može se pokrenuti i lokalno, paketom npx -y @cutoptim/mcp (ključ u CUTOPTIM_API_KEY), a službeni MCP Registry ga navodi kao io.github.cutoptim/engine. Postavke klijenata su u MCP vodiču (na engleskom).

Tri enginea

API nudi izbor engine-a. Prva dva izvode se sinkrono; treći je asinkroni. Razlika nije kvaliteta — riječ je o kompromisu između brzine, toga može li se rezultat rezati na formatnoj pili i koliko se približava teorijskom minimumu.

• heuristic je zadani i isti koji aplikacija koristi. Proizvodi giljotinske rasporede: najveću iskoristivost, svaki raspored rezljiv na formatnoj pili i uvijek potpun plan rezanja. Sinkrono.
• balanced je opcionalan (opt-in). Umjesto toga koristi slobodno raspoređivanje (free nesting), koje je dramatično brže na vrlo velikim poslovima — izmjereno otprilike 25× brže na poslu od 2.000 dijelova — po cijenu nešto niže iskoristivosti. Važna zamka: njegovi rasporedi često se ne mogu rezati od ruba do ruba, pa za njih uopće ne vraća plan rezanja. Sinkrono.
• max je opcionalan (opt-in), za 2D ploče (i, zasebno, za true-shape ugnježđivanje — vidi niže). Kod 2D-a riječ je o pretraživanju stabla na strani poslužitelja koje doseže dokazani optimum na znatno više poslova od zadanog, a njegovi rasporedi i dalje su giljotinski rezljivi. Cijena je vrijeme: max izračun traje od nekoliko sekundi do minute, pa ne odgovara u odgovoru. Umjesto toga, POST /v1/optimize/2d s engine: "max" vraća id posla, a vi ispitujete GET /v1/jobs/{id} dok ne bude spreman. I dalje je determinističan. Posegnite za njim kada je velik, vrijedan posao vrijedan čekanja za posljednjih nekoliko ploča. Modelira jedan format zaliha u punoj veličini ploče, u neograničenoj količini, pa se zahtjev koji uz to nosi drugi format zaliha, trim po stranama, ograničene zalihe (respectStock), materijale, grupe žice ili neprazan matchedSets odbija unaprijed kodom 400 koji točno imenuje što motor ne može — prije nego što se poziv naplati. Takve poslove šaljite motoru heuristic, koji ih sve modelira.

Ugnježđivanje: lbf i max

True-shape ugnježđivanje ima svoja dva motora. lbf je zadani: trenutačan, sinkron i determinističan. max je opcionalan (opt-in) i asinkron, potpuno jednako kao 2D max — POST /v1/optimize/nest s engine: "max" vraća id posla, a vi ispitujete GET /v1/jobs/{id}.

max za ugnježđivanje prvo pokreće lbf prolaz, tako da uvijek ima valjan odgovor pri ruci. Zatim troši vremenski proračun (options.timeBudgetMs, zadano 60 sekundi, između 10 i 180) tražeći raspored s manje ploča, popunjavajući jednu ploču po jednu. Nikad ne vraća više ploča nego lbf: kad pretraga ne pronađe poboljšanje, dobivate lbf raspored i upozorenje koje to kaže. Zato što je pretraga vremenski ograničena, njegovi odgovori nose deterministic: false. Prihvaća više formata ploča po materijalu i respectStock, a rezultat rangira po istom pravilu kao lbf (niže): lbf plan zamjenjuje samo kada je bolji — nikad samo zato što ima manje ploča. Poligonalnu ploču ili zone isključenja, koje njegova pretraga u trakama ne može modelirati, unutar posla poslužuje lbf prolaz, s upozorenjem — nikad se ne odbija. Starije ime sparrow prihvaća se kao alias za max.

Pravokutni dijelovi dobivaju egzaktnu mrežu (od 2026-09-28). lbf pronalazi položaje uzorkovanjem, a to gotovo nikada ne pogodi mrežu bez ikakve zračnosti: tri dijela od 500 mm po širini ploče od 1500 mm uz nulti razmak točno stanu, a pretraga uzorkovanjem postavi dva. Zato oba motora isprobavaju i dvije alternative i zadržavaju onu koja je najbolje rangirana po istom pravilu: dijelove ograničene na prave kutove koje dopuštaju, te opisane pravokutnike dijelova složene egzaktnim algoritmom za slaganje pravokutnika (pravokutnici koji se ne preklapaju ne mogu sadržavati dijelove koji se preklapaju, pa to vrijedi za bilo koji obris). Kod izjednačenja — iste ploče, ista površina ploča — pobjeđuje plan koji svoje ploče popunjava redom, od prve prema posljednjoj, a zatim onaj s manje dijelova zakrenutih izvan pravih kutova. Ništa ne treba uključivati, a zbog tog rangiranja rezultat može biti samo bolji; plan koji pravokutnici svedu na najmanji broj ploča što ga dopušta površina dijelova ujedno omogućuje da max odgovori odmah umjesto da nastavi tražiti.

Posao od nekoliko desetaka dijelova obično treba proračun od otprilike 15 sekundi (timeBudgetMs: 15000); posao završava otprilike jednu do dvije sekunde nakon proračuna, uz eventualno vrijeme provedeno u redu. Ispitujte GET /v1/jobs/{id} svake dvije do tri sekunde — ispitivanje ne troši kvotu. Nijedan proračun ne može obećati određeni broj ploča.

Ugnježđivanje: odmak od ruba, formati ploča i trošak svake ploče

• Odmak od ruba. options.minSeparation je razmak između dijelova, a sam po sebi vrijedi i na rubu ploče. options.edgeClearance postavlja rub zasebno — na primjer 5 između dijelova i 0 ili 10 na rubu. Izostavite ga i rub zadržava minSeparation, potpuno jednako kao i prije. Radi na oba motora, traži pravokutne ploče (w i h), a zone isključenja zadržavaju minSeparation poput dijelova. Poligonalna ploča, ili vrijednost koja na ploči ne ostavlja mjesta, odbija se kodom 400 prije nego što se poziv naplati.
• Odabir formata ploče. Kada materijal ima dva ili više redaka zalihe, lbf ih isprobava vašim redoslijedom, svaki format zasebno i redoslijedom od najjeftinijeg, te zadržava najbolji — pa rezultat više ne ovisi o redoslijedu kojim ste naveli retke. Rangiranje je: najviše postavljenih obaveznih dijelova (vidi niže), zatim najviše postavljenih dijelova, zatim najmanja ukupna površina ploče (materijal), zatim najmanje ploča. Uz options.minimizeCost umjesto toga rangira prema ukupnoj cijeni (price, ili cost za redak bez cijene) — ali samo kada svaki redak tog materijala ima jednu; inače se vraća na površinu i to navodi u warnings.
• Miješanje formata. Nakon toga se svaka ploča — počevši od najmanje popunjene — zasebno ponovno ugnježđuje na jeftinije ili manje retke i zamjenjuje kada je cijeli plan bolje rangiran. Formati se tako mogu miješati unutar jednog materijala: tipično dvije velike ploče i manja posljednja, ondje gdje je napola prazna posljednja ploča prije bila velika. Uz options.respectStock nijedan se redak ne koristi češće nego što mu je qty. max engine primjenjuje isto rangiranje.
• Obavezni dijelovi. parts[].priority: true označava dio koji se mora izrezati. Važno je uz options.respectStock — ograničenu zalihu, gdje možda neće stati svaki dio: obavezni dijelovi se tada postavljaju prvi, pa obični dio nikada ne zauzme prostor na ploči koji treba obaveznom dijelu, a svako gore navedeno rangiranje stavlja naprijed plan koji zadrži više njih, čak i ako ukupno postavi manje dijelova. Oba engine-a to poštuju (max zadržava lbf raspored kad god nešto ostane nepostavljeno). Bez respectStock svaki dio koji stane ionako se postavlja, pa oznaka ništa ne mijenja. Obavezan dio koji ne stane ni na jednu ploču i dalje je naveden u unplaced. (Od 2026-09-22 — prije toga motor za ugnježđivanje prihvaćao je polje, ali ga je ignorirao.)
• Ograničena zaliha na koju ne stane sve. Uz options.respectStock, kad plan još ostavlja nerazmještene dijelove, motor dodatno puni ploče jednu po jednu obuhvatnim pravokutnicima dijelova — svaku što punije, a dio koji stane samo na jednu veličinu ploče ide tamo prvi (visoka stranica na jedinu veliku ploču, ne na traku ostatka). Taj se plan preuzima samo ako razmješta više dijelova (najprije obavezne) ili troši manje materijala; posao na koji sve stane vraća se točno kao prije. Poštuje dopuštene rotacije svakog dijela, minSeparation i edgeClearance. (Od 2026-10-14.)
• Trošak svake ploče. Svaka ploča nosi stock — indeks retka zalihe iz zahtjeva iz kojeg je izrezana — a odgovor dodaje stockUsage: po jedan unos za svaki korišteni redak zalihe, s brojem ploča, ukupnom cijenom i gustoćom. Jedinica je redak zalihe, a ne format: dva retka s istim dimenzijama, ali različitom cijenom ili meta, dva su zasebna unosa.
• Duljina reza i proboji. Svaka ploča nosi cutLength — zbroj opsega obrisa postavljenih dijelova i rupa, u vašoj jedinici — i pierces, po jedan za svaki zatvoreni obris; metrics zbraja oboje. Riječ je o geometrijskoj duljini obrisa: bez rezanja po zajedničkoj liniji, uvodnih rezova ili mikro-spojeva — njih dodaje vaš CAM.
• Iskorištena površina, za naplatu dijela ploče. Svaka ploča nosi usedWidth i usedHeight — najudaljeniju točku do koje seže bilo koji postavljeni dio od ishodišnog kuta ploče, u vašoj jedinici, na stvarnoj ploči (uz edgeClearance uključen je i razmak od ruba) — i usedArea, njihov umnožak; stockUsage[].usedArea zbraja to po retku zalihe. To je ono što ERP-u treba za naplatu vodoravnog reza (usedHeight × širina ploče), okomitog reza (usedWidth × visina ploče) ili graničnog okvira (usedArea) umjesto cijele ploče — pravilo naplate ostaje vaše. Da bi te brojke bile male, oba engine-a zadano zbijaju najmanje popunjenu ploču svakog materijala: njezini dijelovi ponovno se ugnježđuju na istoj ploči s podskupovima rotacija koje svaki dio dopušta — 0/180, 0/90/180/270 i jedna orijentacija za svaku kopiju, presjek s diskretnim allowedRotations, nikad nova kutna vrijednost — a zadržava se raspored s najmanjom iskorištenom površinom. Uz engine: "max" tu ploču zatim ponovno slaže i samo pretraživanje — duž visine ploče, a kod plana s jednom pločom i duž njezine širine — i po istom pravilu zadržava zbijeniji raspored. Broj ploča, veličine, cijena i postavljeni dijelovi nikad se ne mijenjaju; options.compact: false vraća nezbijeni raspored. Ako naplaćujete traku umjesto graničnog okvira, postavite options.compactFor da odabere: "horizontal" zadržava raspored s najmanjom usedHeight (traka preko cijele širine ploče), "vertical" onaj s najmanjom usedWidth (traka preko cijele visine ploče); zadano "box" zadržava najmanju usedArea. Načini rada s trakom također isprobavaju svaku kopiju zakrenutu za četvrtinu kruga (90° ili 270°) gdje to allowedRotations dopušta. Koliko se iskorištena površina smanji ovisi o dijelovima. (Od 2026-09-22.)

Ograničenja

Svaki zahtjev je omeđen, tako da odbjegli posao jasno ne uspije umjesto da visi:

Dobivanje pristupa

Počnite na stranici Engine API-ja. Engine API naplaćuje se zasebno od planova aplikacije i nijedna nadogradnja plana ga ne uključuje.

1. Isprobajte, zatim se pretplatite — ili pitajte. API možete pozvati prije plaćanja: gumbi Pokreni ovaj primjer u API referenci koriste javni demo ključ, a svaki prijavljeni račun na nadzornoj ploči može izraditi besplatne testne ključeve (vlastita mala mjesečna kvota, nikad se ne naplaćuju, pretplata nije potrebna). Kad ste spremni, pretplata na stranici Engine API-ja je najbrži put — početni plan, Studio, počinje besplatnim probnim razdobljem, a pristup sam sleti na vaš račun. Ako biste radije prvo opisali svoju integraciju ili trebate količinu iznad standardnog plana, umjesto toga stupite u kontakt i recite što želite povezati i otprilike koliko planova rezanja mjesečno će trebati.
2. Pristup se pojavljuje na vašem računu. Ništa drugo o vašem računu se ne mijenja.
3. Stvorite ključ. Kartica API ključeva nalazi se na vašoj nadzornoj ploči za svaki prijavljeni račun: bez pretplate stvara testne ključeve, s API pristupom i live ključeve. Ondje sami stvarate, imenujete i brišete ključeve.
4. Odmah kopirajte ključ. Cijeli ključ prikazuje se točno jednom, u trenutku kada ga stvorite.

Prema ključu se odnosite kao prema lozinki: pripada u konfiguraciju vašeg softvera, a ne u e-poštu, tablicu ili snimku zaslona.

Što radi kartica API ključeva na vašoj nadzornoj ploči

Četiri kontrole, i vrijedi biti precizan oko toga što svaka mijenja — posebno posljednja, za koju ljudi očekuju da dira naplatu, a ne dira.

• Plan, Prijelaz i Naplata. Prikazuje na kojem je planu račun (Studio ili Scale). Prijeđi na Scale (ili Prijeđi na Studio) mijenja plan nakon potvrde, a mjesečna kvota računa mijenja se odmah. Naplata otvara vaše postavke naplate, gdje ažurirate karticu, pregledavate račune ili otkazujete.
• Stvori ključ. Generira novi ključ i prikazuje ga jednom, upravo ondje. Dajete mu ime (ERP integration, staging) isključivo kako biste kasnije mogli razlikovati svoje ključeve. Do 10 aktivnih ključeva po računu. Testni ključevi stvaraju se na isti način i broje se zasebno: imaju vlastitu malu mjesečnu kvotu i nikad se ne naplaćuju.
• Traka potrošnje. Dva broja: ukupni iznos vašeg računa za kalendarski mjesec u odnosu na mjesečnu kvotu, i po ključu, koliko je taj ključ potrošio. Brojka po ključu tu je da odgovori koja integracija jede dozvoljenu količinu — nije zaseban proračun.
• Opozovi. Zaustavlja rad tog jednog ključa, od sljedećeg poziva nadalje. Redak ostaje vidljiv pa se njegova povijest ne gubi.

Jedna kvota za račun, ne jedna po ključu

Svaki aktivni ključ na vašem računu crpi iz iste mjesečne dozvoljene količine. Stvaranje drugog ključa ne stvara drugu kvotu — ključevi postoje kako biste mogli odvojiti staging od produkcije, dati svakoj integraciji vlastite vjerodajnice i opozvati jedan bez ometanja ostalih.

GET /v1/usage prijavljuje stanje računa (used, limit, remaining), pa odgovara na pitanje koje zapravo imate — koliko je preostalo prije nego što pozivi počnu neuspješni — bez obzira na to kojim ključem pitate. Kada dozvoljena količina ponestane, svaki ključ vraća 402, ne samo onaj koji ju je potrošio.

Planovi, cijena i kvota

Engine API naplaćuje se zasebno od planova aplikacije, mjesečno, u EUR, s dva plana:

Sve ostalo je isto na oba: isti engine-i, sva četiri načina, svaka opcija, isti odgovori. Svaki zahtjev vrijedi jednako — posao ugnježđivanja košta jedan zahtjev, baš kao i 2D ili 1D posao.

• Čvrsta granica, bez prekoračenja. Kad se mjesečna kvota potroši, pozivi vraćaju 402 sve dok se ne obnovi prvog dana sljedećeg mjeseca. Nema iznenađujućeg računa.
• Dvije poruke e-pošte, da vas granica ne iznenadi. Račun obavještavamo kad dosegne 90 % kvote i ponovno kad je potrošena.
• Promjena plana jedan je gumb na kartici API ključeva na vašoj nadzornoj ploči (Prijeđi na Scale / Prijeđi na Studio); nova kvota primjenjuje se odmah. Nadogradnja se naplaćuje odmah za ostatak razdoblja; prelazak na niži plan ne vraća se, a niža cijena primjenjuje se od sljedeće obnove. Prelazak je dostupan nakon probnog razdoblja.
• Veće količine od plana Scale cijene se pojedinačno — stupite u kontakt.

Trenutne cijene i kvote navedene su na stranici Engine API-ja — ta stranica ih čita iz naše konfiguracije cijena, pa je uvijek točna brojka.

Za tehničke detalje — točan oblik zahtjeva i odgovora, svaku opciju, sve kodove pogrešaka i kako radi verzioniranje — pogledajte API referencu.

Open-source komponente

CutOptim engine-i grade se na open-source bibliotekama, korištenima nepromijenjenima na našim poslužiteljima:

• jagua-rs — geometrijski motor kolizija iza true-shape ugnježđivanja (MPL-2.0).
• sparrow — pretraga iza max engine-a za ugnježđivanje (MIT, KU Leuven).
• PackingSolver — pretraživanje stabla iza 2D max engine-a (MIT).

Sve oko njih — API, mapiranje između ugovora i ovih engine-a, pravokutni pakiraci i sama aplikacija — CutOptimov je vlastiti kod.

Što se ovime ne mijenja

Vrijedi izreći jasno, jer je Engine API lako pogrešno protumačiti kao promjenu proizvoda:

• Optimizator u aplikaciji je nepromijenjen. I dalje se izvodi u vašem pregledniku, točno kao i prije.
• Besplatni, Pro i Radionica plan nisu pogođeni. I dalje uključuju optimizator u aplikaciji, s istim ograničenjima kao prije. Ništa nije premješteno iza API-ja.
• Ništa što radite u aplikaciji ne troši API zahtjeve. Mjesečnu API kvotu diraju samo pozivi koje čini vaš vlastiti softver.

Engine API je dodatak za ljude koji integriraju CutOptim u drugi softver. Ako to niste vi, ništa se nije promijenilo.