Документація API

Автентифікація — довготривалі токени API

Handifyit використовує Довготривалі токени API для автоматизованих або серверних запитів. Вони діють, доки ви їх не відкличете. Щоб отримати токен, виконайте три кроки нижче.

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...",  ← збережіть це!
  "name": "My Production App"
}

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

{ ... тіло запиту ... }

Спільне тіло запиту

Усі шість кінцевих точок оптимізації приймають однакове тіло JSON. Обов’язкові лише materials, stock_plates, parts та optimize_type; решта має значення за замовчуванням.

Повний приклад запиту

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

Запускає оптимізатор і повертає повну схему у JSON. Файли не створюються. Використовуйте цю кінцеву точку для обробки або відображення результатів у власному застосунку.

Структура відповіді

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

Оптимізує та формує один багатосторінковий PDF, по сторінці на плиту. Файл завантажується у хмарне сховище; повертається підписане посилання для завантаження.

Запит

Таке саме тіло JSON, як у /api/optimize (див. вище).

Відповідь

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

Відповідь містить один файл PDF з усіма плитами.

Оптимізує та створює файл DXF для кожної плити. Формат сумісний із більшістю систем CAD/CAM і контролерів ЧПК (AutoCAD, Fusion 360, Mach3 тощо). Повертає окремі посилання на завантажені файли.

Запит

Таке саме тіло JSON, як у /api/optimize (див. вище).

Відповідь

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

Один файл на плиту. Назва містить індекс плити й ідентифікатор запуску: plate-1-25318.dxf — плита 1 запуску 25318.

Оптимізує та створює один CSV з усіма деталями всіх матеріалів і плит. Рядки містять положення, розміри деталі та плити, назву й код матеріалу для таблиць, ERP або власних постпроцесорів. Файл зберігається у хмарі; повертається посилання.

Запит

Таке саме тіло JSON, як у /api/optimize (див. вище).

Стовпці CSV

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

Відповідь

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

Один CSV з усіма різами всіх матеріалів і плит.

Оптимізує та створює SVG для кожної плити. Масштабована векторна графіка підходить для перегляду у браузері та імпорту в Inkscape, Illustrator або Figma. Повертає окремі посилання на завантажені файли.

Запит

Таке саме тіло JSON, як у /api/optimize (див. вище).

Відповідь

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

Оптимізує та створює файл PTX (Pattern Exchange) для кожної групи матеріалу. Це формат обміну для пилок HOLZMA / HOMAG, сумісний із HolzLink, CADmatic 4/5 та HOMAG intelliDivide. Файл містить завдання матеріалу, схеми й послідовності різів. Повертає посилання на файли у хмарі.

Запит

Таке саме тіло JSON, як у /api/optimize (див. вище). Значення optimize_type: "saw" дає гільйотинні схеми для виконання на форматно-розкрійному верстаті.

Відповідь

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

Завантажте DXF як multipart/form-data. Відповідь — повний ValidationReport, з одним PartResult на виявлену деталь, її операціями й порушеннями.

Поля запиту (multipart)

Поля ValidationConfig

Приклад запиту (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"}'

Приклад відповіді

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

Збережені конфігурації ЧПК

Зберігайте іменовані конфігурації ValidationConfig для повторних перевірок. Вони доступні лише вашому обліковому запису.

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

Відповіді з помилками

Усі кінцеві точки повертають помилки в однаковій оболонці JSON:

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

• 400 — перевищено кількість деталей: сума quantity більша за обмеження тарифу на запит. Також повідомляє про некоректний CSV або відсутнє поле multipart.
• 401 — токен Bearer відсутній, прострочений або відкликаний.
• 422 — деталь не вміщується в жодну плиту або плит недостатньо. Оптимізація виконується повністю або завершується помилкою; часткової схеми немає. Повідомлення називає деталь або обмеження. PTX також повертає 422, якщо схема непридатна для пилки.
• 429 — досягнуто добового ліміту запитів. Скидання опівночі UTC.
• 500 — внутрішня помилка сервера, наприклад збій завантаження файлу.