跳到主要内容
开发者文档API 参考项目

更新项目

重命名项目、修改其选项,或替换其车辆或物品(连同分组)。

PATCHhttps://runner.cargoduo.com/v1/projects/{id}

替换车辆或物品会清除已保存的方案;应用中已打开的会话会重新加载。免费,不扣积分。

认证

Bearer API 密钥 · 所需权限范围resources:write了解更多

路径参数

名称类型必填说明
idstring必填
string
是

项目 ID(prj_…)。

请求体参数

application/json
名称类型必填说明
namestring
string
否
≤ 255 chars
vehiclesProjectVehicle[]
ProjectVehicle[]
否

车辆条目。

itemsItem[]
Item[]
否

货物(最多 500 个物品定义)。

groupsGroup[]
Group[]
否

分组及其装载顺序。

optionsProjectOptions
ProjectOptions
否

项目保存的装载选项。

请求示例

curl -X PATCH "https://runner.cargoduo.com/v1/projects/prj_3051" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicles": [
      {
        "vehicle_id": "veh_118",
        "quantity": 2
      }
    ]
  }'

响应示例

200 OK · Project
{
  "id": "prj_3051",
  "object": "project",
  "name": "Order 1042",
  "status": "draft",
  "item_count": 58,
  "vehicle_count": 2,
  "app_url": "https://app.cargoduo.com/projects/3051",
  "created_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "updated_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "created_at": "2026-10-19T09:10:03Z",
  "updated_at": "2026-10-19T09:22:03Z",
  "options": {
    "packing_mode": "auto",
    "group_routing": "none",
    "allow_overweight": false
  },
  "vehicles": [
    {
      "id": "pv_5121",
      "vehicle_id": "veh_118",
      "name": "Mega trailer 13.6 m",
      "type": "trailer",
      "quantity": 2,
      "length": 1360,
      "width": 248,
      "height": 300,
      "max_weight": 24000
    }
  ],
  "items": [
    {
      "id": "item_88410",
      "label": "Euro pallet",
      "shape": "box",
      "length": 120,
      "width": 80,
      "height": 140,
      "weight": 450,
      "quantity": 18,
      "stackable": false,
      "rotation": "all",
      "color": "#3b82f6"
    },
    {
      "id": "item_88411",
      "label": "Carton A",
      "shape": "box",
      "length": 60,
      "width": 40,
      "height": 40,
      "weight": 12,
      "quantity": 40,
      "stackable": true,
      "rotation": "upright",
      "color": "#f59e0b"
    }
  ],
  "groups": [],
  "plan": null
}

响应

  • 200OK修改后的项目。
    名称类型必填说明
    idstring
    string
    否

    项目 ID(prj_…)。

    objectstring
    string
    否
    project
    namestring
    string
    否
    statusstring
    string
    否

    draft = 从未计算过或输入已被替换;calculated = 有当前方案;stale = 方案生成后设置有变更。

    draftcalculatedstaleerror
    item_countinteger
    integer
    否

    物品件数(所有数量之和)。

    vehicle_countinteger
    integer
    否

    车辆数(所有数量之和)。

    app_urlstring
    string
    否

    在应用的 3D 编辑器中打开该项目。

    created_byUserRef | null
    UserRef | null
    否

    创建者(通过 API 调用时为创建该密钥的成员)。未知时为 null。

    updated_byUserRef | null
    UserRef | null
    否

    最后修改它的成员。

    created_atstring
    string
    否

    RFC 3339 格式。

    updated_atstring
    string
    否

    RFC 3339 格式。

    optionsProjectOptions
    ProjectOptions
    否

    项目保存的装载选项。

    vehiclesProjectVehicle[]
    ProjectVehicle[]
    否
    itemsItem[]
    Item[]
    否

    货物,结构与 /v1/pack 的 Item 相同;ID 形如 item_…。

    groupsGroup[]
    Group[]
    否
    planProjectPlan | null
    ProjectPlan | null
    否

    当前方案;项目没有方案时为 null。

  • 400Bad requestinvalid_json
    • invalid_json请求体不是有效的 JSON,或某个字段类型错误。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedAPI 密钥缺失、格式错误或无法识别。
    • key_revoked密钥已被撤销。
    • key_expired密钥已过期。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 403Forbiddenplan_limit_reachedip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • plan_limit_reached组织的套餐已达到项目或货物数量上限。
    • ip_not_allowed调用方 IP 不在该密钥的 IP 白名单中。
    • subscription_inactive组织没有包含 API 的有效订阅。
    • account_inactive组织已被暂停使用,或其所有者的账户均未处于有效状态。
    • scope_missing密钥缺少此接口所需的权限范围。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 404Not foundproject_not_found
    • project_not_found您的组织中没有此 ID 的项目。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 413Payload too largepayload_too_large
    • payload_too_large请求体超过 10 MB。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 422Unprocessable entityvalidation_failed
    • validation_failed请求是格式正确的 JSON,但描述的任务无效。details[] 列出了所有问题。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 429Too many requestsrate_limited
    • rate_limited当前分钟、小时或天内的请求过多(按密钥或按组织计),或您的 IP 地址每分钟认证失败超过 60 次。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 500Internal server errorinternal_error
    • internal_error服务端发生内部错误。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 503Service unavailableapi_disabled
    • api_disabledAPI 暂时停用(维护中),或已对该组织关闭。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码