هذه الوثائق متاحة حاليًا باللغة الإنجليزية فقط.

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.

المصادقة

مفتاح API من نوع Bearer بالصلاحيةpack:writeاعرف المزيد

معاملات الاستعلام

الاسمالنوعمطلوبالوصف

waitinteger

integer

لا

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

الافتراضي 00–60

معاملات الترويسة

الاسمالنوعمطلوبالوصف

Idempotency-Keystring

string

لا

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

معاملات المحتوى

application/json

الاسمالنوعمطلوبالوصف

referencestring

string

لا

Your own reference (order number, shipment id…). Echoed back on the job.

≤ 128 chars

vehiclesVehicle[]مطلوب

Vehicle[]

نعم

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

idstring

string

لا

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

≤ 128 chars

vehicle_idstring

string

لا

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

لا

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

trucktrailerflatbedcontainerpalletaircraftship

namestring

string

لا

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

≤ 255 chars

lengthnumber · cm

number · cm

لا

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

widthnumber · cm

number · cm

لا

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

heightnumber · cm

number · cm

لا

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

max_weightnumber · kg

number · kg

لا

Maximum payload. Required unless vehicle_id is given.

quantityinteger

integer

لا

How many identical vehicles of this definition are available.

الافتراضي 11–100

floor_load_capacitynumber · kg/m²

number · kg/m²

لا

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

aux_deckboolean

boolean

لا

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

الافتراضي false

aux_deck_heightnumber · cm

number · cm

لا

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

aux_deck_max_weightnumber · kg

number · kg

لا

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

blocked_areasRect[]

Rect[]

لا

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

≤ 32 items

axle_positionsيتطلب صلاحية وصولnumber[] · cm

number[] · cm

لا

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_loadsيتطلب صلاحية وصولnumber[] · kg

number[] · kg

لا

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

≤ 10 items

cog_range_xيتطلب صلاحية وصولnumber · cm

number · cm

لا

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

cog_range_yيتطلب صلاحية وصولnumber · cm

number · cm

لا

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

tractor_weightيتطلب صلاحية وصولnumber · kg

number · kg

لا

Semi-trailer axle model: tractor unit mass.

empty_trailer_weightيتطلب صلاحية وصولnumber · kg

number · kg

لا

Semi-trailer axle model: unladen trailer mass.

front_axle_to_middle_axleيتطلب صلاحية وصولnumber · cm

number · cm

لا

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

front_axle_to_tractor_cogيتطلب صلاحية وصولnumber · cm

number · cm

لا

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

front_axle_to_kingpinيتطلب صلاحية وصولnumber · cm

number · cm

لا

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

kingpin_to_rear_axleيتطلب صلاحية وصولnumber · cm

number · cm

لا

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

trailer_cog_to_rear_axleيتطلب صلاحية وصولnumber · cm

number · cm

لا

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

trailer_start_to_kingpinيتطلب صلاحية وصولnumber · cm

number · cm

لا

Semi-trailer axle model: trailer front to kingpin.

max_middle_axle_weightيتطلب صلاحية وصولnumber · kg

number · kg

لا

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

max_rear_axle_weightيتطلب صلاحية وصولnumber · kg

number · kg

لا

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

itemsItem[]مطلوب

Item[]

نعم

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

groupsGroup[]

Group[]

لا

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

لا

Packing options. Every field is optional.

مثال على الطلب

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

مثال على الاستجابة

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

الاستجابات

