Engine API

Tot ce face CutOptim în browserul tău pornește de la un singur calcul: având aceste piese și acest material de bază, care este cel mai bun mod de a le tăia? Engine API expune exact acel calcul prin internet, astfel încât un alt program să poată pune întrebarea și să primească răspunsul înapoi — fără browser, fără clicuri, fără ca nimeni să fie autentificat.

Asta este toată ideea. Nu este un optimizator nou, nu este un optimizator mai bun și nu este un plan mai mare. Este același motor, accesibil pentru software în loc de o persoană.

Este pentru mine?

Pentru marea majoritate a utilizatorilor CutOptim, răspunsul sincer este nu. Dacă ziua ta de lucru înseamnă să deschizi CutOptim, să introduci piesele și materialul de bază și să tipărești sau să exporți planul, aplicația este produsul, iar această pagină nu te privește.

Engine API este pentru o singură situație: planurile de tăiere trebuie să apară în interiorul unui software pe care îl folosești deja, fără ca nimeni să intre pe CutOptim. În practică, asta înseamnă una din două persoane:

• Folosești deja un software în care planul de tăiere își are locul. Un ERP care ține comenzile, o aplicație de ofertare care calculează prețul lucrărilor sau software-ul propriu al unei mașini. În loc ca un operator să reintroducă aceeași listă de piese în CutOptim, acel program întreabă direct motorul și afișează planul acolo unde se lucrează deja.
• Se construiește un software pentru tine. De un programator intern, de o firmă locală de software sau de furnizorul mașinii tale. Engine API este ceea ce conectează ei.

Dacă nu ești sigur de care parte a liniei te afli, un test bun: ar putea apărea planul fără ca nimeni să îl ceară? Dacă da, API-ul este relevant. Dacă întotdeauna o persoană decide să facă un plan de tăiere, aplicația este deja instrumentul potrivit.

Ce face

Software-ul tău trimite aceleași două lucruri pe care le-ai introduce în aplicație — o listă de piese și o listă de material de bază — ca JSON. Motorul trimite înapoi un răspuns complet:

• Layoutul complet. Fiecare piesă, poziționată pe o anumită placă sau bară, inclusiv dacă a fost rotită.
• Un plan de tăiere. Nu doar o imagine cu dreptunghiuri: secvența reală de tăiere ghilotină, în ordine, astfel încât planul să poată fi executat pe un ferăstrău pentru panouri.
• Cifrele. Câte plăci sau bare consumă lucrarea, procentul de randament, câte tăieri sunt necesare și prețul total al materialului folosit. Pentru panouri primești și cele două numere oneste de tăieri — linii de tăiere, care unifică tăierile ce împart aceeași reglare a opritorului, și treceri de ferăstrău, care numără fiecare trecere — plus lungimea totală tăiată.
• Opțional, desenul. Cere include: ["svg","csv","dxf"], iar răspunsul poartă în plus layoutul ca fișier gata făcut — un desen SVG 2D de sine stătător, un DXF R12/AC1009 sau o listă de tăiere CSV — inline în JSON, fără stocare și fără un al doilea apel. (SVG este doar 2D.)
• Propriii tăi identificatori, returnați. Atașează un obiect meta — un număr de articol, o linie de comandă, o referință de client — oricărei piese sau oricărui rând de material, iar el revine neschimbat pe fiecare piesă plasată și pe fiecare placă sau bară, astfel încât planul să se potrivească cu propriul tău sistem. Acesta este câmpul de folosit când vrei să trimiți toate plăcile tale, să marchezi fiecare cu propriul tău cod și să citești înapoi ce placă a ales optimizatorul — pui codul în stock[].meta și îl primești identic pe sheets[].meta. Nu influențează niciodată plasarea. Nu folosi câmpul material pentru identificare: material este o partiționare strictă — o piesă este tăiată doar din material de bază care poartă aceeași etichetă material —, așa că etichetarea fiecărui rând de material, lăsând piesele neetichetate, face ca toate piesele să revină ca unmatched, iar rezultatul să fie gol.

Sunt patru moduri de optimizare, toate corespunzând aplicației — unul pentru plăci 2D, unul pentru material 1D liniar (bare, profile, țeavă), unul pentru lemn, al cărui material are o secțiune, și nesting-ul true-shape (POST /v1/optimize/nest), care aranjează poligoane arbitrare pentru tăiere cu laser, plasmă și jet de apă (modul Nesting al aplicației). Fiecare endpoint de optimizare are și un endpoint gratuit de validare, care verifică o cerere fără să o rezolve (vezi mai jos).

Endpointuri

URL-ul de bază este https://api.cutoptim.com. Endpointurile de optimizare și de consum poartă o cheie în antetul Authorization: Bearer <key>; endpointurile de validare și de disponibilitate nu au nevoie de cheie.

Cele mai multe apeluri primesc direct rezultatul final. Singura excepție este motorul asincron max (vezi Trei motoare mai jos): o trimitere max returnează un id de lucrare, iar tu interoghezi GET /v1/jobs/{id} până când planul este gata.

