API de integração

A API de integração da CUTL permite-lhe calcular o preço de peças de forma programática: envie um ficheiro DXF ou STEP a partir do seu próprio software e receba de volta a geometria e um preço completo, calculado pelo mesmo motor que a aplicação usa. Hoje a superfície disponível é deliberadamente pequena, um par de endpoints de cálculo autenticados, estando em fase de conceção uma API de projetos mais abrangente (consulte a secção de pré-visualização no final desta página).

Autenticação

Cada pedido transporta o seu token de integração num cabeçalho:

X-Auth-Token: <token>

• Cada conta tem um token de integração. Gere-o na aplicação, no separador Integração das definições da sua conta (a mesma ação está exposta como PUT /v2/security/user/key).
• Gerar um novo token invalida imediatamente o anterior. Todas as integrações que ainda usem o token antigo começam nesse momento a falhar com 401, por isso faça a rotação de forma planeada e atualize todos os consumidores logo após a regeneração.
• O token concede acesso total à conta e não expira por si só.

Faturação em moedas

Não existe sandbox gratuita: a API corre contra produção e cada cálculo debita moedas reais do saldo da sua equipa, às mesmas tarifas da aplicação (cerca de 100 moedas por cálculo de peça). Quando o saldo é demasiado baixo, o pedido é rejeitado de antemão em vez de ser executado e cobrado. Planeie os testes de integração com parcimónia, acompanhe o seu saldo na área de faturação da aplicação e consulte Moedas e faturação para tarifas e carregamentos.

Cálculo de um único ficheiro DXF / STEP

Este é o par de endpoints já disponível. Envie um desenho em base64 e consulte depois o resultado pelo id. Aceita apenas DXF e STEP (o PDF é rejeitado aqui; para um desenho em PDF, carregue-o na aplicação, que extrai os contornos de corte de forma interativa). O preço só é devolvido quando são fornecidos materialId e cuttingModeId; a geometria é sempre devolvida.

# Envio, devolve 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": "..." }

# Consulta, devolve 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 é o custo de perfuração; fileType indica DXF ou STEP

Quando o status for COMPLETED, os campos de geometria estão preenchidos; os campos de preço e de peso só aparecem quando foram fornecidos um material e um modo de corte. Uma análise falhada devolve FAILED com um failureReason; um token ausente ou desatualizado devolve 401.

O campo fileBase64 aceita um conteúdo DXF ou STEP: a CUTL deteta o formato a partir do conteúdo do ficheiro.

Pré-visualização: a API completa de projetos

A API de projetos planeada reflete os ecrãs de projeto da aplicação:

• Projetos, peças, cálculos rápidos e nesting como recursos REST sob um caminho base versionado, com os desenhos carregados em base64 (DXF ou STEP) e resultados a transportar os mesmos valores que os painéis da aplicação mostram (preços antes da margem e preços de cliente, tempos de corte, geometria, coeficientes).
• CRUD de dicionários para materiais, equipamentos, modos de corte e clientes, para que as integrações possam gerir os dados de referência em vez de os replicarem.
• Assíncrono em tudo o que envolva cálculo: enviar uma peça ou um trabalho de nesting devolve 202 com um id de trabalho e os resultados chegam por webhook (assinado com HMAC, entrega pelo menos uma vez com repetições) ou por consulta periódica.
• Convenções no roteiro: erros RFC 7807 problem+json, chaves de idempotência nas chamadas que alteram dados, paginação nos endpoints de listagem, limites de taxa por token e uma política explícita de descontinuação de versões principais.
• Gestão de múltiplos tokens (listagem, revogação, auditoria por token) a substituir o atual token único regenerável.

A seguir, consulte Moedas e faturação para compreender quanto custa cada cálculo e como manter o seu saldo carregado.