Engine API

Všechno, co CutOptim v prohlížeči dělá, začíná jedním výpočtem: mám tyto díly a tento materiál — jak je nejlépe rozřezat? Engine API zpřístupňuje přesně tento výpočet přes internet, takže se může zeptat i jiný program a odpověď dostat zpátky — bez prohlížeče, bez klikání, bez přihlášeného člověka.

A to je celá myšlenka. Není to nový optimalizátor, není to lepší optimalizátor a není to větší tarif. Je to stejné jádro, jen dostupné softwaru místo člověku.

Je to pro mě?

Pro naprostou většinu uživatelů CutOptim je poctivá odpověď ne. Pokud tvůj pracovní den vypadá tak, že otevřeš CutOptim, zadáš díly a materiál a plán vytiskneš nebo vyexportuješ, produktem je aplikace a tato stránka se tě netýká.

Engine API míří na jedinou situaci: plány řezání se mají objevovat v softwaru, který už používáš, aniž by kdokoli chodil do CutOptim. V praxi to znamená jednoho ze dvou lidí:

• Už provozuješ software, do kterého plán řezání patří. ERP, ve kterém máš zakázky, kalkulační nástroj, který zakázky cení, nebo vlastní software stroje. Místo aby operátor přepisoval stejný seznam dílů znovu do CutOptim, zeptá se ten program jádra přímo a plán zobrazí tam, kde se práce už odehrává.
• Necháváš si software postavit. Vlastním vývojářem, místní softwarovou firmou nebo dodavatelem svého stroje. Engine API je to, na co se připojí.

Pokud si nejsi jistý, na které straně té hranice stojíš, dobrý test je tento: mohl by plán vzniknout, aniž by si o něj někdo řekl? Pokud ano, API má smysl. Pokud o vytvoření plánu řezání vždycky rozhoduje člověk, správným nástrojem už je aplikace.

Co umí

Tvůj software pošle jako JSON tytéž dvě věci, které bys zadal do aplikace — seznam dílů a seznam materiálu. Jádro pošle zpátky celou odpověď:

• Celé rozvržení. Každý díl umístěný na konkrétní desce nebo tyči, včetně informace, jestli byl otočený.
• Plán řezání. Ne jen obrázek obdélníků: skutečná gilotinová sekvence řezů v pořadí, takže se plán dá provést na formátovací pile.
• Čísla. Kolik desek nebo tyčí zakázka spotřebuje, využití materiálu v procentech, kolik řezů je potřeba a celkovou cenu použitého materiálu. U desek dostaneš navíc dvě poctivé míry počtu řezů — řezy, které slučují řezy se stejným nastavením dorazu, a průjezdy pily, které počítají každý jednotlivý průjezd — a k tomu celkovou délku řezu.
• Volitelně i výkres. Požádej o include: ["svg","csv","dxf"] a odpověď ponese rozvržení i jako hotový soubor — samostatný 2D výkres SVG, DXF ve formátu R12/AC1009 nebo seznam řezů CSV — přímo v JSON, bez úložiště a bez druhého volání. (SVG je jen 2D.)
• Vaše vlastní identifikátory, vrácené zpět. Připoj objekt meta — číslo artiklu, řádek zakázky, referenci zákazníka — k jakémukoli dílu nebo řádku materiálu a vrátí se beze změny u každého umístěného kusu i u každé desky nebo tyče, takže plán sedí s tvým vlastním systémem. Právě tohle je pole, po kterém sáhneš, když chceš poslat všechny své desky, každou označit vlastním kódem a zpětně si přečíst, kterou desku optimalizátor zvolil — kód vlož do stock[].meta a vrátí se ti v sheets[].meta. Na rozmístění nemá nikdy vliv. K identifikaci nepoužívej pole material: material je tvrdé rozdělení (díl se řeže jen ze zásoby stejného materiálu), takže označit materiálem každý řádek zásoby a díly nechat neoznačené znamená, že se všechny díly vrátí jako unmatched a výsledek bude prázdný.

Optimalizační režimy jsou čtyři a všechny odpovídají aplikaci — jeden pro 2D desky, jeden pro 1D lineární materiál (tyče, profily, trubky), jeden pro dřevo, jehož materiál má průřez, a nesting podle skutečného tvaru (POST /v1/optimize/nest), který skládá libovolné polygony pro řezání laserem, plazmou a vodním paprskem (režim Nesting aplikace). Každý optimalizační endpoint má navíc bezplatný endpoint pro validaci, který požadavek zkontroluje bez výpočtu (viz níže).

Endpointy

Základní URL je https://api.cutoptim.com. Optimalizační endpointy a endpoint spotřeby nesou klíč v hlavičce Authorization: Bearer <key>; validační a stavový endpoint žádný klíč nepotřebují.

Většina volání se rovnou zodpoví hotovým výsledkem. Jedinou výjimkou je asynchronní jádro max (viz Tři jádra níže): odeslání úlohy max vrátí id úlohy a vy se dotazujete na GET /v1/jobs/{id}, dokud není plán připravený.

