API de integração

A API de integração da CUTL permite que o seu próprio software trabalhe diretamente com a CUTL: envie um desenho DXF, STEP ou PDF e receba de volta a geometria e um preço completo, leia os seus projetos com os preços orçamentados, obtenha o nesting de um projeto com imagens das chapas e ficheiros DXF para a máquina, e consulte o seu saldo de moedas. Os preços vêm do mesmo motor que a aplicação usa. A escrita de projetos, os webhooks e os múltiplos tokens ainda estão em fase de conceção (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 ou com GET /v2/integration/balance, e consulte Moedas e faturação para tarifas e carregamentos.

O que está disponível

As respostas chegam em JSON por predefinição; envie Accept: application/xml se o seu sistema preferir XML.

Referência da API

Todos os endpoints disponíveis, com os seus parâmetros e o esquema completo de resposta. Clique em Authorize e cole o seu token de integração para experimentar os pedidos só de leitura (GET) com a sua própria conta. Submeter um cálculo fica a cargo do seu próprio código, porque cada um custa moedas.

As secções seguintes explicam como os endpoints se comportam na prática.

Calcular um único desenho

Envie um desenho em base64 e consulte depois o resultado pelo id. A CUTL deteta o tipo de ficheiro a partir do conteúdo, não do nome do ficheiro. Os ficheiros DXF e STEP podem ter até 2 MB, os desenhos PDF até 20 MB. O preço só é devolvido quando são fornecidos materialId e cuttingModeId; a geometria é sempre devolvida. O campo opcional units (por exemplo MILLIMETERS ou INCHES) indica à CUTL em que unidade o desenho está realmente, o que corrige um desenho cuja unidade foi mal detetada.

# 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...\",\"units\":\"MILLIMETERS\"}"

# Consulta, devolve 200
curl -sS "$BASE/v2/integration/calculations/<calcId>" -H "X-Auth-Token: $TOKEN"

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. O validationResult contém as verificações e os avisos do analisador (por exemplo, contornos sobrepostos ou não fechados). Uma análise falhada devolve FAILED com um failureReason e um errorCode como ERROR_READ_DXF, STEP_ASSEMBLY ou INSUFFICIENT_BALANCE; um token ausente ou desatualizado devolve 401.

Desenhos PDF

Um PDF não é orçamentado de uma só vez. A CUTL extrai os contornos de corte para peças candidatas, e a consulta concluída devolve-as em pdfCandidates. Cada candidata tem um dxfUrl (um DXF com os contornos de corte), a page de onde veio, um valor de confidence e a scale detetada, com needsScaleConfirm definido quando o tamanho real não está confirmado. Várias candidatas podem ser vistas diferentes da mesma peça física, por isso verifique as de confiança baixa. Para orçamentar uma candidata, descarregue o seu DXF e envie-o como um novo cálculo com o seu material, modo de corte e unidades.

Consultar o seu saldo

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

balance é o total disponível para gastar, incluindo as moedas de bónus, e é o número que a CUTL verifica antes de aceitar trabalho. Pode ficar abaixo de zero, porque algumas operações faturam por artigo depois de uma verificação inicial. bonusBalance é a parte do total composta por moedas de bónus, que são gastas primeiro. Quando uma cobrança deixa o saldo abaixo de lowBalanceThreshold, os administradores da equipa recebem um email; nada deixa de funcionar a esse nível.

Ler o saldo antes de enviar um lote é a forma fácil de evitar que o trabalho seja recusado por falta de moedas (402 com o código de erro C00034).

Ler projetos

# Listar projetos, os mais recentes primeiro, 10 por página por predefinição
curl -sS "$BASE/v2/integration/projects?updatedFrom=2026-09-01&page=0&size=20" -H "X-Auth-Token: $TOKEN"

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

A lista aceita filtros de data opcionais (createdFrom, createdTo, updatedFrom, updatedTo) mais page e size. Sem filtros, obtém os projetos da equipa, os atualizados mais recentemente primeiro. Um intervalo de datas pode abranger no máximo um mês; um intervalo mais longo é recusado com 400. Cada entrada inclui o id, o name e o code do projeto, o cliente e a organização, e os seus preços: price e clientPrice (o total orçamentado ao cliente, depois da margem), com os valores de imposto ao lado.

Um projeto individual acrescenta o detalhe por trás do orçamento:

• projectParts: cada peça com o seu count, material, modo de corte, operações, tamanho, comprimento de corte, tempo de corte e preços (antes da margem e de cliente), mais uma miniatura em base64 em image.
• materialSummary: uma linha por material com a sua área de corte e totais.
• nestingSheets: uma linha por chapa física com nesting, tal como custeada no orçamento (material, tamanho da chapa, peso, custo e aproveitamento).
• Detalhes do orçamento como currency, validUntil, paymentTerm e deliveryCost.

Obter o nesting de um projeto

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

Isto lê o nesting por trás do orçamento de um projeto; não executa um novo. Escolha a variante de DXF com format: STANDARD_DXF (a predefinição), CYPCUT ou RDWORKS. A primeira chamada inicia a exportação do DXF e a renderização das imagens e responde PENDING; continue a consultar até o estado ser READY. PARTIAL significa que alguns materiais estão prontos e outros falharam, e FAILED significa que todos falharam.

Há uma entrada em nests por material. As chapas com um layout idêntico são agrupadas numa única entrada com um count, pelo que vinte chapas idênticas regressam como uma entrada com count 20. O partId corresponde ao id da peça devolvido pelo endpoint do projeto, para que possa cruzar os dois.

Renovar um link de ficheiro

Algumas respostas contêm URLs de ficheiros armazenados. Para obter um novo link assinado para um deles, envie-o para POST /v2/integration/data-assets/signed-url com o corpo {"url": "<stored url>"}. A resposta devolve o url assinado e a sua hora de expiração expiresAt. Só pode assinar ficheiros que pertençam à sua própria equipa.

Pré-visualização: escrita, webhooks e mais

A leitura já está disponível hoje (ver acima). Os acréscimos planeados dizem respeito à escrita e à automação:

• Criar e alterar projetos, peças, cálculos rápidos e trabalhos de nesting através da API, com os desenhos carregados em base64 e resultados a transportar os mesmos valores que os painéis da aplicação mostram.
• 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.
• Webhooks: resultados enviados para o seu sistema (assinados com HMAC, entrega pelo menos uma vez com repetições) em vez de consulta periódica.
• Convenções no roteiro: erros RFC 7807 problem+json, chaves de idempotência nas chamadas que alteram dados, 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.