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

计算项目装载方案

对项目中的车辆和物品进行装载计算,与 POST /v1/pack 完全一致:相同的价格、积分预留、上限、Idempotency-Key、?wait= 和任务。

POSThttps://runner.cargoduo.com/v1/projects/{id}/pack

任务成功后,方案会保存到项目中,在应用中打开该项目即可看到此方案。如果任务运行期间项目被修改,方案只保留在任务上(警告 project_not_saved)。结果中的 ID 来自项目:vehicle_id 是车辆条目 ID(pv_…),item_id 是物品 ID(item_…)。

认证

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

路径参数

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

项目 ID(prj_…)。

查询参数

名称类型必填说明
waitinteger
integer
否

响应等待任务完成的最长秒数。在此时间内完成:返回 200,结果内联在响应中;否则返回 202。

默认值 00–60

请求头参数

名称类型必填说明
Idempotency-Keystring
string
否

任意唯一字符串,例如 UUID 或您的订单号。24 小时内使用相同的键会返回原任务,而不会创建新任务并再次扣费。

≤ 128 chars

请求体参数

application/json
名称类型必填说明
referencestring
string
否

您的参考编号,会原样返回在任务中。默认为项目名称。

≤ 128 chars
optionsProjectPackOptions
ProjectPackOptions
否

运行选项。所有字段均为可选。

请求示例

curl -X POST "https://runner.cargoduo.com/v1/projects/prj_3051/pack" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Idempotency-Key: order-1042-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042"
  }'

响应示例

202 Accepted · Job
{
  "id": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
  "object": "job",
  "status": "queued",
  "reference": "order-1042",
  "source": "api",
  "project_id": "prj_3051",
  "created_at": "2026-10-19T09:12:03Z",
  "started_at": null,
  "finished_at": null,
  "progress": {
    "stage": "queued",
    "vehicles_done": 0,
    "placed_items": 0
  },
  "summary": {
    "items_requested": 58,
    "items_placed": 0,
    "items_unplaced": 0,
    "vehicles_used": 0,
    "total_weight": 0,
    "volume_utilization": 0,
    "queue_ms": 0,
    "compute_ms": 0
  },
  "cost": {
    "credits": 0,
    "reserved_credits": 1.11,
    "rate_card_version": 1,
    "breakdown": {
      "base": 0,
      "vehicles": 0,
      "compute": 0,
      "large_load": 0
    }
  },
  "error": null,
  "warnings": [],
  "result_url": "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f/result",
  "pdf_url": "",
  "expires_at": "2026-11-02T09:12:03Z"
}

