Saltar para o conteúdo
CargoDuo logoCargoDuo
Preços
Entrar

Por enquanto, esta documentação está disponível só em inglês.

Pack a project

Packs the project's vehicles and items exactly like POST /v1/pack: same price, credit reservation, limits, Idempotency-Key, ?wait= and job.

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

When the job succeeds its plan is saved into the project, which then opens in the app with that plan. If the project changed while the job ran, the plan stays on the job only (warning project_not_saved). Result ids are the project's: vehicle_id is the slot id (pv_…), item_id the item id (item_…).

Autenticação

Chave de API Bearer com a permissãopack:writeresources:writeSaber mais

Parâmetros de caminho

NomeTipoObrigatórioDescrição
idstringobrigatório
string
Sim

Project id (prj_…).

Parâmetros de consulta

NomeTipoObrigatórioDescrição
waitinteger
integer
Não

Seconds to hold the response for the job to finish. Finished in time: 200 with the result inlined. Otherwise: 202.

Predefinição 00–60

Parâmetros de cabeçalho

NomeTipoObrigatórioDescrição
Idempotency-Keystring
string
Não

Any unique string, such as a UUID or your order id. The same key within 24 h returns the original job instead of creating and charging a new one.

≤ 128 chars

Parâmetros do corpo

application/json
NomeTipoObrigatórioDescrição
referencestring
string
Não

Your reference, echoed on the job. Defaults to the project name.

≤ 128 chars
optionsProjectPackOptions
ProjectPackOptions
Não

Run options. Every field is optional.

Exemplo de pedido

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

Exemplo de resposta

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

Respostas

  • 200OKJob finished within ?wait, result inlined. Also an idempotent replay of a finished job.
    NomeTipoObrigatórioDescrição
    idstringobrigatório
    string
    Sim

    Job id (job_…).

    objectstringobrigatório
    string
    Sim

    Always job.

    job
    statusstringobrigatório
    string
    Sim

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Não

    Your reference from the request.

    sourcestring
    string
    Não

    Where the job was created.

    apiplayground
    project_idstring
    string
    Não

    The project (prj_…) a POST /v1/projects/{id}/pack job saves its plan into. Absent on other jobs.

    created_atstringobrigatório
    string
    Sim

    RFC 3339 timestamp.

    started_atstring | null
    string | null
    Não

    When computing started (RFC 3339) or null.

    finished_atstring | null
    string | null
    Não

    When the job ended (RFC 3339) or null.

    progressJobProgress
    JobProgress
    Não

    Live progress while queued/running.

    summaryJobSummary
    JobSummary
    Não

    Counts and timings.

    costJobCost
    JobCost
    Não

    Credits charged (final once the job ended) and the reservation held while it ran.

    errorJobError | null
    JobError | null
    Não

    Why the job failed or was canceled; null otherwise.

    warningsWarning[]
    Warning[]
    Não

    Non-blocking remarks about the request (also repeated in the result).

    result_urlstring
    string
    Não

    GET this URL for the full result once status is succeeded.

    pdf_urlstring
    string
    Não

    A browser link that renders the load plan as a PDF (3D views + loading steps). Valid until expires_at. Empty after expiry.

    expires_atstring
    string
    Não

    When the request/result bodies and the PDF link are deleted (RFC 3339). Job metadata and charges are kept.

    resultResult
    Result
    Não

    The full result, inlined only when requested (?include=result) or when POST /v1/pack?wait= finished in time.

  • 202AcceptedJob accepted (queued or running).
    NomeTipoObrigatórioDescrição
    idstringobrigatório
    string
    Sim

    Job id (job_…).

    objectstringobrigatório
    string
    Sim

    Always job.

    job
    statusstringobrigatório
    string
    Sim

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Não

    Your reference from the request.

    sourcestring
    string
    Não

    Where the job was created.

    apiplayground
    project_idstring
    string
    Não

    The project (prj_…) a POST /v1/projects/{id}/pack job saves its plan into. Absent on other jobs.

    created_atstringobrigatório
    string
    Sim

    RFC 3339 timestamp.

    started_atstring | null
    string | null
    Não

    When computing started (RFC 3339) or null.

    finished_atstring | null
    string | null
    Não

    When the job ended (RFC 3339) or null.

    progressJobProgress
    JobProgress
    Não

    Live progress while queued/running.

    summaryJobSummary
    JobSummary
    Não

    Counts and timings.

    costJobCost
    JobCost
    Não

    Credits charged (final once the job ended) and the reservation held while it ran.

    errorJobError | null
    JobError | null
    Não

    Why the job failed or was canceled; null otherwise.

    warningsWarning[]
    Warning[]
    Não

    Non-blocking remarks about the request (also repeated in the result).

    result_urlstring
    string
    Não

    GET this URL for the full result once status is succeeded.

    pdf_urlstring
    string
    Não

    A browser link that renders the load plan as a PDF (3D views + loading steps). Valid until expires_at. Empty after expiry.

    expires_atstring
    string
    Não

    When the request/result bodies and the PDF link are deleted (RFC 3339). Job metadata and charges are kept.

    resultResult
    Result
    Não

    The full result, inlined only when requested (?include=result) or when POST /v1/pack?wait= finished in time.

  • 400Bad requestinvalid_jsonidempotency_key_invalid
    • invalid_jsonThe body is not valid JSON or a field has the wrong type.
    • idempotency_key_invalidThe Idempotency-Key header is longer than 128 characters.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedMissing, malformed or unknown API key.
    • key_revokedThe key was revoked.
    • key_expiredThe key passed its expiry date.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 402Payment requiredinsufficient_credits
    • insufficient_creditsAvailable credits do not cover the smallest possible run of this job.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_not_allowedThe calling IP is not on the key's allowlist.
    • subscription_inactiveThe organization has no active subscription that includes the API.
    • account_inactiveThe organization is suspended, or has no owner whose account is active.
    • scope_missingThe key lacks a scope this endpoint needs.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 404Not foundproject_not_found
    • project_not_foundNo project with this id in your organization.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 409Conflictproject_busy
    • project_busyThe project is being packed right now (in the app or by another job).
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 413Payload too largepayload_too_large
    • payload_too_largeThe request body exceeds 10 MB.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 422Unprocessable entityvalidation_failed
    • validation_failedThe request is well-formed JSON but describes an invalid job. details[] lists every problem.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 429Too many requeststoo_many_jobsrate_limited
    • too_many_jobsThe organization already has the maximum number of queued + running jobs.
    • rate_limitedToo many requests in the current minute, hour or day (per key or per organization), or more than 60 failed authentications per minute from your IP address.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 500Internal server errorinternal_error
    • internal_errorSomething failed on our side.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 503Service unavailableapi_disabled
    • api_disabledThe API is temporarily disabled (maintenance) or switched off for the organization.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro