API belgeleri

Kimlik doğrulama — uzun ömürlü API belirteçleri

Handifyit, otomatik veya sunucu tarafındaki çağrılar için Uzun ömürlü API belirteçleri kullanır. Siz açıkça iptal edene kadar geçerlidirler. Bir belirteç almak için aşağıdaki üç adımı izleyin.

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...",  ← bu değeri kaydedin!
  "name": "My Production App"
}

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

{ ... istek gövdesi ... }

Ortak istek gövdesi

Altı optimizasyon uç noktası aynı JSON gövdesini kabul eder. Yalnızca materials, stock_plates, parts ve optimize_type zorunludur; diğer alanların varsayılanları vardır.

Tam istek örneği

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

Optimizasyonu çalıştırır ve tam yerleşimi JSON olarak döndürür. Dosya oluşturmaz; kendi uygulamanızda sonuçları işlemek veya göstermek için kullanın.

Yanıt yapısı

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

Optimize edip levha başına bir sayfalı tek PDF oluşturur. Dosya buluta yüklenir ve imzalı indirme URL’si döndürülür.

İstek

/api/optimize ile aynı JSON gövdesi (yukarıya bakın).

Yanıt

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

Yanıt, tüm levhaları içeren tek PDF dosyası içerir.

Optimize edip levha başına DXF oluşturur. Çoğu CAD/CAM yazılımı ve CNC denetleyicisiyle uyumludur (AutoCAD, Fusion 360, Mach3 vb.). Saklanan her dosya için ayrı URL döndürür.

İstek

/api/optimize ile aynı JSON gövdesi (yukarıya bakın).

Yanıt

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

Levha başına bir dosya. Ad, levha indeksini ve çalıştırma kimliğini içerir: plate-1-25318.dxf, 25318 çalıştırmasının 1. levhasıdır.

Optimize edip tüm malzeme ve levhalardaki parçalar için tek CSV oluşturur. Satırlar konum, parça ve levha ölçüleri, malzeme adı ve kodunu içerir; tablolar, ERP ve özel son işlemciler için uygundur. Dosya buluta yüklenir ve URL’si döner.

İstek

/api/optimize ile aynı JSON gövdesi (yukarıya bakın).

CSV sütunları

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

Yanıt

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

Tüm malzeme ve levhaların kesimlerini içeren tek CSV.

Optimize edip levha başına SVG oluşturur. Ölçeklenebilir vektörler web önizlemeleri ve Inkscape, Illustrator veya Figma’ya aktarım için uygundur. Saklanan dosyaların ayrı URL’lerini döndürür.

İstek

/api/optimize ile aynı JSON gövdesi (yukarıya bakın).

Yanıt

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

Optimize edip malzeme grubu başına PTX (Pattern Exchange) oluşturur. HOLZMA / HOMAG testereleri için bu aktarım biçimini HolzLink, CADmatic 4/5 ve HOMAG intelliDivide kabul eder. Dosya, malzemenin işini, kesim desenlerini ve sıralarını içerir. Bulut dosyalarının URL’lerini döndürür.

İstek

/api/optimize ile aynı JSON gövdesi (yukarıya bakın). optimize_type: "saw", panel testerelerine uygun giyotin yerleşimleri üretir.

Yanıt

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

DXF’yi multipart/form-data olarak yükleyin. Yanıt tam ValidationReport içerir: her parça için işlemler ve ihlallerle bir PartResult.

İstek alanları (multipart)

ValidationConfig alanları

İstek örneği (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"}'

Yanıt örneği

{
  "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 yapılandırma ön ayarları

Sonraki doğrulamalar için adlandırılmış ValidationConfig ön ayarlarını kaydedin. Yalnızca hesabınıza özeldirler.

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

Hata yanıtları

Tüm uç noktalar hataları aynı JSON zarfında döndürür:

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

• 400 — parça sınırı aşıldı: quantity toplamı planın istek sınırını aşar. Bozuk CSV veya eksik multipart alanı da burada bildirilir.
• 401 — Bearer belirteci eksik, süresi dolmuş veya iptal edilmiş.
• 422 — parça hiçbir levhaya sığmıyor veya levhalar yetmiyor. Optimizasyon tamamen başarılı olur veya başarısızdır; kısmi yerleşim dönmez. Mesaj parça ya da kısıtı belirtir. PTX, testereyle kesilemeyen yerleşimde de 422 döndürür.
• 429 — günlük sınır doldu. UTC gece yarısında sıfırlanır.
• 500 — dosya yükleme hatası gibi dahili sunucu hatası.