200OKJob finished within ?wait, result inlined. Also an idempotent replay of a finished job.Job
الاسمالنوعمطلوبالوصف
idstringمطلوب
string
نعم
Job id (job_…).
objectstringمطلوب
string
نعم
Always job.
job
statusstringمطلوب
string
نعم
queued → running → succeeded | failed | canceled.
queuedrunningsucceededfailedcanceled
referencestring
string
لا
Your reference from the request.
sourcestring
string
لا
Where the job was created.
apiplayground
project_idstring
string
لا
The project (prj_…) a POST /v1/projects/{id}/pack job saves its plan into. Absent on other jobs.
created_atstringمطلوب
string
نعم
RFC 3339 timestamp.
started_atstring | null
string | null
لا
When computing started (RFC 3339) or null.
finished_atstring | null
string | null
لا
When the job ended (RFC 3339) or null.
progressJobProgress
JobProgress
لا
Live progress while queued/running.
summaryJobSummary
JobSummary
لا
Counts and timings.
costJobCost
JobCost
لا
Credits charged (final once the job ended) and the reservation held while it ran.
errorJobError | null
JobError | null
لا
Why the job failed or was canceled; null otherwise.
warningsWarning[]
Warning[]
لا
Non-blocking remarks about the request (also repeated in the result).
result_urlstring
string
لا
GET this URL for the full result once status is succeeded.
pdf_urlstring
string
لا
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
لا
When the request/result bodies and the PDF link are deleted (RFC 3339). Job metadata and charges are kept.
resultResult
Result
لا
The full result, inlined only when requested (?include=result) or when POST /v1/pack?wait= finished in time.
202AcceptedJob accepted (queued or running).Job
الاسمالنوعمطلوبالوصف
idstringمطلوب
string
نعم
Job id (job_…).
objectstringمطلوب
string
نعم
Always job.
job
statusstringمطلوب
string
نعم
queued → running → succeeded | failed | canceled.
queuedrunningsucceededfailedcanceled
referencestring
string
لا
Your reference from the request.
sourcestring
string
لا
Where the job was created.
apiplayground
project_idstring
string
لا
The project (prj_…) a POST /v1/projects/{id}/pack job saves its plan into. Absent on other jobs.
created_atstringمطلوب
string
نعم
RFC 3339 timestamp.
started_atstring | null
string | null
لا
When computing started (RFC 3339) or null.
finished_atstring | null
string | null
لا
When the job ended (RFC 3339) or null.
progressJobProgress
JobProgress
لا
Live progress while queued/running.
summaryJobSummary
JobSummary
لا
Counts and timings.
costJobCost
JobCost
لا
Credits charged (final once the job ended) and the reservation held while it ran.
errorJobError | null
JobError | null
لا
Why the job failed or was canceled; null otherwise.
warningsWarning[]
Warning[]
لا
Non-blocking remarks about the request (also repeated in the result).
result_urlstring
string
لا
GET this URL for the full result once status is succeeded.
pdf_urlstring
string
لا
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
لا
When the request/result bodies and the PDF link are deleted (RFC 3339). Job metadata and charges are kept.
resultResult
Result
لا
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.
الاسمالنوعمطلوبالوصف
errorErrorBodyمطلوب
ErrorBody
نعم
كل رموز الأخطاء
401Unauthorizedunauthorizedkey_revokedkey_expiredError
- unauthorizedMissing, malformed or unknown API key.
- key_revokedThe key was revoked.
- key_expiredThe key passed its expiry date.
الاسمالنوعمطلوبالوصف
errorErrorBodyمطلوب
ErrorBody
نعم
كل رموز الأخطاء
402Payment requiredinsufficient_creditsError
- insufficient_creditsAvailable credits do not cover the smallest possible run of this job.
الاسمالنوعمطلوبالوصف
errorErrorBodyمطلوب
ErrorBody
نعم
كل رموز الأخطاء
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.
الاسمالنوعمطلوبالوصف
errorErrorBodyمطلوب
ErrorBody
نعم
كل رموز الأخطاء
413Payload too largepayload_too_largeError
- payload_too_largeThe request body exceeds 10 MB.
الاسمالنوعمطلوبالوصف
errorErrorBodyمطلوب
ErrorBody
نعم
كل رموز الأخطاء
422Unprocessable entityvalidation_failedError
- validation_failedThe request is well-formed JSON but describes an invalid job. details[] lists every problem.
الاسمالنوعمطلوبالوصف
errorErrorBodyمطلوب
ErrorBody
نعم
كل رموز الأخطاء
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.
الاسمالنوعمطلوبالوصف
errorErrorBodyمطلوب
ErrorBody
نعم
كل رموز الأخطاء
500Internal server errorinternal_errorError
- internal_errorSomething failed on our side.
الاسمالنوعمطلوبالوصف
errorErrorBodyمطلوب
ErrorBody
نعم
كل رموز الأخطاء
503Service unavailableapi_disabledError
- api_disabledThe API is temporarily disabled (maintenance) or switched off for the organization.
الاسمالنوعمطلوبالوصف
errorErrorBodyمطلوب
ErrorBody
نعم
كل رموز الأخطاء

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.

المصادقة

معاملات الاستعلام

معاملات الترويسة

معاملات المحتوى

مثال على الطلب

مثال على الاستجابة

الاستجابات

ذو صلة