Documentação da API

Autenticação — tokens API de longa duração

O Handifyit usa Tokens API de longa duração para chamadas automáticas ou do servidor. Permanecem válidos até serem revogados explicitamente. Siga estes três passos para obter um.

POST /login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "yourpassword"
}

→ 200 OK
{
  "access_token":  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

POST /api/tokens
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "My Production App"
}

→ 201 Created
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",  ← guarde este valor!
  "name": "My Production App"
}

POST /api/optimize
Authorization: Bearer <your-api-token>
Content-Type: application/json

{ ... corpo do pedido ... }

Corpo comum do pedido

Os seis endpoints de otimização aceitam o mesmo corpo JSON. Só materials, stock_plates, parts e optimize_type são obrigatórios; os restantes campos têm valores predefinidos.

Exemplo completo de pedido

{
  "materials": [
    { "id": 1, "name": "Plywood 18mm", "identifier": "PLY18", "thickness": 18 }
  ],
  "stock_plates": [
    { "width": 2440, "height": 1220, "quantity": 5, "material_id": 1 }
  ],
  "parts": [
    { "width": 800, "height": 600, "quantity": 4, "material_id": 1, "can_rotate": true  },
    { "width": 400, "height": 300, "quantity": 8, "material_id": 1, "can_rotate": false }
  ],
  "optimize_type":           "saw",
  "blade_width":              5,
  "trim_stock_plate":         10,
  "allow_mixed_stock_sizes":  true,
  "pattern_direction":       "none",
  "performance_mode":        "normal",
  "random_seed":              0
}

Executa o otimizador e devolve a disposição completa em JSON. Não cria ficheiros; use este endpoint para processar ou apresentar resultados na sua aplicação.

Estrutura da resposta

{
  "results": [
    {
      "material": { "id": 1, "name": "Plywood 18mm", "identifier": "PLY18",
                    "thickness": 18 },
      "layouts": [
        {
          "stock_width":  2420,
          "stock_height": 1200,
          "stock_index":  0,
          "cuts": [
            { "x": 0,   "y": 0,   "width": 800, "height": 600, "part_id": 0 },
            { "x": 805, "y": 0,   "width": 400, "height": 300, "part_id": 1 },
            { "x": 805, "y": 305, "width": 400, "height": 300, "part_id": 1 }
          ],
          "cut_length_mm":     10420,
          "cut_length_method": "guillotine",
          "offcuts": [
            { "x": 1220, "y": 0, "width": 1220, "height": 1220 },
            …
          ],
          "saw_plan": {
            "kind": "split", "x": 0, "y": 0, "width": 2440, "height": 1220,
            "axis": "x", "cuts": [5, 810, 1215],
            "children": [
              { "kind": "offcut", "x": 0, "y": 0, "width": 5, "height": 1220 },
              { "kind": "split", "x": 10, "y": 0, "width": 800, "height": 1220,
                "axis": "y", "cuts": [5, 610],
                "children": [
                  { "kind": "offcut", "x": 10, "y": 0, "width": 800, "height": 5 },
                  { "kind": "part", "x": 10, "y": 10, "width": 800, "height": 600,
                    "cut_index": 0 },
                  …
                ] },
              …
            ]
          }
        }
      ],
      "summary": {
        "total_stock_used":    1,
        "total_parts":         12,
        "material_efficiency": 91.8,
        "total_cut_length_mm": 10420
      }
    }
  ]
}

Otimiza e gera um PDF com várias páginas, uma por painel. Guarda-o na nuvem e devolve um URL de transferência assinado.

Pedido

Mesmo corpo JSON que /api/optimize (ver acima).

Resposta

{
  "files": [
    {
      "name": "layout-1708433600000.pdf",
      "url":  "https://storage.example.com/pdf/1708433600000/layout-1708433600000.pdf"
    }
  ]
}

A resposta contém um único PDF com todos os painéis.

Otimiza e gera um DXF por painel, compatível com a maioria dos sistemas CAD/CAM e controladores CNC (AutoCAD, Fusion 360, Mach3, etc.). Devolve URLs individuais dos ficheiros guardados.

Pedido

Mesmo corpo JSON que /api/optimize (ver acima).

Resposta

{
  "files": [
    {
      "name": "plate-1-25318.dxf",
      "url":  "https://storage.example.com/dxf/1708433600000/plate-1-25318.dxf"
    },
    {
      "name": "plate-2-25318.dxf",
      "url":  "https://storage.example.com/dxf/1708433600000/plate-2-25318.dxf"
    }
  ]
}

Um ficheiro por painel. O nome inclui o índice e a execução: plate-1-25318.dxf corresponde ao painel 1 da execução 25318.

Otimiza e gera um CSV com todas as peças de todos os materiais e painéis. Cada linha inclui posição, dimensões da peça e painel, nome e código do material, para folhas de cálculo, ERP ou pós-processadores. Guarda o ficheiro na nuvem e devolve o URL.

Pedido

Mesmo corpo JSON que /api/optimize (ver acima).

Colunas CSV

Part ID, x, y, width, height, stock_width, stock_height, material(as name), material(as identifier)

Resposta

{
  "files": [
    {
      "name": "layout-1708433600000.csv",
      "url":  "https://storage.example.com/csv/1708433600000/layout-1708433600000.csv"
    }
  ]
}

