Documentação para desenvolvedoresAPI referencePack

Create a packing job

Validates the request, reserves the worst-case price from your credits and queues a job.

POSThttps://runner.cargoduo.com/v1/pack

Answers 202 with the job; poll GET /v1/jobs/{id}, or pass ?wait= to hold the response until it ends. Validation failures (422) are free and create no job.

Autenticação

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

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 own reference (order number, shipment id…). Echoed back on the job.

≤ 128 chars

vehiclesVehicle[]obrigatório

Vehicle[]

Sim

Vehicle definitions. Each one may have quantity > 1. At least one.

idstring

string

Não

Your identifier, unique within the request. Results refer to it as vehicle_id. Defaults to vehicle_id.

≤ 128 chars

vehicle_idstring

string

Não

A vehicle id from GET /v1/vehicles: a preset or one of your organization's vehicles (veh_…). Supplies type, name, dimensions, payload and every other saved value.

typestring

string

Não

Vehicle type. Required unless vehicle_id is given. Only the types listed in GET /v1/limits (allowed_vehicle_types) are accepted.

trucktrailerflatbedcontainerpalletaircraftship

namestring

string

Não

Display name (defaults to the saved vehicle's name or the id).

≤ 255 chars

lengthnumber · cm

number · cm

Não

Internal cargo-space length, along x (from the front wall toward the door). Required unless vehicle_id is given.

widthnumber · cm

number · cm

Não

Internal cargo-space width, along z. Required unless vehicle_id is given.

heightnumber · cm

number · cm

Não

Internal cargo-space height, along y. Required unless vehicle_id is given.

max_weightnumber · kg

number · kg

Não

Maximum payload. Required unless vehicle_id is given.

quantityinteger

integer

Não

How many identical vehicles of this definition are available.

Predefinição 11–100

floor_load_capacitynumber · kg/m²

number · kg/m²

Não

Floor load capacity: 0 or more (0 = no limit).

aux_deckboolean

boolean

Não

The vehicle has a second deck (double-decker).

Predefinição false

aux_deck_heightnumber · cm

number · cm

Não

Second deck height above the floor. Required when aux_deck is true.

aux_deck_max_weightnumber · kg

number · kg

Não

Load limit of the second deck. Required when aux_deck is true.

blocked_areasRect[]

Rect[]

Não

Floor zones nothing may stand on (wheel arches, damage, reserved space). Each must lie on the vehicle floor.

≤ 32 items

axle_positionsAcesso mediante pedidonumber[] · cm

number[] · cm

Não

Axle (support point) positions measured from the front of the cargo area; negative = in front of it. Same length as axle_max_loads. Each between −300 (an axle ahead of the cargo area, e.g. a rigid truck's front axle under the cab) and the vehicle length.

≤ 10 items

axle_max_loadsAcesso mediante pedidonumber[] · kg

number[] · kg

Não

Maximum cargo load per axle, in the order of axle_positions. Each greater than 0 and at most 100000.

≤ 10 items

cog_range_xAcesso mediante pedidonumber · cm

number · cm

Não

Allowed centre-of-gravity deviation from the middle of the length: 0 to length / 2.

cog_range_yAcesso mediante pedidonumber · cm

number · cm

Não

Allowed centre-of-gravity deviation from the middle of the width: 0 to width / 2.

tractor_weightAcesso mediante pedidonumber · kg

number · kg

Não

Semi-trailer axle model: tractor unit mass.

empty_trailer_weightAcesso mediante pedidonumber · kg

number · kg

Não

Semi-trailer axle model: unladen trailer mass.

front_axle_to_middle_axleAcesso mediante pedidonumber · cm

number · cm

Não

Semi-trailer axle model: tractor front axle to drive (middle) axle.

front_axle_to_tractor_cogAcesso mediante pedidonumber · cm

number · cm

Não

Semi-trailer axle model: front axle to tractor centre of gravity.

front_axle_to_kingpinAcesso mediante pedidonumber · cm

number · cm

Não

Semi-trailer axle model: front axle to kingpin (fifth wheel).

kingpin_to_rear_axleAcesso mediante pedidonumber · cm

number · cm

Não

Semi-trailer axle model: kingpin to trailer rear axle group.

trailer_cog_to_rear_axleAcesso mediante pedidonumber · cm

number · cm

Não

Semi-trailer axle model: trailer centre of gravity to rear axle group.

trailer_start_to_kingpinAcesso mediante pedidonumber · cm

number · cm

Não

Semi-trailer axle model: trailer front to kingpin.

max_middle_axle_weightAcesso mediante pedidonumber · kg

number · kg

Não

Semi-trailer axle model: legal drive (middle) axle limit.

max_rear_axle_weightAcesso mediante pedidonumber · kg

number · kg

Não

Semi-trailer axle model: legal rear axle group limit.

itemsItem[]obrigatório

Item[]

Sim

Item definitions. Each one may have quantity > 1. At least one.

groupsGroup[]

Group[]

Não

Optional groups (customers, stops, orders). Required for every group an item names when options.group_routing is not "none"; otherwise groups are created from the item group names in order of appearance.

optionsOptions

Options

Não

Packing options. Every field is optional.

Exemplo de pedido

curl -X POST "https://runner.cargoduo.com/v1/pack" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Idempotency-Key: order-1042-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042",
    "vehicles": [
      {
        "id": "trailer",
        "type": "trailer",
        "name": "13.6 m trailer",
        "length": 1360,
        "width": 245,
        "height": 270,
        "max_weight": 24000
      }
    ],
    "items": [
      {
        "id": "pallet-eu",
        "label": "Euro pallet",
        "length": 120,
        "width": 80,
        "height": 140,
        "weight": 450,
        "quantity": 18,
        "stackable": false
      },
      {
        "id": "carton-a",
        "label": "Carton A",
        "length": 60,
        "width": 40,
        "height": 40,
        "weight": 12,
        "quantity": 40,
        "rotation": "upright"
      }
    ],
    "options": {
      "packing_mode": "auto"
    }
  }'

const res = await fetch("https://runner.cargoduo.com/v1/pack", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CARGODUO_API_KEY}`,
    "Idempotency-Key": "order-1042-v1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "reference": "order-1042",
    "vehicles": [
      {
        "id": "trailer",
        "type": "trailer",
        "name": "13.6 m trailer",
        "length": 1360,
        "width": 245,
        "height": 270,
        "max_weight": 24000
      }
    ],
    "items": [
      {
        "id": "pallet-eu",
        "label": "Euro pallet",
        "length": 120,
        "width": 80,
        "height": 140,
        "weight": 450,
        "quantity": 18,
        "stackable": false
      },
      {
        "id": "carton-a",
        "label": "Carton A",
        "length": 60,
        "width": 40,
        "height": 40,
        "weight": 12,
        "quantity": 40,
        "rotation": "upright"
      }
    ],
    "options": {
      "packing_mode": "auto"
    }
  }),
});

const data = await res.json();
console.log(res.status, data);

import os
import requests

response = requests.post(
    "https://runner.cargoduo.com/v1/pack",
    headers={"Authorization": f"Bearer {os.environ['CARGODUO_API_KEY']}", "Idempotency-Key": "order-1042-v1"},
    json={
        "reference": "order-1042",
        "vehicles": [
            {
                "id": "trailer",
                "type": "trailer",
                "name": "13.6 m trailer",
                "length": 1360,
                "width": 245,
                "height": 270,
                "max_weight": 24000,
            },
        ],
        "items": [
            {
                "id": "pallet-eu",
                "label": "Euro pallet",
                "length": 120,
                "width": 80,
                "height": 140,
                "weight": 450,
                "quantity": 18,
                "stackable": False,
            },
            {
                "id": "carton-a",
                "label": "Carton A",
                "length": 60,
                "width": 40,
                "height": 40,
                "weight": 12,
                "quantity": 40,
                "rotation": "upright",
            },
        ],
        "options": {
            "packing_mode": "auto",
        },
    },
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "reference": "order-1042",
  "vehicles": [
    {
      "id": "trailer",
      "type": "trailer",
      "name": "13.6 m trailer",
      "length": 1360,
      "width": 245,
      "height": 270,
      "max_weight": 24000
    }
  ],
  "items": [
    {
      "id": "pallet-eu",
      "label": "Euro pallet",
      "length": 120,
      "width": 80,
      "height": 140,
      "weight": 450,
      "quantity": 18,
      "stackable": false
    },
    {
      "id": "carton-a",
      "label": "Carton A",
      "length": 60,
      "width": 40,
      "height": 40,
      "weight": 12,
      "quantity": 40,
      "rotation": "upright"
    }
  ],
  "options": {
    "packing_mode": "auto"
  }
}`)

	req, err := http.NewRequest("POST", "https://runner.cargoduo.com/v1/pack", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CARGODUO_API_KEY"))
	req.Header.Set("Idempotency-Key", "order-1042-v1")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(out))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "reference": "order-1042",
              "vehicles": [
                {
                  "id": "trailer",
                  "type": "trailer",
                  "name": "13.6 m trailer",
                  "length": 1360,
                  "width": 245,
                  "height": 270,
                  "max_weight": 24000
                }
              ],
              "items": [
                {
                  "id": "pallet-eu",
                  "label": "Euro pallet",
                  "length": 120,
                  "width": 80,
                  "height": 140,
                  "weight": 450,
                  "quantity": 18,
                  "stackable": false
                },
                {
                  "id": "carton-a",
                  "label": "Carton A",
                  "length": 60,
                  "width": 40,
                  "height": 40,
                  "weight": 12,
                  "quantity": 40,
                  "rotation": "upright"
                }
              ],
              "options": {
                "packing_mode": "auto"
              }
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://runner.cargoduo.com/v1/pack"))
            .header("Authorization", "Bearer " + System.getenv("CARGODUO_API_KEY"))
            .header("Idempotency-Key", "order-1042-v1")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("CARGODUO_API_KEY"));