响应

  • 200OK任务在 ?wait 时间内完成,结果已内联。已结束任务的幂等重放也返回此状态。
    名称类型必填说明
    idstring必填
    string
    是

    任务 ID(job_…)。

    objectstring必填
    string
    是

    始终为 job。

    job
    statusstring必填
    string
    是

    queued → running → succeeded | failed | canceled。

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    否

    请求中提供的参考编号。

    sourcestring
    string
    否

    任务的创建来源。

    apiplayground
    project_idstring
    string
    否

    POST /v1/projects/{id}/pack 任务将方案保存到的项目(prj_…)。其他任务不含此字段。

    created_atstring必填
    string
    是

    RFC 3339 时间戳。

    started_atstring | null
    string | null
    否

    开始计算的时间(RFC 3339),或 null。

    finished_atstring | null
    string | null
    否

    任务结束时间(RFC 3339),或 null。

    progressJobProgress
    JobProgress
    否

    排队中/运行中的实时进度。

    summaryJobSummary
    JobSummary
    否

    计数和耗时。

    costJobCost
    JobCost
    否

    已扣积分(任务结束后为最终值)以及运行期间预留的积分。

    errorJobError | null
    JobError | null
    否

    任务失败或被取消的原因;否则为 null。

    warningsWarning[]
    Warning[]
    否

    关于请求的非阻断性提示(结果中也会重复列出)。

    result_urlstring
    string
    否

    status 为 succeeded 后,对此 URL 发起 GET 请求以获取完整结果。

    pdf_urlstring
    string
    否

    浏览器链接,打开后会将装载方案生成为 PDF(3D 视图 + 装载步骤)。在 expires_at 之前有效,过期后为空。

    expires_atstring
    string
    否

    请求体/结果体和 PDF 链接的删除时间(RFC 3339)。任务元数据和扣费记录会保留。

    resultResult
    Result
    否

    完整结果,仅在请求时(?include=result)或 POST /v1/pack?wait= 按时完成时内联返回。

  • 202Accepted任务已接受(排队中或运行中)。
    名称类型必填说明
    idstring必填
    string
    是

    任务 ID(job_…)。

    objectstring必填
    string
    是

    始终为 job。

    job
    statusstring必填
    string
    是

    queued → running → succeeded | failed | canceled。

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    否

    请求中提供的参考编号。

    sourcestring
    string
    否

    任务的创建来源。

    apiplayground
    project_idstring
    string
    否

    POST /v1/projects/{id}/pack 任务将方案保存到的项目(prj_…)。其他任务不含此字段。

    created_atstring必填
    string
    是

    RFC 3339 时间戳。

    started_atstring | null
    string | null
    否

    开始计算的时间(RFC 3339),或 null。

    finished_atstring | null
    string | null
    否

    任务结束时间(RFC 3339),或 null。

    progressJobProgress
    JobProgress
    否

    排队中/运行中的实时进度。

    summaryJobSummary
    JobSummary
    否

    计数和耗时。

    costJobCost
    JobCost
    否

    已扣积分(任务结束后为最终值)以及运行期间预留的积分。

    errorJobError | null
    JobError | null
    否

    任务失败或被取消的原因;否则为 null。

    warningsWarning[]
    Warning[]
    否

    关于请求的非阻断性提示(结果中也会重复列出)。

    result_urlstring
    string
    否

    status 为 succeeded 后,对此 URL 发起 GET 请求以获取完整结果。

    pdf_urlstring
    string
    否

    浏览器链接,打开后会将装载方案生成为 PDF(3D 视图 + 装载步骤)。在 expires_at 之前有效,过期后为空。

    expires_atstring
    string
    否

    请求体/结果体和 PDF 链接的删除时间(RFC 3339)。任务元数据和扣费记录会保留。

    resultResult
    Result
    否

    完整结果,仅在请求时(?include=result)或 POST /v1/pack?wait= 按时完成时内联返回。

  • 400Bad requestinvalid_jsonidempotency_key_invalid
    • invalid_json请求体不是有效的 JSON,或某个字段类型错误。
    • idempotency_key_invalidIdempotency-Key 请求头超过 128 个字符。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedAPI 密钥缺失、格式错误或无法识别。
    • key_revoked密钥已被撤销。
    • key_expired密钥已过期。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 402Payment requiredinsufficient_credits
    • insufficient_credits可用积分不足以支付该任务的最低可能费用。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_not_allowed调用方 IP 不在该密钥的 IP 白名单中。
    • subscription_inactive组织没有包含 API 的有效订阅。
    • account_inactive组织已被暂停使用,或其所有者的账户均未处于有效状态。
    • scope_missing密钥缺少此接口所需的权限范围。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 404Not foundproject_not_found
    • project_not_found您的组织中没有此 ID 的项目。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 409Conflictproject_busy
    • project_busy该项目正在进行装载计算(在应用中或由另一个任务执行)。
    名称类型必填说明
    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 requeststoo_many_jobsrate_limited
    • too_many_jobs组织的排队中 + 运行中任务数已达上限。
    • rate_limited当前分钟、小时或天内的请求过多(按密钥或按组织计),或您的 IP 地址每分钟认证失败超过 60 次。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 500Internal server errorinternal_error
    • internal_error服务端发生内部错误。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 503Service unavailableapi_disabled
    • api_disabledAPI 暂时停用(维护中),或已对该组织关闭。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码