Engine API

Todo lo que CutOptim hace en tu navegador parte de un mismo cálculo: dadas estas piezas y este material, ¿cuál es la mejor forma de cortarlas? La Engine API expone exactamente ese cálculo a través de internet, para que un programa distinto pueda plantear la pregunta y recibir la respuesta — sin navegador, sin clics, sin nadie con la sesión iniciada.

Esa es toda la idea. No es un optimizador nuevo, ni un optimizador mejor, ni un plan más grande. Es el mismo motor, accesible para el software en lugar de para una persona.

¿Esto es para mí?

Para la inmensa mayoría de los usuarios de CutOptim, la respuesta honesta es no. Si tu jornada de trabajo consiste en abrir CutOptim, introducir piezas y material, e imprimir o exportar el plan, la aplicación es el producto y esta página es irrelevante para ti.

La Engine API es para una situación: los planes de corte necesitan aparecer dentro de un software que ya usas, sin que nadie visite CutOptim. En la práctica eso significa una de dos personas:

• Ya usas un software dentro del cual pertenece el plan de corte. Un ERP que guarda tus pedidos, una herramienta de presupuestos que fija precios a los trabajos, o el propio software de una máquina. En lugar de que un operario vuelva a teclear la misma lista de piezas en CutOptim, ese programa consulta el motor directamente y muestra el plan allí donde ya ocurre el trabajo.
• Estás encargando que te construyan un software. Un desarrollador interno, una empresa de software local o el proveedor de tu máquina. La Engine API es aquello a lo que ellos se conectan.

Si no tienes claro en qué lado de esa línea estás, una buena prueba: ¿podría aparecer el plan sin que nadie lo pida? Si es así, la API es relevante. Si siempre hay una persona que decide crear un plan de corte, la aplicación ya es la herramienta adecuada.

Qué hace

Tu software envía las mismas dos cosas que teclearías en la aplicación — una lista de piezas y una lista de material — en formato JSON. El motor devuelve una respuesta completa:

• El plano completo. Cada pieza, colocada en un tablero o barra concretos, incluido si se giró.
• Un plan de corte. No solo un dibujo de rectángulos: la secuencia real de cortes de guillotina, en orden, para que el plan pueda ejecutarse en una seccionadora.
• Los números. Cuántos tableros o barras requiere el trabajo, el porcentaje de aprovechamiento, cuántos cortes hacen falta y el precio total del material utilizado. Para paneles también obtienes los dos recuentos honestos de cortes — líneas de corte, que fusiona los cortes que comparten un mismo ajuste de tope, y pasadas de sierra, que cuenta cada pasada — además de la longitud total serrada.
• Opcionalmente, el dibujo. Pide include: ["svg","csv","dxf"] y la respuesta también lleva la distribución como un archivo listo para usar — un dibujo SVG 2D autónomo, un DXF R12/AC1009 o una lista de corte CSV — en línea en el JSON, sin almacenamiento y sin una segunda llamada. (SVG es solo 2D.)
• Tus propios identificadores, devueltos. Adjunta un objeto meta — un número de artículo, una línea de pedido, una referencia de cliente — a cualquier pieza o fila de material, y vuelve sin cambios en cada pieza colocada y cada tablero o barra, para que el plan cuadre con tu propio sistema. Este es el campo que debes usar cuando quieras enviar todos tus tableros, etiquetar cada uno con tu propio código y leer de vuelta qué tablero eligió el optimizador: pon el código en stock[].meta y vuelve reflejado en sheets[].meta. Nunca afecta a la colocación. No uses el campo material para identificar: material es una partición estricta (una pieza solo se corta a partir de material del mismo tipo), así que etiquetar cada fila de material con un material y dejar las piezas sin etiquetar hace que todas las piezas vuelvan como unmatched y el resultado quede vacío.

Hay cuatro modos de optimización, todos correspondientes a la aplicación — uno para paneles 2D, uno para material lineal 1D como barras, perfiles y tubo, uno para madera, donde el material tiene una sección, y el anidado por forma real (POST /v1/optimize/nest), que encaja polígonos arbitrarios para corte por láser, plasma y chorro de agua (el modo Nesting de la aplicación). Cada endpoint de optimización tiene además un endpoint de validación gratuito que comprueba una solicitud sin resolverla (ver más abajo).

Endpoints

La URL base es https://api.cutoptim.com. Los endpoints de optimización y de uso llevan una clave en una cabecera Authorization: Bearer <key>; los endpoints de validación y de disponibilidad no necesitan clave.

La mayoría de las llamadas se responden directamente con el resultado terminado. La única excepción es el motor asíncrono max (ver Tres motores más abajo): un envío max devuelve un id de trabajo, y sondeas GET /v1/jobs/{id} hasta que el plan esté listo.

