API de integración

La API de integración de CUTL permite que tu propio software trabaje directamente con CUTL: envía un plano DXF, STEP o PDF y recibe de vuelta la geometría y un precio completo, lee tus proyectos con sus precios presupuestados, obtén el anidado de un proyecto con imágenes de las chapas y archivos DXF para la máquina, y consulta tu saldo de monedas. Los precios salen del mismo motor que usa la aplicación. La escritura de proyectos, los webhooks y los tokens múltiples siguen en diseño (consulta la sección de anticipo al final de esta página).

Autenticación

Cada petición lleva tu token de integración en un encabezado:

X-Auth-Token: <token>

• Cada cuenta tiene un token de integración. Genéralo en la aplicación, en la pestaña Integración de los ajustes de tu cuenta (la misma acción está expuesta como PUT /v2/security/user/key).
• Generar un token nuevo invalida de inmediato el anterior. Toda integración que siga usando el token antiguo empieza a fallar con 401 en ese instante, así que rota el token de forma planificada y actualiza todos los consumidores justo después de regenerarlo.
• El token concede acceso completo a la cuenta y no caduca por sí solo.

Facturación con monedas

No hay un entorno de pruebas gratuito: la API funciona contra producción y cada cálculo descuenta monedas reales del saldo de tu equipo con las mismas tarifas que la aplicación (unas 100 monedas por cálculo de pieza). Cuando el saldo es demasiado bajo, la petición se rechaza de antemano en lugar de ejecutarse y cobrarse. Planifica las pruebas de integración con moderación, vigila tu saldo en el área de facturación de la aplicación o con GET /v2/integration/balance, y consulta Monedas y facturación para ver tarifas y recargas.

Qué está disponible

Las respuestas llegan en JSON por defecto; envía Accept: application/xml si tu sistema prefiere XML.

Referencia de la API

Todos los endpoints disponibles, con sus parámetros y el esquema completo de respuesta. Pulsa Authorize y pega tu token de integración para probar las peticiones de solo lectura (GET) con tu propia cuenta. Enviar un cálculo queda para tu propio código, porque cada uno cuesta monedas.

Las secciones siguientes explican cómo se comportan los endpoints en la práctica.

Calcular un solo plano

Envía un plano en base64 y después consulta el resultado por id. CUTL detecta el tipo de archivo a partir del contenido, no del nombre del archivo. Los archivos DXF y STEP pueden ocupar hasta 2 MB, los planos PDF hasta 20 MB. El precio se devuelve únicamente cuando se indican tanto materialId como cuttingModeId; la geometría se devuelve siempre. El campo opcional units (por ejemplo MILLIMETERS o INCHES) indica a CUTL en qué unidad está realmente el plano, lo que corrige un plano cuya unidad se detectó mal.

