Engine API

Tutto quello che CutOptim fa nel tuo browser parte da un solo calcolo: dati questi pezzi e questo materiale, qual è il modo migliore di tagliarli? L’Engine API espone esattamente quel calcolo su internet, così un programma diverso può porre la domanda e riavere la risposta — senza browser, senza clic, senza che nessuno abbia fatto l’accesso.

È tutta l’idea. Non è un nuovo ottimizzatore, non è un ottimizzatore migliore e non è un livello di abbonamento superiore. È lo stesso motore, raggiungibile da un software invece che da una persona.

Fa per me?

Per la grandissima maggioranza degli utenti di CutOptim, la risposta onesta è no. Se la tua giornata di lavoro consiste nell’aprire CutOptim, inserire pezzi e materiale e stampare o esportare il piano, l’app è il prodotto e questa pagina non ti riguarda.

L’Engine API serve a una sola situazione: i piani di taglio devono comparire dentro un software che già usi, senza che nessuno visiti CutOptim. In pratica si tratta di uno di questi due casi:

• Usi già un software dentro cui il piano di taglio dovrebbe stare. Un ERP che tiene i tuoi ordini, uno strumento di preventivazione che calcola il prezzo dei lavori, o il software della macchina stessa. Invece di far ribattere a un operatore la stessa distinta di pezzi in CutOptim, quel programma interroga direttamente il motore e mostra il piano dove il lavoro avviene già.
• Ti stai facendo sviluppare un software. Da uno sviluppatore interno, da una software house locale o dal fornitore della tua macchina. L’Engine API è ciò a cui si collegano.

Se non sei sicuro da quale lato di quella linea ti trovi, una buona prova: il piano potrebbe comparire senza che nessuno lo chieda? Se sì, l’API è pertinente. Se è sempre una persona a decidere di fare un piano di taglio, l’app è già lo strumento giusto.

Cosa fa

Il tuo software invia le stesse due cose che inseriresti nell’app — un elenco di pezzi e un elenco di materiale — in JSON. Il motore restituisce una risposta completa:

• Lo schema completo. Ogni pezzo, posizionato su un pannello o su una barra precisi, compresa l’indicazione se è stato ruotato.
• Un piano di taglio. Non solo un disegno di rettangoli: la vera sequenza di taglio guillotine, in ordine, così che il piano possa essere eseguito su una sezionatrice.
• I numeri. Quanti pannelli o barre richiede il lavoro, la percentuale di resa, quanti tagli servono e il prezzo totale del materiale usato. Per i pannelli ottieni anche i due conteggi onesti dei tagli — le linee di taglio, che uniscono i tagli che condividono un’unica regolazione della guida, e i passaggi della lama, che contano ogni singolo passaggio — più la lunghezza totale tagliata.
• Opzionalmente, il disegno. Chiedi include: ["svg","csv","dxf"] e la risposta trasporta anche lo schema come file già pronto — un disegno SVG 2D autonomo, un DXF R12/AC1009 o una distinta di taglio CSV — inline nel JSON, senza archiviazione e senza una seconda chiamata. (L’SVG è solo 2D.)
• I tuoi identificativi, restituiti. Allega un oggetto meta — un codice articolo, una riga d’ordine, un riferimento cliente — a qualsiasi pezzo o riga di materiale, e torna invariato su ogni pezzo posizionato e su ogni pannello o barra, così il piano si allinea con il tuo sistema. È questo il campo da usare quando vuoi inviare tutti i tuoi pannelli, contrassegnare ciascuno con un tuo codice e rileggere quale pannello ha scelto l’ottimizzatore: metti il codice in stock[].meta e ti torna su sheets[].meta. Non influisce mai sul posizionamento. Non usare invece il campo material per identificare: material è una partizione rigida (un pezzo viene tagliato solo da righe di materiale con lo stesso valore material), quindi assegnare un material a ogni riga di materiale lasciando i pezzi senza tag fa tornare ogni pezzo come unmatched, con un risultato vuoto.

Le modalità di ottimizzazione sono quattro, tutte corrispondenti all’app — una per i pannelli 2D, una per il materiale 1D lineare come barre, profili e tubi, una per il legno, dove il materiale ha una sezione, e il nesting a forma reale (POST /v1/optimize/nest), che annida poligoni arbitrari per il taglio laser, plasma e a getto d’acqua (la modalità Nesting dell’app). Ogni endpoint di ottimizzazione ha anche un endpoint di validazione gratuito che verifica una richiesta senza risolverla (vedi sotto).

Endpoint

La base URL è https://api.cutoptim.com. Gli endpoint di ottimizzazione e usage portano una chiave in un header Authorization: Bearer <key>; gli endpoint di validazione e health non richiedono alcuna chiave.

La maggior parte delle chiamate riceve direttamente il risultato finito. L’unica eccezione è il motore asincrono max (vedi Tre motori più sotto): un invio max restituisce un id di lavoro e interroghi GET /v1/jobs/{id} finché il piano non è pronto.