Los endpoints de validación toman el mismo cuerpo que el endpoint de optimización correspondiente y lo comprueban sin ejecutar el cálculo: una solicitud mal formada vuelve como un 400 que nombra el campo exacto que falla, y una bien formada devuelve valid: true más avisos de viabilidad (por ejemplo, una pieza que no cabe en ningún material). No cuestan nada y no necesitan clave, así que puedes validar tus cargas útiles mientras construyes la integración — antes incluso de tener una clave — y confirmar que una solicitud no será rechazada sin gastar una de tus llamadas mensuales.

Por qué la madera tiene su propio endpoint

El material lineal conoce una sola dimensión, su longitud, así que cualquier barra puede servir para cualquier pieza. La madera no funciona así: una pieza de 50×150 no puede salir de una barra de 50×100, por mucha longitud que le quede. Por eso el endpoint de madera toma los dos lados de la sección en cada pieza y cada fila de material, divide el trabajo por sección, empareja cada sección con su propio material y devuelve las secciones por separado — cada una con sus propias barras y sus propios totales, junto a las cifras del trabajo completo.

Dos detalles que conviene conocer antes de integrarlo:

• Los dos lados de la sección pueden enviarse en cualquier orden. 50×100 y 100×50 son la misma barra girada, así que se emparejan como una sola sección. Eso significa que una diferencia en cómo se hayan introducido tus datos no puede hacer que desaparezca material.
• “No hay material de esta sección” y “no cupo” se informan por separado. Lo primero es un aviso de material faltante, lo segundo es un problema de capacidad, y tienen soluciones distintas — así que mezclarlos en una sola lista haría que tu usuario buscara en el sitio equivocado.

Podrías aproximar esto con varias llamadas 1d propias, agrupando tú mismo las piezas. Costaría una petición de tu cuota por sección en lugar de una por trabajo, dejaría la coincidencia de material en tu código y produciría un total del trabajo que tendrías que ensamblar tú mismo — uno que no coincidiría necesariamente con lo que la aplicación de CutOptim muestra para el mismo trabajo.

Piezas desde un archivo CAD

El endpoint de nesting no acepta solo coordenadas. Una pieza puede llevar en su lugar un source — un documento SVG o DXF — y el servidor extrae de él su contorno y los agujeros que contenga. Es el mismo lector que usa la app cuando sueltas un dibujo sobre su modo Nesting, así que una biblioteca de piezas que ya existe como archivos CAD no hay que reescribirla antes en listas de coordenadas.

El archivo sustituye solo la geometría. Cantidad, material, rotaciones permitidas y tus propios metadatos siguen siendo campos normales de la fila de la pieza, igual que cuando envías coordenadas. Un archivo describe una pieza; cuando un mismo dibujo contiene varios componentes separados, POST /v1/import/nest lo divide antes en filas listas para usar — y esa llamada requiere una clave pero no consume una solicitud de tu cuota mensual.

No se almacena nada. El archivo existe únicamente como la propia solicitud: se lee en memoria y desaparece en el momento en que se escribe la respuesta. No queda copia en disco ni en una base de datos, nada acaba en un registro y después no hay nada que borrar. Con las unidades hacemos lo mismo — un DXF puede declarar milímetros o pulgadas y nosotros informamos de lo que dijo, pero las coordenadas nunca se convierten, porque ningún valor de esta API lleva unidad.

La misma respuesta cada vez

El motor es determinista: la misma entrada siempre produce la misma salida. No hay aleatoriedad ni reloj dentro del algoritmo.

Esto suena académico pero es la razón práctica para construir sobre él. Significa que los resultados pueden cachearse — si ya preguntaste por este mismo trabajo exacto, puedes reutilizar la respuesta con seguridad en lugar de preguntar de nuevo. También significa que la integración puede probarse: un plan puede compararse con un resultado conocido como bueno, y una diferencia es una diferencia real, no ruido. Un software que le da un precio a un cliente el lunes le dará el mismo precio el viernes.

Tres motores

La API ofrece a elegir entre motores. Los dos primeros se ejecutan de forma síncrona; el tercero es asíncrono. La diferencia no es de calidad — es un compromiso entre velocidad, si el resultado puede cortarse en una seccionadora y cuánto se acerca al mínimo teórico.