Validační endpointy přijímají stejné tělo jako odpovídající optimalizační endpoint a zkontrolují ho, aniž by spustily výpočet: chybně sestavený požadavek se vrátí jako 400 s uvedením přesně toho špatného pole a správně sestavený vrátí valid: true plus upozornění na proveditelnost (například díl, který se nevejde do žádného materiálu). Nic nestojí a nepotřebují klíč, takže si můžeš svá těla požadavků ověřovat už při stavbě integrace — ještě než vůbec máš klíč — a potvrdit si, že požadavek nebude odmítnut, aniž bys utratil jedno ze svých měsíčních volání.

Proč má dřevo vlastní endpoint

Lineární materiál zná jediný rozměr, délku, takže každá tyč může posloužit každému dílu. U dřeva to neplatí: díl 50×150 z tyče 50×100 nevyřežete, ať zbývá jakákoli délka. Endpoint pro dřevo proto u každého dílu i u každé položky materiálu přebírá obě strany průřezu, rozdělí zakázku podle průřezu, přiřadí každému průřezu jeho vlastní materiál a průřezy vrátí odděleně — každý s vlastními tyčemi a vlastními součty, vedle čísel za celou zakázku.

Dvě věci, které je dobré znát před integrací:

• Obě strany průřezu lze poslat v libovolném pořadí. 50×100 a 100×50 je tentýž otočený hranol a patří do jednoho průřezu. Rozdíl v tom, jak byla vaše data zrovna zadána, tedy nemůže způsobit, že materiál zmizí.

• „Žádný materiál tohoto průřezu“ a „nevešlo se“ se hlásí odděleně. První je chybějící materiál, druhé problém kapacity a každé se řeší jinak — smíchané v jednom seznamu pošlou vašeho uživatele hledat na špatné místo.

Totéž byste mohli přiblížit několika vlastními voláními 1d a díly si seskupit sami. Stálo by to jeden požadavek z kvóty na průřez místo jednoho na zakázku, přesunulo by to přiřazování materiálu do vašeho kódu a vzniklý součet za zakázku byste museli složit sami — a nemusel by se shodovat s tím, co pro stejnou zakázku ukazuje aplikace CutOptim.

Díly z CAD souboru

Nesting endpoint nepřijímá jen souřadnice. Díl může místo nich nést source — dokument SVG nebo DXF — a server z něj načte obrys i otvory v něm. Je to tentýž čteč, jaký používá aplikace, když na její režim Nesting přetáhnete výkres, takže knihovnu dílů, která už existuje jako CAD soubory, není nutné nejdřív přepsat na seznamy souřadnic.

Soubor nahrazuje pouze geometrii. Množství, materiál, povolená otočení i vaše vlastní metadata zůstávají běžnými poli řádku dílu, přesně jako když posíláte souřadnice. Jeden soubor popisuje jeden díl; když jeden výkres obsahuje několik samostatných součástí, POST /v1/import/nest jej nejprve rozdělí na hotové řádky — a toto volání vyžaduje klíč, ale nespotřebuje požadavek z vaší měsíční kvóty.

Nic se neukládá. Soubor existuje pouze jako samotný požadavek: čte se v paměti a v okamžiku, kdy je zapsána odpověď, mizí. Nezůstává kopie na disku ani v databázi, nic nekončí v logu a poté není co mazat. S jednotkami postupujeme stejně — DXF může deklarovat milimetry nebo palce a my hlásíme, co uvedl, ale souřadnice nikdy nepřepočítáváme, protože žádná hodnota v tomto API nenese jednotku.

Pokaždé stejná odpověď

Jádro je deterministické: stejný vstup vrací vždy stejný výstup. V algoritmu není žádná náhoda ani hodiny.

Zní to akademicky, ale právě to je praktický důvod, proč na tom stavět. Znamená to, že se výsledky dají cachovat — pokud jsi se na přesně tuto zakázku už ptal, můžeš odpověď bezpečně použít znovu místo dalšího dotazu. A také to znamená, že se propojení dá testovat: plán se dá porovnat se známým správným výsledkem a rozdíl je pak skutečný rozdíl, ne šum. Software, který zákazníkovi v pondělí nacení zakázku, ji v pátek nacení stejně.

Tři jádra

API nabízí na výběr z jader. První dvě běží synchronně, třetí asynchronně. Rozdíl není v kvalitě — je to kompromis mezi rychlostí, tím, jestli se výsledek dá rozřezat na formátovací pile, a tím, jak blízko se dostane k teoretickému minimu.

• heuristic je výchozí a je to totéž jádro, které používá aplikace. Vytváří gilotinová rozvržení: nejvyšší využití materiálu, každé rozvržení je řezatelné na formátovací pile a vždy je k němu plný plán řezání. Synchronní.
• balanced si zapneš sám. Používá místo toho volný nesting, který je na hodně velkých zakázkách dramaticky rychlejší — naměřeno asi 25× rychleji na zakázce s 2 000 díly — za cenu o něco nižšího využití materiálu. Důležitá past: jeho rozvržení často nelze rozřezat od hrany k hraně, takže u nich nevrací žádný plán řezání. Synchronní.
• max si zapneš sám a je jen 2D. Je to serverové prohledávání stromu, které dosahuje prokázaného optima u mnohem více zakázek než výchozí jádro, a jeho rozvržení jsou stále řezatelná na gilotině. Cenou je čas: výpočet max trvá sekundy až minutu, takže neodpovídá v samotné odpovědi. Místo toho POST /v1/optimize/2d s engine: "max" vrátí id úlohy a vy se dotazujete na GET /v1/jobs/{id}, dokud není hotová. Stále je deterministické. Sáhni po něm, když se u velké, hodnotné zakázky vyplatí počkat na posledních pár desek. Modeluje jediný formát materiálu v plné velikosti desky a v neomezeném množství, takže požadavek, který navíc nese druhý formát materiálu, trim po stranách, omezené zásoby (respectStock), materiály nebo skupiny vláken, je předem odmítnut kódem 400, který přesně pojmenuje, co jádro neumí — ještě než se volání účtuje. Takové zakázky posílejte do heuristic, které je zvládne všechny.

Limity

Každý požadavek má své hranice, takže zakázka, která se vymkne, jasně selže a nezůstane viset:

Jak získat přístup

Začni na stránce Engine API. Engine API se účtuje odděleně od tarifů aplikace a nezapne ho žádná změna tarifu.

1. Předplať si ho, nebo napiš. Předplatné na stránce Engine API je nejrychlejší cesta — běží se zkušebním obdobím a přístup dorazí na účet sám. Pokud chceš nejdřív popsat svou integraci nebo potřebuješ objem nad rámec standardního tarifu, napiš nám a uveď, co chceš propojit a kolik plánů řezu měsíčně to zhruba bude potřebovat.
2. Přístup ti přidáme na účet. Nic jiného se na tvém účtu nemění.
3. Vytvoř si klíč. Jakmile má tvůj účet přístup k API, objeví se na tvé nástěnce karta API klíče. Klíče si tam sám vytváříš, pojmenováváš a mažeš.
4. Zkopíruj si klíč hned. Celý klíč se zobrazí právě jednou, v okamžiku, kdy ho vytvoříš.

Ke klíči se chovej jako k heslu: patří do konfigurace tvého softwaru, ne do e-mailu, do tabulky nebo na snímek obrazovky.

Co dělá karta API klíče na nástěnce

Tři ovládací prvky — a stojí za to přesně říct, co který mění, hlavně ten poslední, u kterého mnozí čekají dopad na placení. Nemá ho.

• Vytvořit klíč. Vygeneruje nový klíč a jednou ho tam zobrazí. Název (ERP integrace, staging) slouží jen k tomu, abyste klíče později rozeznali. Až 10 aktivních klíčů na účet.
• Ukazatel spotřeby. Dvě čísla: celková spotřeba účtu za kalendářní měsíc vůči kvótě a u každého klíče, kolik spotřeboval on. Číslo u klíče odpovídá na to, která integrace kvótu spotřebovává — není to samostatný rozpočet.
• Odvolat. Od dalšího volání ten jeden klíč vyřadí. Řádek zůstává vidět, aby se neztratila historie.

Jedna kvóta pro účet, ne jedna na klíč

Každý aktivní klíč vašeho účtu čerpá ze stejné měsíční kvóty. Druhý klíč nevytvoří druhou kvótu — klíče jsou od toho, abyste oddělili staging od produkce, dali každé integraci vlastní přihlašovací údaj a jeden odvolali, aniž byste rušili ostatní.

GET /v1/usage hlásí stav účtu (used, limit, remaining), takže odpovídá na otázku, kterou skutečně máte — kolik zbývá, než volání začnou selhávat — bez ohledu na to, kterým klíčem jste se ptali. Když kvóta dojde, vrací 402 každý klíč, ne jen ten, který ji spotřeboval.

Cena a kvóta

Engine API se účtuje odděleně od tarifů aplikace a má pevný počet požadavků za měsíc. Aktuální cenu, měsíční kvótu požadavků i délku zkušebního období najdeš na stránce Engine API — ta si je čte z naší konfigurace ceníku, takže tam je vždy platné číslo.

Technické podrobnosti — přesnou podobu požadavku a odpovědi, všechny volby, všechny chybové kódy i to, jak funguje verzování — najdeš v referenci API.

Co se tím nemění

Stojí za to to říct naplno, protože Engine API se dá snadno špatně přečíst jako změna produktu:

• Optimalizátor v aplikaci zůstává beze změny. Dál běží v tvém prohlížeči, přesně jako dřív.
• Tarify Zdarma, Pro a Dílna se nemění. Optimalizátor v aplikaci v nich zůstává zahrnutý se stejnými limity jako dřív. Nic se za API nepřesunulo.
• Nic, co v aplikaci uděláš, nespotřebovává požadavky API. Měsíční kvótu API ubírají jen volání, která pošle tvůj vlastní software.

Engine API je doplněk pro ty, kdo CutOptim zapojují do jiného softwaru. Pokud to nejsi ty, nezměnilo se nic.