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

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.

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) i samo 2D. 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 ili grupe žice 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.

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. Pretplatite se ili pitajte. Pretplata na stranici Engine API-ja je najbrži put — ona ima probno razdoblje, 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 pojavljuje se na vašoj nadzornoj ploči čim vaš račun dobije API pristup. 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

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

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

Cijena i kvota

Engine API naplaćuje se zasebno od planova aplikacije, s fiksnim brojem zahtjeva mjesečno. Trenutna cijena, mjesečna kvota zahtjeva i duljina probnog razdoblja sve su navedeni 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.

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