Documentation API

Authentification — jetons API à longue durée de vie

Handifyit utilise des Jetons API à longue durée de vie pour les appels automatisés ou côté serveur. Ils restent valides jusqu’à leur révocation explicite. Suivez les trois étapes ci-dessous pour en obtenir un.

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...",  ← conservez cette valeur !
  "name": "My Production App"
}

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

{ ... corps de requête ... }

Corps de requête commun

Les six points de terminaison d’optimisation acceptent le même corps JSON. Seuls materials, stock_plates, parts et optimize_type sont obligatoires ; les autres champs ont une valeur par défaut.

Exemple de requête complet

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

Exécute l’optimiseur et renvoie le calepinage complet en JSON. Aucun fichier n’est créé ; utilisez ce point pour traiter ou afficher les résultats dans votre application.

Structure de la réponse

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

Optimise et rassemble les calepinages dans un PDF multipage, une page par panneau. Le fichier est envoyé au stockage cloud et une URL de téléchargement signée est renvoyée.

Requête

Même corps JSON que /api/optimize (voir ci-dessus).

Réponse

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

La réponse contient un seul fichier PDF regroupant tous les panneaux.

Optimise et crée un DXF par panneau, compatible avec la plupart des logiciels CAO/FAO et contrôleurs CNC (AutoCAD, Fusion 360, Mach3, etc.). Renvoie une URL par fichier envoyé au stockage.

Requête

Même corps JSON que /api/optimize (voir ci-dessus).

Réponse

{
  "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 fichier par panneau. Son nom encode l’indice du panneau et l’exécution : plate-1-25318.dxf désigne le panneau 1 de l’exécution 25318.

Optimise et crée un CSV pour toutes les pièces de tous les matériaux et panneaux. Chaque ligne contient position, dimensions de la pièce et du panneau, nom et code du matériau, pour tableurs, ERP ou postprocesseurs. Le fichier est stocké dans le cloud et son URL est renvoyée.

Requête

Même corps JSON que /api/optimize (voir ci-dessus).

Colonnes CSV

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

Réponse

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

Un seul CSV avec toutes les coupes de tous les matériaux et panneaux.

Optimise et crée un SVG par panneau. Ces graphiques vectoriels conviennent aux aperçus web et à l’import dans Inkscape, Illustrator ou Figma. Renvoie une URL par fichier envoyé au stockage.

Requête

Même corps JSON que /api/optimize (voir ci-dessus).

Réponse

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

Optimise et crée un PTX (Pattern Exchange) par groupe de matériau. Ce format de transfert pour scies HOLZMA / HOMAG est accepté par HolzLink, CADmatic 4/5 et HOMAG intelliDivide. Chaque fichier contient le travail du matériau, ses schémas et séquences de sciage. Renvoie les URL des fichiers stockés dans le cloud.

Requête

Même corps JSON que /api/optimize (voir ci-dessus). Le réglage optimize_type: "saw" produit des calepinages guillotine adaptés aux scies à panneaux.

Réponse

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

Envoyez un DXF en multipart/form-data. La réponse est un ValidationReport complet : un PartResult par pièce détectée, avec opérations et violations.

Champs de requête (multipart)

Champs de ValidationConfig

Exemple de requête (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"}'

Exemple de réponse

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

Préréglages de configuration CNC

Enregistrez des préréglages ValidationConfig nommés pour les validations suivantes. Ils restent privés à votre compte.

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

Réponses d’erreur

Tous les points renvoient leurs erreurs dans la même enveloppe JSON :

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

• 400 — limite de pièces dépassée : la somme des quantity dépasse le plafond par requête de l’offre. Signale aussi un CSV mal formé ou un champ multipart absent.
• 401 — jeton Bearer absent, expiré ou révoqué.
• 422 — une pièce ne tient sur aucun panneau ou les panneaux sont insuffisants. L’optimisation réussit entièrement ou échoue ; aucun calepinage partiel n’est renvoyé. Le message nomme la pièce ou la contrainte. L’export PTX renvoie aussi 422 si le plan est irréalisable à la scie.
• 429 — limite quotidienne atteinte. Remise à zéro à minuit UTC.
• 500 — erreur interne du serveur, par exemple échec d’envoi d’un fichier.