Endpointurile de validare preiau același corp ca endpointul de optimizare corespunzător și îl verifică fără a rula rezolvarea: o cerere malformată revine ca un 400 care numește exact câmpul greșit, iar una bine formată returnează valid: true plus avertismente de fezabilitate (de exemplu, o piesă care nu încape în niciun material). Nu costă nimic și nu au nevoie de cheie, așa că îți poți valida payload-urile în timp ce construiești integrarea — încă înainte de a avea o cheie — și poți confirma că o cerere nu va fi respinsă fără să consumi unul dintre apelurile tale lunare.

De ce lemnul are endpoint propriu

Materialul liniar cunoaște o singură dimensiune, lungimea, așa că orice bară poate servi oricărei piese. La lemn nu este așa: o piesă 50×150 nu poate ieși dintr-o bară 50×100, oricâtă lungime ar rămâne. De aceea endpointul pentru lemn preia ambele laturi ale secțiunii pentru fiecare piesă și fiecare rând de material, împarte lucrarea pe secțiuni, potrivește fiecărei secțiuni materialul ei și returnează secțiunile separat — fiecare cu barele și totalurile proprii, alături de cifrele pentru întreaga lucrare.

Două detalii de știut înainte de integrare:

• Cele două laturi ale secțiunii pot fi trimise în orice ordine. 50×100 și 100×50 sunt aceeași grindă întoarsă și formează o singură secțiune. Astfel, o diferență în felul în care au fost introduse datele tale nu poate face materialul să dispară.

• „Niciun material de această secțiune” și „nu a încăput” se raportează separat. Primul înseamnă material lipsă, al doilea o problemă de capacitate, iar rezolvarea diferă — amestecate într-o singură listă, l-ar trimite pe utilizatorul tău să caute în locul greșit.

Ai putea aproxima asta cu mai multe apeluri 1d proprii, grupând piesele singur. Te-ar costa o cerere din cotă pentru fiecare secțiune în loc de una pentru lucrare, ar muta potrivirea materialului în codul tău și ar produce un total pe care ar trebui să-l compui singur — și care nu ar coincide neapărat cu ce arată aplicația CutOptim pentru aceeași lucrare.

Piese dintr-un fișier CAD

Endpointul de nesting nu acceptă doar coordonate. O piesă poate purta în schimb un source — un document SVG sau DXF — iar serverul îi extrage conturul, și găurile din el, din fișier. Este același cititor pe care aplicația îl folosește când tragi un desen peste modul ei Nesting, deci o bibliotecă de piese care există deja ca fișiere CAD nu trebuie rescrisă mai întâi în liste de coordonate.

Fișierul înlocuiește doar geometria. Cantitatea, materialul, rotațiile permise și propriile tale metadate rămân câmpuri obișnuite ale rândului piesei, exact ca atunci când trimiți coordonate. Un fișier descrie o piesă; când un singur desen conține mai multe componente separate, POST /v1/import/nest îl împarte întâi în rânduri gata de folosit — iar acel apel necesită o cheie, dar nu consumă o cerere din cota ta lunară.

Nimic nu se stochează. Fișierul există doar ca cererea însăși: este citit în memorie și dispare în momentul în care răspunsul este scris. Nu rămâne nicio copie pe disc sau într-o bază de date, nimic nu ajunge într-un jurnal și nu este nimic de șters după aceea. Cu unitățile procedăm la fel — un DXF poate declara milimetri sau inci și noi raportăm ce a spus, dar coordonatele nu sunt niciodată convertite, fiindcă nicio valoare din acest API nu poartă o unitate.

Același răspuns de fiecare dată

Motorul este determinist: aceeași intrare produce întotdeauna același rezultat. Nu există aleatoriu și nu există ceas în algoritm.

Sună academic, dar este exact motivul practic pentru care merită să construiești pe el. Înseamnă că rezultatele pot fi puse în cache — dacă ai întrebat deja despre exact aceeași lucrare, poți refolosi liniștit răspunsul în loc să întrebi din nou. Înseamnă și că integrarea poate fi testată: un plan poate fi comparat cu un rezultat cunoscut ca bun, iar o diferență este o diferență reală, nu zgomot. Un software care dă luni un preț unui client va da vineri același preț.

Trei motoare

API-ul oferă mai multe variante de motor. Primele două rulează sincron; al treilea este asincron. Diferența nu este de calitate — este un compromis între viteză, faptul că rezultatul poate fi tăiat sau nu pe un ferăstrău pentru panouri și cât de aproape ajunge de minimul teoretic.

