Documentazione API

Autenticazione — token API di lunga durata

Handifyit usa Token API di lunga durata per chiamate automatiche o lato server. Restano validi fino alla revoca esplicita. Per ottenerne uno, segui questi tre passaggi.

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...",  ← salva questo valore!
  "name": "My Production App"
}

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

{ ... corpo della richiesta ... }

Corpo comune della richiesta

Tutti i sei endpoint di ottimizzazione accettano lo stesso corpo JSON. Sono obbligatori solo materials, stock_plates, parts e optimize_type; gli altri campi hanno valori predefiniti.

Esempio completo di richiesta

{
  "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
}

Esegue l’ottimizzatore e restituisce l’intera disposizione in JSON. Non crea file; usa questo endpoint per elaborare o visualizzare risultati nella tua applicazione.

Struttura della risposta

{
  "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
      }
    }
  ]
}

Ottimizza e genera un PDF multipagina, una pagina per pannello. Il file viene salvato nel cloud e si restituisce un URL di download firmato.

Richiesta

Stesso corpo JSON di /api/optimize (vedi sopra).

Risposta

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

La risposta contiene un unico PDF con tutti i pannelli.

Ottimizza e genera un DXF per pannello, compatibile con la maggior parte dei software CAD/CAM e controlli CNC (AutoCAD, Fusion 360, Mach3, ecc.). Restituisce URL individuali dei file salvati.

Richiesta

Stesso corpo JSON di /api/optimize (vedi sopra).

Risposta

{
  "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"
    }
  ]
}

Un file per pannello. Il nome contiene indice e identificativo dell’esecuzione: plate-1-25318.dxf indica il pannello 1 dell’esecuzione 25318.

Ottimizza e genera un CSV con tutti i pezzi di tutti i materiali e pannelli. Ogni riga contiene posizione, misure del pezzo e pannello, nome e codice materiale, per fogli di calcolo, ERP o postprocessori. Il file viene salvato nel cloud e si restituisce il suo URL.

Richiesta

Stesso corpo JSON di /api/optimize (vedi sopra).

Colonne CSV

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

Risposta

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

Un unico CSV con tutti i tagli di tutti i materiali e pannelli.

Ottimizza e genera un SVG per pannello. La grafica vettoriale scalabile è adatta ad anteprime web e importazione in Inkscape, Illustrator o Figma. Restituisce URL individuali dei file salvati.

Richiesta

Stesso corpo JSON di /api/optimize (vedi sopra).

Risposta

{
  "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"
    }
  ]
}

Ottimizza e genera un PTX (Pattern Exchange) per gruppo di materiale. Il formato per sezionatrici HOLZMA / HOMAG è accettato da HolzLink, CADmatic 4/5 e HOMAG intelliDivide. Ogni file contiene il lavoro del materiale, schemi e sequenze di taglio. Restituisce gli URL dei file nel cloud.

Richiesta

Stesso corpo JSON di /api/optimize (vedi sopra). optimize_type: "saw" genera schemi a ghigliottina adatti alle sezionatrici.

Risposta

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

Carica DXF come multipart/form-data. La risposta è un ValidationReport completo: un PartResult per pezzo con operazioni e violazioni.

Campi della richiesta (multipart)

Campi di ValidationConfig

Esempio di richiesta (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"}'

Esempio di risposta

{
  "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
    }
  ]
}

Preimpostazioni CNC

Salva preimpostazioni ValidationConfig con nome per verifiche successive. Sono private del tuo account.

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"
}

Risposte di errore

Tutti gli endpoint restituiscono errori nello stesso involucro JSON:

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

• 400 — limite pezzi superato: la somma di quantity supera il limite per richiesta del piano. Segnala anche CSV non valido o campo multipart mancante.
• 401 — token Bearer mancante, scaduto o revocato.
• 422 — un pezzo non entra in alcun pannello o i pannelli non bastano. L’ottimizzazione riesce interamente o fallisce; non restituisce layout parziali. Il messaggio indica pezzo o vincolo. PTX restituisce 422 anche se il piano non è segabile.
• 429 — limite giornaliero raggiunto. Azzeramento a mezzanotte UTC.
• 500 — errore interno del server, per esempio caricamento file fallito.