Um único CSV com todos os cortes de todos os materiais e painéis.

Otimiza e gera um SVG por painel. Estes gráficos vetoriais escaláveis servem para pré-visualizações web e importação no Inkscape, Illustrator ou Figma. Devolve URLs individuais dos ficheiros guardados.

Pedido

Mesmo corpo JSON que /api/optimize (ver acima).

Resposta

{
  "files": [
    {
      "name": "plate-1-25318.svg",
      "url":  "https://storage.example.com/svg/1708433600000/plate-1-25318.svg"
    },
    {
      "name": "plate-2-25318.svg",
      "url":  "https://storage.example.com/svg/1708433600000/plate-2-25318.svg"
    }
  ]
}

Otimiza e gera um PTX (Pattern Exchange) por grupo de material. Este formato para serras HOLZMA / HOMAG é aceite pelo HolzLink, CADmatic 4/5 e HOMAG intelliDivide. Cada ficheiro contém o trabalho do material, padrões e sequências de corte. Devolve os URLs dos ficheiros na nuvem.

Pedido

Mesmo corpo JSON que /api/optimize (ver acima). optimize_type: "saw" gera disposições de guilhotina adequadas a serras de painéis.

Resposta

{
  "files": [
    {
      "name": "J1708433600000.PTX",
      "url":  "https://storage.example.com/ptx/1708433600000/J1708433600000.PTX"
    }
  ]
}

Envie DXF como multipart/form-data. A resposta é um ValidationReport completo: um PartResult por peça com operações e violações.

Campos do pedido (multipart)

Campos de ValidationConfig

Exemplo de pedido (curl)

curl -X POST https://handifyit.com/api/validate-cnc \
  -H "Authorization: Bearer <your-api-token>" \
  -F "[email protected]" \
  -F 'config={"part_min_width":50,"part_min_height":50,\
              "part_max_width":2800,"part_max_height":2070,\
              "drill_min_diameter":2,"drill_max_diameter":35,\
              "min_edge_offset":8,"min_op_spacing":8,\
              "groove_aspect_ratio":3,"unit":"mm"}'

Exemplo de resposta

{
  "valid": false,
  "summary": {
    "total_parts":      3,
    "total_operations": 12,
    "total_issues":     2,
    "errors":           1,
    "warnings":         1
  },
  "parts": [
    {
      "id":    "part_1",
      "layer": "PART",
      "bbox":  { "min_x": 0, "min_y": 0, "max_x": 400, "max_y": 300,
                 "width": 400, "height": 300 },
      "operations": [
        {
          "id":     "op_1",
          "kind":   "drilling",
          "side":   "through",
          "layer":  "DRILL",
          "bbox":   { "min_x": 46, "min_y": 46, "max_x": 54, "max_y": 54,
                      "width": 8, "height": 8 },
          "center": { "x": 50, "y": 50 },
          "diameter": 8
        }
      ],
      "issues": [
        {
          "code":         "OPERATION_TOO_CLOSE_TO_EDGE",
          "message":      "Operation op_1 is 3.50 mm from the part edge (minimum: 8.0 mm)",
          "severity":     "error",
          "operation_id": "op_1"
        }
      ],
      "valid": false
    }
  ]
}

Predefinições CNC

Guarde predefinições ValidationConfig com nome para validações futuras. São privadas da sua conta.

GET /api/cnc-configs
Authorization: Bearer <your-api-token>

→ 200 OK
{
  "configs": [
    {
      "id":         "d4f2a1b3-...",
      "name":       "Standard Router",
      "config":     { ... },
      "created_at": "2026-04-05T10:00:00Z",
      "updated_at": "2026-04-05T10:00:00Z"
    }
  ]
}

POST /api/cnc-configs
Authorization: Bearer <your-api-token>
Content-Type: application/json

{
  "name": "Standard Router",
  "config": {
    "part_min_width":     50,
    "part_min_height":    50,
    "part_max_width":     2800,
    "part_max_height":    2070,
    "drill_min_diameter": 2,
    "drill_max_diameter": 35,
    "min_edge_offset":    8,
    "min_op_spacing":     8,
    "groove_aspect_ratio": 3,
    "unit": "mm"
  }
}

→ 201 Created
{
  "id":         "d4f2a1b3-...",
  "name":       "Standard Router",
  "config":     { ... },
  "created_at": "2026-04-05T10:00:00Z",
  "updated_at": "2026-04-05T10:00:00Z"
}

Respostas de erro

Todos os endpoints devolvem erros no mesmo invólucro JSON:

{ "message": "A part (800×600) does not fit any stock plate" }

• 400 — limite de peças excedido: a soma de quantity supera o limite por pedido do plano. Também indica CSV inválido ou campo multipart ausente.
• 401 — token Bearer ausente, expirado ou revogado.
• 422 — uma peça não cabe em nenhum painel ou faltam painéis. A otimização é completa ou falha; nunca devolve disposição parcial. A mensagem identifica peça ou restrição. PTX também devolve 422 se a disposição não puder ser serrada.
• 429 — limite diário atingido. Reinicia à meia-noite UTC.
• 500 — erro interno do servidor, como falha no envio do ficheiro.