• heuristic este cel implicit și este același pe care îl folosește aplicația. Produce aranjamente ghilotină: cel mai bun randament, fiecare aranjament tăiabil pe ferăstrău și întotdeauna un plan de tăiere complet. Sincron.
• balanced se activează explicit. Folosește în schimb nesting liber, care este dramatic mai rapid la lucrările foarte mari — măsurat aproximativ 25× mai rapid la o lucrare de 2.000 de piese — cu prețul unui randament puțin mai mic. Reținerea importantă: aranjamentele sale adesea nu pot fi tăiate de la o margine la alta, așa că pentru acelea nu returnează niciun plan de tăiere. Sincron.
• max se activează explicit și este doar 2D. Este o căutare în arbore pe server care atinge optimul demonstrat pe mult mai multe lucrări decât cel implicit, iar aranjamentele sale rămân tăiabile ghilotină. Costul este timpul: o rezolvare max durează de la câteva secunde până la un minut, deci nu răspunde în cadrul răspunsului. În schimb, POST /v1/optimize/2d cu engine: "max" returnează un id de lucrare, iar tu interoghezi GET /v1/jobs/{id} până când este gata. Rămâne determinist. Apelează la el atunci când o lucrare mare și valoroasă merită așteptarea pentru ultimele câteva plăci. Modelează un singur format de stoc la dimensiunea completă a plăcii, cu disponibilitate nelimitată, așa că o cerere care mai poartă un al doilea format de stoc, trim pe laturi, stoc limitat (respectStock), materiale sau grupuri de fibră este refuzată din start cu un 400 care numește exact ce nu poate face — înainte ca un apel să fie taxat. Trimite acele lucrări către heuristic, care le modelează pe toate.

Limite

Fiecare cerere este mărginită, așa că o lucrare scăpată de sub control eșuează clar, în loc să rămână blocată:

Obținerea accesului

Pornește de la pagina Engine API. Engine API se facturează separat de planurile aplicației și nicio schimbare de plan nu îl activează.

1. Abonează-te sau scrie-ne. Abonarea din pagina Engine API este calea cea mai rapidă — are o perioadă de probă, iar accesul ajunge singur în cont. Dacă preferi să descrii mai întâi integrarea sau ai nevoie de un volum peste planul standard, scrie-ne și spune ce vrei să conectezi și aproximativ câte planuri de tăiere pe lună va fi nevoie.
2. Accesul este adăugat pe contul tău. Nimic altceva la contul tău nu se schimbă.
3. Creează o cheie. Odată ce contul tău are acces API, în panoul de control apare un card Chei API. Îți creezi, denumești și ștergi singur cheile de acolo.
4. Copiază imediat cheia. Cheia completă este afișată exact o singură dată, în momentul în care o creezi.

Tratează o cheie ca pe o parolă: locul ei este în configurația software-ului tău, nu într-un email, într-un tabel sau într-o captură de ecran.

Ce face cardul Chei API din panoul tău

Trei comenzi — și merită spus exact ce schimbă fiecare, mai ales ultima, despre care mulți cred că ține de facturare. Nu ține.

• Creează cheie. Generează o cheie nouă și o afișează o singură dată, chiar acolo. Numele (Integrare ERP, staging) există doar ca să le deosebești mai târziu. Până la 10 chei active per cont.
• Bara de consum. Două cifre: totalul contului pe luna calendaristică față de cotă și, pentru fiecare cheie, cât a consumat ea. Cifra pe cheie răspunde la care integrare consumă alocarea — nu este un buget separat.
• Revocă. Scoate din uz acea singură cheie, începând cu următorul apel. Rândul rămâne vizibil, ca istoricul să nu se piardă.

O singură cotă pentru cont, nu una pentru fiecare cheie

Fiecare cheie activă a contului consumă din aceeași alocare lunară. A doua cheie nu creează o a doua cotă — cheile există ca să separi staging-ul de producție, să dai fiecărei integrări propria credențială și să revoci una fără să le deranjezi pe celelalte.

GET /v1/usage raportează situația contului (used, limit, remaining), deci răspunde la întrebarea pe care o ai de fapt — cât a mai rămas până când apelurile încep să eșueze — indiferent de cheia cu care ai întrebat. Când alocarea se termină, fiecare cheie returnează 402, nu doar cea care a consumat-o.

Preț și cotă

Engine API este facturat separat de planurile aplicației, cu un număr fix de cereri pe lună. Prețul actual, cota lunară de cereri și durata perioadei de probă sunt toate listate pe pagina Engine API — acea pagină le citește din configurația noastră de prețuri, deci cifra de acolo este întotdeauna cea corectă.

Pentru detaliile tehnice — structura exactă a cererii și a răspunsului, fiecare opțiune, toate codurile de eroare și modul în care funcționează versionarea — vezi documentația API.

Ce nu se schimbă

Merită spus limpede, pentru că Engine API este ușor de citit greșit ca o schimbare a produsului:

• Optimizatorul din aplicație este neschimbat. Rulează în continuare în browserul tău, exact ca înainte.
• Gratuit, Pro și Atelier nu sunt afectate. Includ în continuare optimizatorul din aplicație, cu aceleași limite ca înainte. Nimic nu a fost mutat în spatele API-ului.
• Nimic din ce faci în aplicație nu consumă cereri API. Cota lunară de API este atinsă doar de apelurile făcute de propriul tău software.

Engine API este o adăugire pentru cei care integrează CutOptim în alt software. Dacă nu este cazul tău, nimic nu s-a schimbat.