Documentación de la API

Autenticación — tokens API de larga duración

Handifyit usa Tokens API de larga duración para llamadas automatizadas o desde servidores. Siguen siendo válidos hasta que los revoque. Obtenga uno siguiendo estos tres pasos.

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

{ ... cuerpo de la solicitud ... }

Cuerpo común de la solicitud

Los seis endpoints de optimización aceptan el mismo cuerpo JSON. Solo son obligatorios materials, stock_plates, parts y optimize_type; los demás campos tienen valores predeterminados.

Ejemplo completo de solicitud

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

Ejecuta el optimizador y devuelve la distribución completa en JSON. No crea archivos; utilice este endpoint para procesar o mostrar resultados en su aplicación.

Estructura de la respuesta

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

Optimiza y crea un PDF de varias páginas, una por tablero. Lo guarda en la nube y devuelve una URL de descarga firmada.

Solicitud

Mismo cuerpo JSON que /api/optimize (véase arriba).

Respuesta

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

La respuesta contiene un único PDF con todos los tableros.

Optimiza y crea un DXF por tablero, compatible con la mayoría de sistemas CAD/CAM y controles CNC (AutoCAD, Fusion 360, Mach3, etc.). Devuelve una URL por archivo almacenado.

Solicitud

Mismo cuerpo JSON que /api/optimize (véase arriba).

Respuesta

{
  "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 archivo por tablero. El nombre incluye el índice y la ejecución: plate-1-25318.dxf corresponde al tablero 1 de la ejecución 25318.

Optimiza y crea un CSV con todas las piezas de todos los materiales y tableros. Cada fila incluye posición, medidas de pieza y tablero, nombre y código del material para hojas de cálculo, ERP o posprocesadores. Lo guarda en la nube y devuelve su URL.

Solicitud

Mismo cuerpo JSON que /api/optimize (véase arriba).

Columnas CSV

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

Respuesta

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

Un único CSV con todos los cortes de todos los materiales y tableros.

Optimiza y crea un SVG por tablero. Estos gráficos vectoriales escalables sirven para vistas web e importación en Inkscape, Illustrator o Figma. Devuelve una URL por archivo almacenado.

Solicitud

Mismo cuerpo JSON que /api/optimize (véase arriba).

Respuesta

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

Optimiza y crea un PTX (Pattern Exchange) por grupo de material. Este formato de transferencia para sierras HOLZMA / HOMAG funciona con HolzLink, CADmatic 4/5 y HOMAG intelliDivide. Cada archivo contiene el trabajo del material, sus patrones y secuencias de corte. Devuelve las URL de los archivos en la nube.

Solicitud

Mismo cuerpo JSON que /api/optimize (véase arriba). optimize_type: "saw" genera distribuciones de guillotina adecuadas para sierras de paneles.

Respuesta

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

Suba un DXF como multipart/form-data. La respuesta es un ValidationReport completo: un PartResult por pieza con operaciones e infracciones.

Campos de solicitud (multipart)

Campos de ValidationConfig

Ejemplo de solicitud (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"}'

Ejemplo de respuesta

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

Preajustes de configuración CNC

Guarde preajustes ValidationConfig con nombre para próximas validaciones. Son privados de su cuenta.

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

Respuestas de error

Todos los endpoints devuelven errores en el mismo envoltorio JSON:

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

• 400 — límite de piezas superado: la suma de quantity excede el máximo por solicitud del plan. También indica CSV incorrecto o campo multipart ausente.
• 401 — token Bearer ausente, caducado o revocado.
• 422 — una pieza no cabe en ningún tablero o faltan tableros. La optimización es completa o falla; nunca devuelve distribución parcial. El mensaje identifica la pieza o restricción. PTX también devuelve 422 si no puede cortarse con sierra.
• 429 — límite diario alcanzado. Se reinicia a medianoche UTC.
• 500 — error interno del servidor, como fallo al subir un archivo.