Gli endpoint di validazione prendono lo stesso corpo dell’endpoint di ottimizzazione corrispondente e lo verificano senza eseguire la risoluzione: una richiesta malformata torna come 400 che indica il campo esatto sbagliato, mentre una ben formata restituisce valid: true più avvisi di fattibilità (per esempio un pezzo che non entra in alcun materiale). Non costano nulla e non richiedono alcuna chiave, così puoi validare i tuoi payload mentre costruisci l’integrazione — ancora prima di avere una chiave — e confermare che una richiesta non verrà rifiutata senza spendere una delle tue chiamate mensili.

Perché il legno ha un endpoint dedicato

Il materiale lineare conosce una sola dimensione, la lunghezza, quindi qualsiasi barra può servire qualsiasi pezzo. Con il legno non funziona così: un pezzo 50×150 non può uscire da una barra 50×100, per quanta lunghezza avanzi. L’endpoint del legno prende perciò entrambi i lati della sezione su ogni pezzo e ogni riga di materiale, divide il lavoro per sezione, abbina a ciascuna sezione il proprio materiale e restituisce le sezioni separatamente — ognuna con le proprie barre e i propri totali, accanto ai numeri dell’intero lavoro.

Due dettagli da conoscere prima di integrarlo:

• I due lati della sezione si possono inviare in qualsiasi ordine. 50×100 e 100×50 sono la stessa trave girata e vengono trattate come un’unica sezione. Così una differenza nel modo in cui i tuoi dati sono stati inseriti non può far sparire del materiale.

• «Nessun materiale di questa sezione» e «non è entrato» sono segnalati separatamente. Il primo è un problema di materiale mancante, il secondo di capacità, e si risolvono in modi diversi — mescolarli in un unico elenco manderebbe il tuo utente a cercare nel posto sbagliato.

Potresti approssimare tutto questo con più chiamate 1d tue, raggruppando i pezzi da solo. Ti costerebbe una richiesta di quota per sezione invece di una per il lavoro, sposterebbe l’abbinamento del materiale nel tuo codice e produrrebbe un totale che dovresti comporre tu — e che non coinciderebbe necessariamente con quanto l’app CutOptim mostra per lo stesso lavoro.

Pezzi da un file CAD

L’endpoint di nesting non accetta solo coordinate. Un pezzo può portare invece un source — un documento SVG o DXF — e il server ne estrae il contorno, e gli eventuali fori, dal file. È lo stesso lettore che l’app usa quando trascini un disegno sulla sua modalità Nesting, quindi una libreria di pezzi che esiste già come file CAD non va prima riscritta in elenchi di coordinate.

Il file sostituisce solo la geometria. Quantità, materiale, rotazioni ammesse e i tuoi metadati restano campi ordinari della riga del pezzo, esattamente come quando invii coordinate. Un file descrive un pezzo; quando un singolo disegno contiene più componenti separati, POST /v1/import/nest lo divide prima in righe pronte — e quella chiamata richiede una chiave ma non consuma una richiesta della tua quota mensile.

Nulla viene memorizzato. Il file esiste solo come la richiesta stessa: viene letto in memoria e sparisce nel momento in cui la risposta è scritta. Non resta copia su disco o in un database, nulla finisce in un log e non c’è nulla da cancellare dopo. Con le unità facciamo lo stesso — un DXF può dichiarare millimetri o pollici e noi riportiamo ciò che ha detto, ma le coordinate non vengono mai convertite, perché nessun valore di questa API porta un’unità.

Sempre la stessa risposta

Il motore è deterministico: lo stesso input produce sempre lo stesso output. Non c’è casualità e non c’è nessun orologio dentro l’algoritmo.

Suona accademico, ma è la ragione pratica per costruirci sopra. Significa che i risultati possono essere messi in cache — se hai già chiesto di questo lavoro esatto, puoi riutilizzare la risposta in sicurezza invece di richiederla di nuovo. Significa anche che l’integrazione può essere testata: un piano può essere confrontato con un risultato noto come corretto, e una differenza è una differenza reale, non rumore. Un software che lunedì preventiva un prezzo a un cliente, venerdì preventiverà lo stesso prezzo.

Tre motori

L’API offre la scelta del motore. I primi due funzionano in modo sincrono; il terzo è asincrono. La differenza non è la qualità — è un compromesso tra velocità, realizzabilità del risultato su una sezionatrice e quanto ci si avvicina al minimo teorico.

• heuristic è il predefinito ed è lo stesso che usa l’app. Produce schemi guillotine: resa massima, ogni schema tagliabile su una sezionatrice, e sempre un piano di taglio completo. Sincrono.
• balanced si attiva su richiesta. Usa invece il nesting libero, che è enormemente più rapido sui lavori molto grandi — misurato circa 25× più rapido su un lavoro da 2.000 pezzi — al costo di una resa leggermente inferiore. L’insidia importante: i suoi schemi spesso non sono tagliabili da bordo a bordo, quindi per quelli non restituisce alcun piano di taglio. Sincrono.
• max si attiva su richiesta ed è solo 2D. È una ricerca ad albero lato server che raggiunge l’ottimo dimostrato su molti più lavori rispetto al predefinito, e i suoi schemi restano tagliabili a guillotine. Il costo è il tempo: una risoluzione max richiede da secondi a un minuto, quindi non risponde nella risposta. Invece, POST /v1/optimize/2d con engine: "max" restituisce un id di lavoro, e interroghi GET /v1/jobs/{id} finché non è pronto. Rimane deterministico. Ricorri a esso quando un lavoro grande e di valore vale l’attesa per gli ultimi pannelli. Modella un solo formato di stock a piena dimensione con disponibilità illimitata, quindi una richiesta che porta anche un secondo formato di stock, trim per lato, stock limitato (respectStock), materiali o gruppi di venatura viene rifiutata in anticipo con un 400 che indica esattamente ciò che non può fare — prima che una chiamata venga addebitata. Manda quei lavori a heuristic, che li modella tutti.

Limiti

Ogni richiesta ha dei limiti, così un lavoro fuori controllo fallisce in modo chiaro invece di rimanere bloccato:

Ottenere l’accesso

Parti dalla pagina Engine API. L’Engine API è fatturata separatamente dai piani dell’app e nessun passaggio di piano la attiva.

1. Abbonati, oppure scrivici. Abbonarsi dalla pagina Engine API è la via più rapida: prevede un periodo di prova e l’accesso arriva da solo sul tuo account. Se preferisci descrivere prima la tua integrazione, o ti serve un volume oltre il piano standard, scrivici e indica che cosa vuoi collegare e all’incirca quanti piani di taglio al mese servono.
2. L’accesso viene aggiunto al tuo account. Nient’altro del tuo account cambia.
3. Crea una chiave. Una card chiavi API compare nella tua dashboard quando il tuo account ha l’accesso API. Le chiavi le crei, le nomini e le elimini lì tu stesso.
4. Copia subito la chiave. La chiave completa viene mostrata una sola volta, nel momento in cui la crei.

Tratta una chiave come una password: sta nella configurazione del tuo software, non in un’email, in un foglio di calcolo o in uno screenshot.

Che cosa fa la scheda Chiavi API nella dashboard

Tre comandi, e vale la pena essere precisi su cosa cambia ciascuno — soprattutto l’ultimo, che molti si aspettano tocchi la fatturazione. Non la tocca.

• Crea chiave. Genera una nuova chiave e la mostra una volta sola, lì. Il nome (Integrazione ERP, staging) serve solo a distinguerle in seguito. Fino a 10 chiavi attive per account.
• La barra di utilizzo. Due numeri: il totale del tuo account per il mese solare rispetto alla quota, e per ciascuna chiave quanto ha consumato. Il dato per chiave risponde a quale integrazione sta consumando il monte — non è un budget separato.
• Revoca. Blocca quella singola chiave dalla chiamata successiva. La riga resta visibile, così lo storico non va perso.

Una quota per l’account, non una per chiave

Ogni chiave attiva del tuo account attinge allo stesso monte mensile. Creare una seconda chiave non crea una seconda quota — le chiavi servono a separare staging e produzione, dare a ogni integrazione la propria credenziale e revocarne una senza disturbare le altre.

GET /v1/usage riporta la posizione dell’account (used, limit, remaining) e risponde quindi alla domanda che hai davvero — quanto resta prima che le chiamate falliscano — indipendentemente dalla chiave con cui hai chiesto. Esaurito il monte, ogni chiave restituisce 402, non solo quella che l’ha speso.

Prezzo e quota

L’Engine API viene fatturata separatamente dai piani dell’app, con un numero fisso di richieste al mese. Il prezzo attuale, la quota mensile di richieste e la durata della prova sono tutti indicati sulla pagina Engine API — quella pagina li legge dalla nostra configurazione dei prezzi, quindi il dato è sempre quello corretto.

Per il dettaglio tecnico — la struttura esatta di richiesta e risposta, tutte le opzioni, tutti i codici di errore e come funziona il versionamento — vedi il riferimento API.

Cosa non cambia

Vale la pena dirlo con chiarezza, perché l’Engine API si può facilmente fraintendere come un cambiamento del prodotto:

• L’ottimizzatore nell’app è invariato. Gira ancora nel tuo browser, esattamente come prima.
• Gratuito, Pro e Officina non sono toccati. Includono ancora l’ottimizzatore integrato nell’app, con gli stessi limiti di prima. Niente è stato spostato dietro l’API.
• Niente di ciò che fai nell’app consuma richieste API. La quota API mensile viene toccata solo dalle chiamate che fa il tuo software.

L’Engine API è un’aggiunta per chi integra CutOptim in altri software. Se non è il tuo caso, non è cambiato niente.