# Enviar, devuelve 202
DXF_B64=$(base64 -i part.dxf | tr -d '\n')
curl -sS -X POST "$BASE/v2/integration/calculations" \
  -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" \
  -d "{\"fileName\":\"part.dxf\",\"fileBase64\":\"$DXF_B64\",\"materialId\":\"7e1...\",\"cuttingModeId\":\"4a8...\",\"units\":\"MILLIMETERS\"}"

# Consultar el estado, devuelve 200
curl -sS "$BASE/v2/integration/calculations/<calcId>" -H "X-Auth-Token: $TOKEN"

Cuando status pasa a COMPLETED los campos de geometría están rellenos; los campos de precio y de peso solo aparecen si se indicaron un material y un modo de corte. validationResult recoge las comprobaciones y advertencias del analizador (por ejemplo, contornos solapados o sin cerrar). Un análisis fallido devuelve FAILED con un failureReason y un errorCode como ERROR_READ_DXF, STEP_ASSEMBLY o INSUFFICIENT_BALANCE; un token ausente u obsoleto devuelve 401.

Planos PDF

Un PDF no se valora de una sola vez. CUTL extrae los contornos de corte en piezas candidatas, y la consulta completada las devuelve en pdfCandidates. Cada candidata tiene un dxfUrl (un DXF con los contornos de corte), la page de la que procede, un valor de confidence y la scale detectada, con needsScaleConfirm activado cuando el tamaño real no está confirmado. Varias candidatas pueden ser vistas distintas de la misma pieza física, así que revisa las de baja confianza. Para valorar una candidata, descarga su DXF y envíalo como un cálculo nuevo con tu material, modo de corte y unidades.

Consultar tu saldo

curl -sS "$BASE/v2/integration/balance" -H "X-Auth-Token: $TOKEN"

balance es el total disponible para gastar, monedas de bonificación incluidas, y es la cifra que CUTL comprueba antes de aceptar trabajo. Puede quedar por debajo de cero, porque algunas operaciones se facturan por artículo después de una comprobación previa. bonusBalance es la parte del total formada por monedas de bonificación, que se gastan primero. Cuando un cargo deja el saldo por debajo de lowBalanceThreshold, los administradores del equipo reciben un correo; nada deja de funcionar en ese nivel.

Leer el saldo antes de enviar un lote es la forma sencilla de evitar que se rechace trabajo por falta de monedas (402 con el código de error C00034).

Leer proyectos

# Listar proyectos, los más recientes primero, 10 por página por defecto
curl -sS "$BASE/v2/integration/projects?updatedFrom=2026-09-01&page=0&size=20" -H "X-Auth-Token: $TOKEN"

# Un proyecto completo
curl -sS "$BASE/v2/integration/projects/<projectId>" -H "X-Auth-Token: $TOKEN"

La lista admite filtros de fecha opcionales (createdFrom, createdTo, updatedFrom, updatedTo) además de page y size. Sin filtros obtienes los proyectos del equipo, los actualizados más recientemente primero. Un intervalo de fechas puede abarcar como máximo un mes; uno más largo se rechaza con 400. Cada entrada lleva el id, el name y el code del proyecto, el cliente y la organización, y sus precios: price y clientPrice (el total que se presupuesta al cliente, después del margen), junto con las cifras de impuestos.

Un proyecto individual añade el detalle que hay detrás del presupuesto:

• projectParts: cada pieza con su count, material, modo de corte, operaciones, tamaño, longitud de corte, tiempo de corte y precios (antes del margen y de cliente), más una miniatura en base64 en image.
• materialSummary: una fila por material con su superficie de corte y sus totales.
• nestingSheets: una fila por chapa física anidada, tal como se ha costeado en el presupuesto (material, tamaño de chapa, peso, coste y aprovechamiento).
• Datos del presupuesto como currency, validUntil, paymentTerm y deliveryCost.

Obtener el anidado de un proyecto

curl -sS "$BASE/v2/integration/projects/<projectId>/nesting?format=CYPCUT" -H "X-Auth-Token: $TOKEN"

Esto lee el anidado que hay detrás del presupuesto de un proyecto; no ejecuta uno nuevo. Elige la variante de DXF con format: STANDARD_DXF (la predeterminada), CYPCUT o RDWORKS. La primera llamada inicia la exportación DXF y el renderizado de las imágenes y responde PENDING; sigue consultando hasta que el estado sea READY. PARTIAL significa que algunos materiales están listos y otros han fallado, y FAILED significa que han fallado todos.

Hay una entrada en nests por material. Las chapas con una disposición idéntica se agrupan en una sola entrada con un count, así que veinte chapas idénticas vuelven como una entrada con count 20. partId coincide con el id de la pieza del endpoint de proyecto, así que puedes cruzar los dos.

Renovar un enlace de archivo

Algunas respuestas contienen URL de archivos almacenados. Para obtener un enlace firmado nuevo para una de ellas, envíala a POST /v2/integration/data-assets/signed-url con un cuerpo {"url": "<stored url>"}. La respuesta devuelve la url firmada y su hora de caducidad en expiresAt. Solo puedes firmar archivos que pertenezcan a tu propio equipo.

Anticipo: escritura, webhooks y más

La lectura ya está disponible hoy (ver arriba). Las incorporaciones previstas tratan de escritura y automatización:

• Crear y modificar proyectos, piezas, cálculos rápidos y trabajos de anidado a través de la API, con los planos subidos en base64 y resultados que llevan las mismas cifras que muestran los paneles de la aplicación.
• CRUD de diccionarios para materiales, equipos, modos de corte y clientes, de modo que las integraciones puedan gestionar los datos de referencia en lugar de duplicarlos.
• Webhooks: resultados enviados a tu sistema (firmados con HMAC, entrega al menos una vez con reintentos) en lugar de consultas periódicas.
• Convenciones en el plan de desarrollo: errores problem+json según RFC 7807, claves de idempotencia en las llamadas que modifican datos, límites de peticiones por token y una política explícita de obsolescencia de versiones principales.
• Gestión de varios tokens (listado, revocación, auditoría por token) que sustituirá al único token regenerable actual.

A continuación, consulta Monedas y facturación para entender cuánto cuesta cada cálculo y cómo mantener tu saldo recargado.