Kubova REST API

모든 요청의 Authorization 헤더에 API 키가 필요합니다:

Authorization: Bearer kbv_abc123...

Pro 요금제에 가입한 후 대시보드에서 키를 생성하세요.

적재 요청을 보내기 전에 /me 엔드포인트를 사용하여 키가 유효한지 확인하세요:

curl https://kubova.com/api/v1/me \
  -H "Authorization: Bearer kbv_..."

화물 정보와 컨테이너 정보를 담아 /api/v1/pack으로 POST 요청을 보내세요. 패커는 컨테이너별 배치 정보, 사용된 부피, 적재되지 못한 수량을 반환합니다.

curl -X POST https://kubova.com/api/v1/pack \
  -H "Authorization: Bearer kbv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cargos": [{
      "id": "sku-a",
      "name": "Box A",
      "shape": "box",
      "lengthCm": 50, "widthCm": 40, "heightCm": 30,
      "quantity": 20,
      "weightKg": 5,
      "color": "#e85d3a",
      "includeInLoading": true,
      "allowStacking": true,
      "allowRotation": true
    }],
    "container": {
      "id": "40hc",
      "name": "40HC",
      "innerLengthCm": 1203.0,
      "innerWidthCm": 235.2,
      "innerHeightCm": 269.7,
      "doorWidthCm": 233.5,
      "doorHeightCm": 258.5,
      "maxPayloadKg": 26330
    },
    "options": {
      "loadingDirection": "floor-to-top",
      "vnsTimeLimitMs": 5000
    }
  }'

성공 시 ok=true와 함께 result.containers 및 result.unplaced를 반환합니다. 오류 발생 시 ok=false와 오류 메시지 문자열을 반환합니다.

/pack과 동일한 바디 형태로 /api/v1/report에 POST 요청을 보내세요. format=json은 base64 PDF와 컨테이너별 3D PNG를 반환하며, format=binary는 직접 저장할 수 있는 단일 통합 PDF를 스트림으로 반환합니다.

# JSON response: base64 PDF + 3D PNG per container
curl -X POST https://kubova.com/api/v1/report \
  -H "Authorization: Bearer kbv_..." \
  -H "Content-Type: application/json" \
  -d '{ "cargos": [...], "container": {...}, "format": "json" }'

# Binary response: a single combined PDF
curl -X POST "https://kubova.com/api/v1/report?format=binary" \
  -H "Authorization: Bearer kbv_..." \
  -H "Content-Type: application/json" \
  -d '{ "cargos": [...], "container": {...} }' \
  --output kubova-report.pdf

키에 report 범위가 필요합니다. 새 키는 기본적으로 pack과 report 범위를 모두 포함하여 생성됩니다.

• 키당 기본 분당 60회 요청(요청 시 키별로 구성 가능).
• 적재 요청은 290초 후에 타임아웃됩니다. 이는 지금까지 확인된 모든 작업량을 감당할 수 있는 수준이며, 실제 사용자가 한계에 도달하기 시작하면 비동기 작업 패턴이 도입될 예정입니다.
• 각 키에는 범위 세트(pack, report)가 있습니다. /pack 엔드포인트는 pack 범위가 필요합니다.
• API 액세스는 Pro 요금제 이상에서 사용할 수 있습니다.