Engine API

Wszystko, co CutOptim robi w Twojej przeglądarce, zaczyna się od jednego obliczenia: mając te elementy i ten materiał bazowy, jak najlepiej je pociąć? Engine API udostępnia dokładnie to obliczenie przez internet, więc pytanie może zadać inny program i sam otrzymać odpowiedź — bez przeglądarki, bez klikania, bez nikogo zalogowanego.

I to cała idea. To nie nowy optymalizator, nie lepszy optymalizator i nie większy plan. To ten sam silnik, dostępny dla oprogramowania zamiast dla człowieka.

Czy to jest dla mnie?

Dla zdecydowanej większości użytkowników CutOptim uczciwa odpowiedź brzmi nie. Jeśli Twój dzień pracy polega na otwarciu CutOptim, wpisaniu elementów i materiału bazowego oraz wydrukowaniu albo wyeksportowaniu planu, to aplikacja jest produktem, a ta strona jest dla Ciebie bez znaczenia.

Engine API jest dla jednej sytuacji: plany cięcia mają pojawiać się wewnątrz oprogramowania, z którego już korzystasz, bez tego, żeby ktokolwiek wchodził na CutOptim. W praktyce oznacza to jedną z dwóch osób:

• Już korzystasz z oprogramowania, w którym plan cięcia powinien się znaleźć. System ERP prowadzący Twoje zamówienia, narzędzie ofertowe wyceniające zlecenia albo oprogramowanie samej maszyny. Zamiast operatora przepisującego tę samą listę elementów do CutOptim, ten program pyta silnik bezpośrednio i pokazuje plan tam, gdzie praca już się dzieje.
• Ktoś buduje dla Ciebie oprogramowanie. Własny programista, lokalna firma informatyczna albo dostawca Twojej maszyny. Engine API jest tym, do czego się oni podłączają.

Jeśli nie masz pewności, po której stronie tej granicy jesteś, oto dobry test: czy plan mógłby pojawić się bez tego, żeby ktokolwiek o niego poprosił? Jeśli tak, API ma dla Ciebie znaczenie. Jeśli o powstaniu planu cięcia zawsze decyduje człowiek, aplikacja jest już właściwym narzędziem.

Co robi

Twoje oprogramowanie przesyła te same dwie rzeczy, które wpisałbyś w aplikacji — listę elementów i listę materiału bazowego — w formacie JSON. Silnik odsyła pełną odpowiedź:

• Cały układ. Każdy element umieszczony na konkretnej płycie lub pręcie, wraz z informacją, czy został obrócony.
• Plan cięcia. Nie tylko obrazek z prostokątami: rzeczywista gilotynowa sekwencja cięcia, po kolei, tak żeby plan dało się wykonać na pile panelowej.
• Liczby. Ile płyt albo prętów zajmie zlecenie, procentowe wykorzystanie materiału, ile potrzeba cięć oraz łączna cena zużytego materiału. Przy płytach otrzymujesz też dwie uczciwe miary liczby cięć — linie cięcia, które scalają cięcia korzystające z jednego ustawienia prowadnicy, oraz przejścia piły, które liczą każde przejście — a do tego łączną długość cięcia.
• Opcjonalnie rysunek. Poproś o include: ["svg","csv","dxf"], a odpowiedź poniesie też układ jako gotowy plik — samodzielny rysunek 2D SVG, plik DXF R12/AC1009 albo listę cięć CSV — w treści JSON, bez magazynowania i bez drugiego wywołania. (SVG dotyczy tylko 2D.)
• Twoje własne identyfikatory, zwrócone. Dołącz obiekt meta — numer artykułu, pozycję zamówienia, referencję klienta — do dowolnego elementu lub wiersza materiału bazowego, a wróci on niezmieniony przy każdym rozmieszczonym kawałku i każdej płycie lub pręcie, dzięki czemu plan pokrywa się z Twoim własnym systemem. To właśnie tego pola należy użyć, gdy chcesz wysłać wszystkie swoje płyty, oznaczyć każdą własnym kodem i odczytać z odpowiedzi, którą płytę wybrał optymalizator — wpisz kod w stock[].meta, a wróci on w sheets[].meta. Nigdy nie wpływa to na rozmieszczenie. Do identyfikacji nie używaj pola material: material to twardy podział — element wycinany jest wyłącznie z materiału bazowego o tym samym materiale — więc wypełnienie pola material we wszystkich wierszach materiału bazowego przy pozostawieniu elementów bez tego pola sprawia, że każdy element wraca jako unmatched, a wynik jest pusty.