client.DefaultRequestHeaders.Add("Idempotency-Key", "order-1042-v1");

var json = """
    {
      "reference": "order-1042",
      "vehicles": [
        {
          "id": "trailer",
          "type": "trailer",
          "name": "13.6 m trailer",
          "length": 1360,
          "width": 245,
          "height": 270,
          "max_weight": 24000
        }
      ],
      "items": [
        {
          "id": "pallet-eu",
          "label": "Euro pallet",
          "length": 120,
          "width": 80,
          "height": 140,
          "weight": 450,
          "quantity": 18,
          "stackable": false
        },
        {
          "id": "carton-a",
          "label": "Carton A",
          "length": 60,
          "width": 40,
          "height": 40,
          "weight": 12,
          "quantity": 40,
          "rotation": "upright"
        }
      ],
      "options": {
        "packing_mode": "auto"
      }
    }
    """;

var request = new HttpRequestMessage(HttpMethod.Post, "https://runner.cargoduo.com/v1/pack")
{
    Content = new StringContent(json, Encoding.UTF8, "application/json"),
};
var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

<?php

$payload = <<<'JSON'
{
  "reference": "order-1042",
  "vehicles": [
    {
      "id": "trailer",
      "type": "trailer",
      "name": "13.6 m trailer",
      "length": 1360,
      "width": 245,
      "height": 270,
      "max_weight": 24000
    }
  ],
  "items": [
    {
      "id": "pallet-eu",
      "label": "Euro pallet",
      "length": 120,
      "width": 80,
      "height": 140,
      "weight": 450,
      "quantity": 18,
      "stackable": false
    },
    {
      "id": "carton-a",
      "label": "Carton A",
      "length": 60,
      "width": 40,
      "height": 40,
      "weight": 12,
      "quantity": 40,
      "rotation": "upright"
    }
  ],
  "options": {
    "packing_mode": "auto"
  }
}
JSON;