• heuristic es el predeterminado y el mismo que usa la aplicación. Produce planos de guillotina: mayor aprovechamiento, todos los planos cortables en una seccionadora, y siempre un plan de corte completo. Síncrono.
• balanced es opcional. Usa anidado libre en su lugar, que es drásticamente más rápido en trabajos muy grandes — medido en aproximadamente 25× más rápido en un trabajo de 2.000 piezas — a costa de un aprovechamiento algo menor. La pega importante: sus planos a menudo no pueden cortarse de borde a borde, así que para esos no devuelve ningún plan de corte. Síncrono.
• max es opcional y solo 2D. Es una búsqueda en árbol del lado del servidor que alcanza el óptimo probado en muchos más trabajos que el predeterminado, y sus planos siguen siendo cortables con guillotina. El coste es tiempo: un cálculo max tarda de segundos a un minuto, así que no responde en la propia respuesta. En su lugar, POST /v1/optimize/2d con engine: "max" devuelve un id de trabajo, y sondeas GET /v1/jobs/{id} hasta que esté listo. Sigue siendo determinista. Recurre a él cuando un trabajo grande y valioso merezca la espera por los últimos tableros. Modela un solo formato de stock a tamaño completo de tablero, con disponibilidad ilimitada, así que una solicitud que además lleve un segundo formato de stock, trim por lado, stock limitado (respectStock), materiales o grupos de veta se rechaza de antemano con un 400 que nombra exactamente lo que no puede hacer — antes de que se cobre una llamada. Envía esos trabajos a heuristic, que los modela todos.

Límites

Cada petición está acotada, para que un trabajo desbocado falle con claridad en lugar de quedarse colgado:

Obtener acceso

Empieza en la página de la Engine API. La Engine API se factura por separado de los planes de la aplicación, y ninguna mejora de plan la activa.

1. Suscríbete, o pregunta. Suscribirte en la página de la Engine API es la vía más rápida — incluye un periodo de prueba, y el acceso llega a tu cuenta por sí solo. Si prefieres describir primero tu integración, o necesitas un volumen por encima del plan estándar, ponte en contacto en su lugar y di qué quieres conectar y aproximadamente cuántos planes de corte al mes necesitará.
2. El acceso aparece en tu cuenta. Nada más de tu cuenta cambia.
3. Crea una clave. Aparece una tarjeta de claves de API en tu panel una vez que tu cuenta tiene acceso a la API. Tú mismo creas, nombras y eliminas claves ahí.
4. Copia la clave de inmediato. La clave completa se muestra exactamente una vez, en el momento en que la creas.

Trata una clave como una contraseña: pertenece a la configuración de tu software, no a un correo, una hoja de cálculo o una captura de pantalla.

Qué hace la tarjeta de claves de API de tu panel

Tres controles, y vale la pena ser preciso sobre qué cambia cada uno — especialmente el último, que la gente espera que toque la facturación y no lo hace.

• Crear clave. Genera una clave nueva y la muestra una vez, ahí mismo. Le pones un nombre (ERP integration, staging) únicamente para poder distinguir tus claves más adelante. Hasta 10 claves activas por cuenta.
• La barra de uso. Dos números: el total de tu cuenta para el mes natural frente a la cuota mensual, y por clave, cuánto ha gastado esa clave. La cifra por clave está para responder qué integración se está comiendo el cupo — no es un presupuesto aparte.
• Revocar. Deja esa clave concreta sin funcionar, a partir de la siguiente llamada. La fila permanece visible para que no se pierda su historial.

Una cuota para la cuenta, no una por clave

Cada clave activa de tu cuenta consume del mismo cupo mensual. Crear una segunda clave no crea una segunda cuota — las claves existen para que puedas separar staging de producción, dar a cada integración su propia credencial y revocar una sin molestar a las demás.

GET /v1/usage informa de la posición de la cuenta (used, limit, remaining), de modo que responde a la pregunta que realmente tienes — cuánto queda antes de que las llamadas empiecen a fallar — con independencia de con qué clave preguntaste. Cuando se agota el cupo, todas las claves devuelven 402, no solo la que lo gastó.

Precio y cuota

La Engine API se factura por separado de los planes de la aplicación, con un número fijo de peticiones al mes. El precio actual, la cuota mensual de peticiones y la duración de la prueba están todos indicados en la página de la Engine API — esa página los lee de nuestra configuración de precios, así que siempre es la cifra exacta.

Para el detalle técnico — la forma exacta de la petición y la respuesta, todas las opciones, todos los códigos de error y cómo funciona el versionado — consulta la referencia de la API.

Qué no cambia esto

Vale la pena decirlo con claridad, porque es fácil malinterpretar la Engine API como un cambio en el producto:

• El optimizador de la aplicación no cambia. Sigue ejecutándose en tu navegador, exactamente igual que antes.
• Gratis, Pro y Taller no se ven afectados. Siguen incluyendo el optimizador integrado, con los mismos límites que antes. Nada se movió detrás de la API.
• Nada de lo que hagas en la aplicación consume peticiones de la API. La cuota mensual de la API solo se toca con las llamadas que hace tu propio software.

La Engine API es una adición para quienes integran CutOptim en otro software. Si ese no eres tú, nada ha cambiado.