API-Dokumentation

Authentifizierung — langlebige API-Token

Handifyit verwendet Langlebige API-Token für automatisierte oder serverseitige Aufrufe. Sie bleiben gültig, bis Sie sie ausdrücklich widerrufen. Die folgenden drei Schritte zeigen, wie Sie eines erhalten.

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...",  ← diesen Wert speichern!
  "name": "My Production App"
}

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

{ ... Anfrageinhalt ... }

Gemeinsamer Anfrageinhalt

Alle sechs Optimierungsendpunkte akzeptieren denselben JSON-Inhalt. Nur materials, stock_plates, parts und optimize_type sind erforderlich; die übrigen Felder haben Standardwerte.

Vollständiges Anfragebeispiel

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

Führt die Optimierung aus und liefert die vollständige Anordnung als JSON. Erstellt keine Dateien. Verwenden Sie diesen Endpunkt zur Verarbeitung oder Darstellung in Ihrer Anwendung.

Aufbau der Antwort

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

Optimiert und erstellt ein mehrseitiges PDF mit einer Seite pro Platte. Die Datei wird im Cloud-Speicher abgelegt; eine signierte Download-URL wird zurückgegeben.

Anfrage

Derselbe JSON-Inhalt wie bei /api/optimize (siehe oben).

Antwort

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

Die Antwort enthält eine PDF-Datei mit allen Platten.

Optimiert und erstellt eine DXF-Datei pro Platte. Kompatibel mit den meisten CAD/CAM-Systemen und CNC-Steuerungen (AutoCAD, Fusion 360, Mach3 usw.). Liefert einzelne URLs für die gespeicherten Dateien.

Anfrage

Derselbe JSON-Inhalt wie bei /api/optimize (siehe oben).

Antwort

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

Eine Datei pro Platte. Der Name enthält Plattenindex und Laufkennung: plate-1-25318.dxf bezeichnet Platte 1 aus Lauf 25318.

Optimiert und erstellt eine CSV-Datei für alle Teile, Materialien und Platten. Jede Zeile enthält Position, Teile- und Plattenmaße sowie Materialname und -code für Tabellen, ERP oder eigene Nachbearbeitung. Die Datei wird in der Cloud gespeichert und ihre URL zurückgegeben.

Anfrage

Derselbe JSON-Inhalt wie bei /api/optimize (siehe oben).

CSV-Spalten

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

Antwort

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

Eine CSV-Datei mit allen Schnitten aller Materialien und Platten.

Optimiert und erstellt eine SVG-Datei pro Platte. Skalierbare Vektorgrafiken eignen sich für Webvorschauen und Inkscape, Illustrator oder Figma. Liefert einzelne URLs für die gespeicherten Dateien.

Anfrage

Derselbe JSON-Inhalt wie bei /api/optimize (siehe oben).

Antwort

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

Optimiert und erstellt eine PTX-Datei (Pattern Exchange) pro Materialgruppe. Dieses Übertragungsformat für HOLZMA-/HOMAG-Plattensägen wird von HolzLink, CADmatic 4/5 und HOMAG intelliDivide unterstützt. Jede Datei enthält einen Materialauftrag mit Schnittmustern und Sägefolgen. Liefert URLs der Cloud-Dateien.

Anfrage

Derselbe JSON-Inhalt wie bei /api/optimize (siehe oben). optimize_type: "saw" erzeugt Guillotine-Anordnungen für Plattensägen.

Antwort

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

Laden Sie DXF als multipart/form-data hoch. Die Antwort ist ein vollständiger ValidationReport: ein PartResult pro Teil mit Bearbeitungen und Verstößen.

Anfragefelder (multipart)

Felder von ValidationConfig

Anfragebeispiel (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"}'

Antwortbeispiel

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

CNC-Konfigurationsvorlagen

Speichern Sie benannte ValidationConfig-Vorlagen für spätere Prüfungen. Sie sind nur für Ihr Konto zugänglich.

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

Fehlerantworten

Alle Endpunkte geben Fehler in derselben JSON-Struktur zurück:

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

• 400 — Teilelimit überschritten: Die Summe von quantity übersteigt das Tariflimit pro Anfrage. Meldet auch fehlerhafte CSV-Dateien oder fehlende Multipart-Felder.
• 401 — Bearer-Token fehlt, ist abgelaufen oder wurde widerrufen.
• 422 — ein Teil passt auf keine Platte oder die Platten reichen nicht. Die Optimierung gelingt vollständig oder scheitert; es gibt keine Teilanordnung. Die Meldung nennt das Teil oder die Grenze. PTX liefert ebenfalls 422, wenn die Anordnung nicht sägbar ist.
• 429 — Tageslimit erreicht. Zurücksetzung um Mitternacht UTC.
• 500 — interner Serverfehler, etwa fehlgeschlagener Datei-Upload.