Tryby optymalizacji są cztery, wszystkie odpowiadają aplikacji — jeden dla płyt 2D, jeden dla materiału 1D liniowego (pręty, profile, rury), jeden dla drewna, którego materiał ma przekrój, oraz nesting z rzeczywistych kształtów (POST /v1/optimize/nest), który układa dowolne wielokąty do cięcia laserowego, plazmowego i strumieniem wody (tryb Nesting aplikacji). Każdy endpoint optymalizacji ma też bezpłatny endpoint walidacji, który sprawdza zapytanie bez jego rozwiązywania (patrz niżej).

Endpointy

Bazowy URL to https://api.cutoptim.com. Endpointy optymalizacji i zużycia przenoszą klucz w nagłówku Authorization: Bearer <key>; endpointy walidacji i zdrowia nie wymagają klucza.

Większość wywołań od razu zwraca gotowy wynik. Jedynym wyjątkiem jest asynchroniczny silnik max (patrz Trzy silniki poniżej): zgłoszenie max zwraca identyfikator zadania, a Ty odpytujesz GET /v1/jobs/{id}, aż plan będzie gotowy.

Endpointy walidacji przyjmują tę samą treść co odpowiadający im endpoint optymalizacji i sprawdzają ją bez uruchamiania obliczeń: błędnie sformułowane zapytanie wraca jako 400 z nazwą dokładnie tego pola, które jest nie tak, a poprawne zwraca valid: true wraz z ostrzeżeniami o wykonalności (na przykład o elemencie, który nie pasuje do żadnego materiału bazowego). Nic nie kosztują i nie wymagają klucza, więc możesz walidować swoje ładunki podczas budowania integracji — jeszcze zanim będziesz mieć klucz — i potwierdzić, że zapytanie nie zostanie odrzucone, bez zużywania jednego z miesięcznych wywołań.

Dlaczego drewno ma własny endpoint

Materiał liniowy zna jeden wymiar, długość, więc każdy pręt może posłużyć każdemu elementowi. Z drewnem tak nie jest: elementu 50×150 nie da się wyciąć z pręta 50×100, niezależnie od tego, ile długości zostało. Dlatego endpoint drewna przyjmuje oba boki przekroju przy każdym elemencie i każdej pozycji materiału, dzieli zlecenie według przekroju, dopasowuje do każdego przekroju jego własny materiał i zwraca przekroje osobno — każdy z własnymi prętami i własnymi sumami, obok liczb dla całego zlecenia.

Dwa szczegóły warte poznania przed integracją:

• Oba boki przekroju można podać w dowolnej kolejności. 50×100 i 100×50 to ta sama belka obrócona i trafiają do jednego przekroju. Różnica w tym, jak akurat wprowadzono Twoje dane, nie może więc sprawić, że materiał zniknie.

• „Brak materiału o tym przekroju” i „nie zmieściło się” są raportowane osobno. Pierwsze to brak materiału, drugie to problem pojemności, a każdy naprawia się inaczej — zmieszane w jednej liście wysłałyby Twojego użytkownika w złe miejsce.

Można to przybliżyć kilkoma własnymi wywołaniami 1d, grupując elementy samodzielnie. Kosztowałoby to jedno zapytanie z Twojego limitu na przekrój zamiast jednego na zlecenie, przeniosłoby dopasowanie materiału do Twojego kodu i dałoby sumę zlecenia, którą musiałbyś złożyć sam — i która niekoniecznie zgadzałaby się z tym, co dla tego samego zlecenia pokazuje aplikacja CutOptim.

Elementy z pliku CAD

Endpoint nestingu przyjmuje nie tylko współrzędne. Element może zamiast nich nieść source — dokument SVG lub DXF — a serwer odczyta z pliku jego obrys wraz z otworami. To ten sam czytnik, którego używa aplikacja, gdy upuścisz rysunek na jej tryb Nesting, więc biblioteki elementów istniejącej już jako pliki CAD nie trzeba najpierw przepisywać na listy współrzędnych.

