API de integración

La API de integración de CUTL te permite valorar piezas de forma programática: envía un archivo DXF o STEP desde tu propio software y recibe de vuelta la geometría y un precio completo, calculado por el mismo motor que usa la aplicación. El conjunto de endpoints disponible hoy es deliberadamente reducido, un único par de endpoints de cálculo autenticados, y hay una API de proyectos más amplia 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 y consulta Monedas y facturación para ver tarifas y recargas.

Cálculo de un solo archivo DXF / STEP

Este es el par de endpoints ya disponible. Envía un plano en base64 y después consulta el resultado por id. Solo acepta DXF y STEP (aquí el PDF se rechaza; para un plano en PDF, súbelo en la aplicación, que extrae los contornos de corte de forma interactiva). El precio se devuelve únicamente cuando se indican tanto materialId como cuttingModeId; la geometría se devuelve siempre.

# 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...\",\"count\":1}"
# → 202 { "id": "<calcId>", "status": "PENDING", "created": "..." }

# Consultar el estado, devuelve 200
curl -sS "$BASE/v2/integration/calculations/<calcId>" -H "X-Auth-Token: $TOKEN"
# → { "id": "...", "status": "PENDING|COMPLETED|FAILED",
#     "result": { "fileType", "sizeXMm", "sizeYMm", "areaSqM", "cutLengthMm", "contourCount",
#                 "weightKg", "volumeM3", "svgUrl", "thumbnailUrl", "contours": [],
#                 "materialPrice", "cuttingPrice", "incuttingPrice", "markupPercent",
#                 "singlePrice", "totalPrice", "clientSinglePrice", "clientTotalPrice" },
#     "failureReason": "..." }
# incuttingPrice es el coste de perforación; fileType indica DXF o STEP

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. Un análisis fallido devuelve FAILED con un failureReason; un token ausente u obsoleto devuelve 401.

El campo fileBase64 acepta tanto una carga DXF como una STEP: CUTL detecta el formato a partir del contenido del archivo.

Anticipo: la API completa de proyectos

La API de proyectos prevista refleja las pantallas de proyecto de la aplicación:

• Proyectos, piezas, cálculos rápidos y anidado como recursos REST bajo una ruta base versionada, con los planos subidos en base64 (DXF o STEP) y resultados que llevan las mismas cifras que muestran los paneles de la aplicación (precios antes de margen y precios de cliente, tiempos de corte, geometría, coeficientes).
• 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.
• Asíncrono en todos los procesos de cálculo: enviar una pieza o un trabajo de anidado devuelve 202 con un id de trabajo, y los resultados llegan por webhook (firmado con HMAC, entrega al menos una vez con reintentos) o por consulta periódica.
• Convenciones en el plan de desarrollo: errores problem+json según RFC 7807, claves de idempotencia en las llamadas que modifican datos, paginación en los endpoints de listado, 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.