$ch = curl_init('https://runner.cargoduo.com/v1/pack');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CARGODUO_API_KEY'),
        'Idempotency-Key: order-1042-v1',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

require "net/http"
require "uri"

uri = URI("https://runner.cargoduo.com/v1/pack")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("CARGODUO_API_KEY")}"
request["Idempotency-Key"] = "order-1042-v1"
request["Content-Type"] = "application/json"
request.body = <<~'JSON'
  {
    "reference": "order-1042",
    "vehicles": [
      {
        "id": "trailer",
        "type": "trailer",
        "name": "13.6 m trailer",
        "length": 1360,
        "width": 245,
        "height": 270,
        "max_weight": 24000
      }
    ],
    "items": [
      {
        "id": "pallet-eu",
        "label": "Euro pallet",
        "length": 120,
        "width": 80,
        "height": 140,
        "weight": 450,
        "quantity": 18,
        "stackable": false
      },
      {
        "id": "carton-a",
        "label": "Carton A",
        "length": 60,
        "width": 40,
        "height": 40,
        "weight": 12,
        "quantity": 40,
        "rotation": "upright"
      }
    ],
    "options": {
      "packing_mode": "auto"
    }
  }
JSON

response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
puts response.code, response.body

Exemplo de resposta

202 Accepted · Job

{
  "id": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
  "object": "job",
  "status": "queued",
  "reference": "order-1042",
  "source": "api",
  "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.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).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.
400Bad requestinvalid_jsonidempotency_key_invalidError
- 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_expiredError
- 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_creditsError
- 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_missingError
- 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
413Payload too largepayload_too_largeError
- payload_too_largeThe request body exceeds 10 MB.
NomeTipoObrigatórioDescrição
errorErrorBodyobrigatório
ErrorBody
Sim
Todos os códigos de erro
422Unprocessable entityvalidation_failedError
- 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_limitedError
- 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_errorError
- internal_errorSomething failed on our side.
NomeTipoObrigatórioDescrição
errorErrorBodyobrigatório
ErrorBody
Sim
Todos os códigos de erro
503Service unavailableapi_disabledError
- 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

QuickstartCreate a key, send one request, read the plan.IdempotencyRetry POST /v1/pack without creating a second job.Credits & pricingWhat a job costs and where credits come from.Results & coordinatesWhere every item sits, in which orientation and loading order.

Autenticação

Parâmetros de consulta

Parâmetros de cabeçalho

Parâmetros do corpo

Exemplo de pedido

Exemplo de resposta

Respostas

Relacionados