Plik zastępuje wyłącznie geometrię. Ilość, materiał, dozwolone obroty i Twoje własne metadane pozostają zwykłymi polami wiersza elementu, dokładnie tak jak przy wysyłaniu współrzędnych. Jeden plik opisuje jeden element; gdy pojedynczy rysunek zawiera kilka oddzielnych części, POST /v1/import/nest najpierw dzieli go na gotowe wiersze — a to wywołanie wymaga klucza, lecz nie zużywa żądania z Twojego miesięcznego limitu.

Nic nie jest przechowywane. Plik istnieje wyłącznie jako samo żądanie: jest czytany w pamięci i znika w chwili, gdy odpowiedź zostaje zapisana. Nie zostaje kopia na dysku ani w bazie danych, nic nie trafia do logu i nie ma potem czego usuwać. Z jednostkami postępujemy tak samo — DXF może zadeklarować milimetry lub cale i my zgłaszamy to, co zadeklarował, ale współrzędne nigdy nie są przeliczane, bo żadna wartość w tym API nie niesie jednostki.

Za każdym razem ta sama odpowiedź

Silnik jest deterministyczny: te same dane wejściowe zawsze zwracają ten sam wynik. W algorytmie nie ma żadnej losowości ani zegara.

Brzmi to akademicko, ale to właśnie praktyczny powód, żeby na tym budować. Oznacza bowiem, że wyniki można buforować — jeśli o dokładnie to zlecenie już raz zapytałeś, możesz bezpiecznie użyć wcześniejszej odpowiedzi, zamiast pytać ponownie. Oznacza też, że integrację można testować: plan da się porównać ze znanym, poprawnym wynikiem, a różnica jest wtedy prawdziwą różnicą, a nie szumem. Oprogramowanie, które w poniedziałek podaje klientowi cenę, w piątek podaje tę samą cenę.

Trzy silniki

API daje wybór silnika. Pierwsze dwa działają synchronicznie, trzeci jest asynchroniczny. Różnica nie polega na jakości — to kompromis między szybkością, tym, czy wynik da się pociąć na pile panelowej, i tym, jak blisko dochodzi do teoretycznego minimum.

• heuristic jest domyślny i jest tym samym, którego używa aplikacja. Tworzy układy gilotynowe: najwyższe wykorzystanie materiału, każdy układ da się pociąć na pile panelowej i zawsze pełny plan cięcia. Synchroniczny.
• balanced trzeba włączyć samemu. Korzysta zamiast tego ze swobodnego nestingu, który przy bardzo dużych zleceniach jest zdecydowanie szybszy — zmierzone ~25× szybciej przy zleceniu na 2000 elementów — za cenę nieco niższego wykorzystania materiału. Ważne zastrzeżenie: jego układów często nie da się pociąć od krawędzi do krawędzi, więc dla nich nie zwraca żadnego planu cięcia. Synchroniczny.
• max trzeba włączyć samemu i działa tylko dla 2D. To przeszukiwanie drzewa po stronie serwera, które osiąga dowiedzione optimum przy znacznie większej liczbie zleceń niż silnik domyślny, a jego układy nadal da się pociąć gilotynowo. Kosztem jest czas: obliczenie max trwa od sekund do minuty, więc nie odpowiada w treści zapytania. Zamiast tego POST /v1/optimize/2d z engine: "max" zwraca identyfikator zadania, a Ty odpytujesz GET /v1/jobs/{id}, aż będzie gotowy. Jest nadal deterministyczny. Sięgnij po niego, gdy przy dużym, wartościowym zleceniu warto poczekać na ostatnich kilka płyt. Modeluje jeden format materiału w pełnym rozmiarze płyty, w nieograniczonej ilości, więc żądanie zawierające dodatkowo drugi format materiału, trim na bok, ograniczony zapas (respectStock), materiały lub grupy słojów jest odrzucane z góry kodem 400, który nazywa dokładnie to, czego silnik nie potrafi — zanim wywołanie zostanie naliczone. Takie zlecenia kieruj do heuristic, który obsługuje je wszystkie.

Limity

Każde zapytanie ma swoje granice, więc zlecenie, które wymknęło się z ręki, kończy się wyraźnym błędem, a nie zawieszeniem:

Uzyskanie dostępu

Zacznij od strony Engine API. Engine API jest rozliczane osobno od planów aplikacji i żadna zmiana planu go nie włącza.

1. Wykup albo napisz. Wykupienie na stronie Engine API to najszybsza droga — działa z okresem próbnym, a dostęp sam pojawia się na koncie. Jeśli wolisz najpierw opisać swoją integrację albo potrzebujesz wolumenu powyżej planu standardowego, napisz do nas i podaj, co chcesz podłączyć i mniej więcej ile planów cięcia miesięcznie będzie potrzebnych.
2. Dostęp zostaje dodany do Twojego konta. Nic więcej w Twoim koncie się nie zmienia.
3. Utwórz klucz. Gdy Twoje konto ma już dostęp do API, w Twoim panelu pojawia się karta klucze API. Klucze tworzysz tam, nazywasz i usuwasz samodzielnie.
4. Skopiuj klucz od razu. Pełny klucz pokazywany jest dokładnie raz, w chwili jego utworzenia.

Traktuj klucz jak hasło: jego miejsce jest w konfiguracji Twojego oprogramowania, a nie w emailu, arkuszu kalkulacyjnym czy na zrzucie ekranu.

Co robi karta Klucze API w panelu

Trzy elementy — i warto precyzyjnie powiedzieć, co zmienia każdy z nich, zwłaszcza ostatni, po którym wiele osób spodziewa się wpływu na płatności. Nie ma go.

• Utwórz klucz. Generuje nowy klucz i pokazuje go tylko raz, od razu. Nazwa (Integracja ERP, staging) służy wyłącznie do rozróżniania kluczy później. Do 10 aktywnych kluczy na konto.
• Pasek zużycia. Dwie liczby: łączne zużycie konta w miesiącu kalendarzowym wobec limitu oraz, dla każdego klucza, ile zużył. Wartość per klucz odpowiada na pytanie, która integracja zjada pulę — nie jest osobnym budżetem.
• Wycofaj. Wyłącza ten jeden klucz od następnego wywołania. Wiersz pozostaje widoczny, żeby historia nie zniknęła.

Jeden limit na konto, nie po jednym na klucz

Każdy aktywny klucz Twojego konta czerpie z tej samej miesięcznej puli. Utworzenie drugiego klucza nie tworzy drugiego limitu — klucze służą do oddzielenia stagingu od produkcji, nadania każdej integracji własnych poświadczeń i wycofania jednego bez ruszania pozostałych.

GET /v1/usage podaje stan konta (used, limit, remaining), więc odpowiada na pytanie, które faktycznie masz — ile zostało, zanim wywołania zaczną się nie udawać — niezależnie od tego, którym kluczem zapytałeś. Gdy pula się skończy, każdy klucz zwraca 402, nie tylko ten, który ją zużył.

Cena i limit zapytań

Engine API rozliczane jest osobno od planów aplikacji, ze stałą liczbą zapytań na miesiąc. Aktualna cena, miesięczny limit zapytań i długość okresu próbnego są podane na stronie Engine API — ta strona czyta je z naszej konfiguracji cennika, więc pokazuje zawsze prawidłową wartość.

Szczegóły techniczne — dokładną strukturę zapytania i odpowiedzi, wszystkie opcje, wszystkie kody błędów oraz sposób wersjonowania — znajdziesz w dokumentacji API.

Czego to nie zmienia

Warto powiedzieć to wprost, bo Engine API łatwo błędnie odczytać jako zmianę w produkcie:

• Optymalizator w aplikacji pozostaje bez zmian. Nadal działa w Twojej przeglądarce, dokładnie tak jak wcześniej.
• Plany Bezpłatny, Pro i Warsztat są nienaruszone. Nadal zawierają optymalizator w aplikacji, z tymi samymi limitami co wcześniej. Nic nie zostało przeniesione za API.
• Nic, co robisz w aplikacji, nie zużywa zapytań API. Miesięczny limit API zużywają wyłącznie wywołania wykonywane przez Twoje własne oprogramowanie.

Engine API to dodatek dla osób integrujących CutOptim z innym oprogramowaniem. Jeśli to nie Ty, nic się nie zmieniło.