Créer une tâche de chargement
Valide la requête, réserve sur vos crédits le prix maximal possible et met une tâche en file d'attente.
Répond 202 avec la tâche ; interrogez GET /v1/jobs/{id} ou passez ?wait= pour que la réponse attende la fin de la tâche. Les échecs de validation (422) sont gratuits et ne créent aucune tâche.
Authentification
Paramètres de requête
waitintegerNombre de secondes pendant lesquelles la réponse attend la fin de la tâche. Terminée à temps : 200 avec le résultat inclus. Sinon : 202.
00–60Paramètres d'en-tête
Idempotency-KeystringToute chaîne unique, par exemple un UUID ou votre numéro de commande. La même clé réutilisée dans un délai de 24 h renvoie la tâche d'origine au lieu d'en créer et d'en facturer une nouvelle.
Paramètres du corps
application/jsonreferencestringVotre propre référence (numéro de commande, ID d'expédition…). Renvoyée telle quelle dans la tâche.
vehiclesVehicle[]obligatoireDéfinitions de véhicules. Chacune peut avoir quantity > 1. Au moins une.
idstringVotre identifiant, unique dans la requête. Les résultats le désignent par vehicle_id. Par défaut : vehicle_id.
vehicle_idstringUn ID de véhicule issu de GET /v1/vehicles : un préréglage ou l'un des véhicules de votre organisation (veh_…). Fournit le type, le nom, les dimensions, la charge utile et toutes les autres valeurs enregistrées.
typestringType de véhicule. Obligatoire sauf si vehicle_id est fourni. Seuls les types listés dans GET /v1/limits (allowed_vehicle_types) sont acceptés.
trucktrailerflatbedcontainerpalletaircraftshipnamestringNom affiché (par défaut, le nom du véhicule enregistré ou l'ID).
lengthnumber · cmLongueur intérieure de l'espace de chargement, selon x (de la paroi avant vers la porte). Obligatoire sauf si vehicle_id est fourni.
widthnumber · cmLargeur intérieure de l'espace de chargement, selon z. Obligatoire sauf si vehicle_id est fourni.
heightnumber · cmHauteur intérieure de l'espace de chargement, selon y. Obligatoire sauf si vehicle_id est fourni.
max_weightnumber · kgCharge utile maximale. Obligatoire sauf si vehicle_id est fourni.
quantityintegerNombre de véhicules identiques disponibles pour cette définition.
11–100floor_load_capacitynumber · kg/m²Capacité de charge du plancher : 0 ou plus (0 = sans limite).
aux_deckbooleanLe véhicule a un second plancher (double plancher).
falseaux_deck_heightnumber · cmHauteur du second plancher au-dessus du plancher. Obligatoire lorsque aux_deck vaut true.
aux_deck_max_weightnumber · kgLimite de charge du second plancher. Obligatoire lorsque aux_deck vaut true.
blocked_areasRect[]Zones du plancher sur lesquelles rien ne peut être posé (passages de roue, dégâts, espace réservé). Chacune doit se trouver sur le plancher du véhicule.
xnumber · cmobligatoireDistance entre la paroi avant et le bord le plus proche du rectangle.
znumber · cmobligatoireDistance entre la paroi droite (z = 0 ; la droite vue depuis la porte, en regardant vers l'intérieur) et le bord le plus proche du rectangle.
lengthnumber · cmobligatoireÉtendue selon x.
widthnumber · cmobligatoireÉtendue selon z.
axle_positionsAccès requisnumber[] · cmPositions des essieux (points d'appui) mesurées depuis l'avant de l'espace de chargement ; négatif = en avant de celui-ci. Même nombre d'éléments que axle_max_loads. Chacune entre −300 (un essieu situé en avant de l'espace de chargement, par ex. l'essieu avant d'un porteur, sous la cabine) et la longueur du véhicule.
axle_max_loadsAccès requisnumber[] · kgCharge maximale par essieu, dans l'ordre du champ axle_positions. Chaque valeur doit être supérieure à 0 et au plus égale à 100000.
cog_range_xAccès requisnumber · cmÉcart admis du centre de gravité par rapport au milieu de la longueur : de 0 à length / 2.
cog_range_yAccès requisnumber · cmÉcart admis du centre de gravité par rapport au milieu de la largeur : de 0 à width / 2.
tractor_weightAccès requisnumber · kgModèle d'essieux de semi-remorque : masse du tracteur.
empty_trailer_weightAccès requisnumber · kgModèle d'essieux de semi-remorque : masse à vide de la remorque.
front_axle_to_middle_axleAccès requisnumber · cmModèle d'essieux de semi-remorque : de l'essieu avant du tracteur à l'essieu moteur (central).
front_axle_to_tractor_cogAccès requisnumber · cmModèle d'essieux de semi-remorque : de l'essieu avant au centre de gravité du tracteur.
front_axle_to_kingpinAccès requisnumber · cmModèle d'essieux de semi-remorque : de l'essieu avant au pivot d'attelage (sellette).
kingpin_to_rear_axleAccès requisnumber · cmModèle d'essieux de semi-remorque : du pivot d'attelage au groupe d'essieux arrière de la remorque.
trailer_cog_to_rear_axleAccès requisnumber · cmModèle d'essieux de semi-remorque : du centre de gravité de la remorque au groupe d'essieux arrière.
trailer_start_to_kingpinAccès requisnumber · cmModèle d'essieux de semi-remorque : de l'avant de la remorque au pivot d'attelage.
max_middle_axle_weightAccès requisnumber · kgModèle d'essieux de semi-remorque : limite légale de l'essieu moteur (central).
max_rear_axle_weightAccès requisnumber · kgModèle d'essieux de semi-remorque : limite légale du groupe d'essieux arrière.
itemsItem[]obligatoireDéfinitions d'articles. Chacune peut avoir quantity > 1. Au moins une.
idstringVotre identifiant, unique dans la requête. Les résultats le désignent par item_id. Par défaut : template_id.
template_idstringUn ID de modèle (tpl_…) issu de GET /v1/templates. Fournit tous les champs de l'article ; les champs envoyés en plus les remplacent.
labelstringLibellé affiché (par défaut, l'ID).
shapestringForme de l'article. cylinder et drum utilisent radius + height au lieu de length + width ; pallet et drum restent toujours debout.
boxcylinderpalletbagdrumPar défaut "box"lengthnumber · cmLongueur. Obligatoire sauf si shape vaut cylinder ou drum.
widthnumber · cmLargeur. Obligatoire sauf si shape vaut cylinder ou drum.
heightnumber · cmobligatoireHauteur (le côté vertical lorsque l'article est posé tel que défini).
radiusnumber · cmRayon. Obligatoire lorsque shape vaut cylinder ou drum.
weightnumber · kgobligatoirePoids d'UNE unité.
quantityintegerNombre d'unités identiques.
11–10000stackablebooleanD'autres articles peuvent être placés dessus.
truemax_stack_weightnumber · kgPoids maximal pouvant reposer sur une unité. 0 = illimité.
0rotationstringall = l'une des six orientations ; upright = rotation autour de l'axe vertical uniquement (ce côté vers le haut) ; fixed = jamais tourné.
alluprightfixedPar défaut "all"hazardousbooleanMarchandise dangereuse : placée près du plancher et séparée des autres articles dangereux.
falsepriorityintegerPriorité de chargement. Plus élevée = chargé en premier et conservé quand l'espace manque. 0 = aucune.
0groupstringNom du groupe auquel appartient cet article (voir groups et options.group_routing).
colorstringCouleur d'affichage au format #rrggbb (visionneuse et PDF uniquement).
nesting_heightnumber · cmRecouvrement télescopique lorsque des unités identiques s'empilent (caisses ou seaux emboîtables).
0groupsGroup[]Groupes facultatifs (clients, arrêts, commandes). Obligatoires pour chaque groupe cité par un article lorsque options.group_routing ne vaut pas "none" ; sinon, les groupes sont créés à partir des noms de groupe des articles, dans leur ordre d'apparition.
namestringobligatoireNom du groupe, référencé par Item.group.
orderintegerOrdre de chargement (plus petit = chargé en premier). Par défaut : sa position dans la liste.
colorstringCouleur d'affichage au format #rrggbb.
optionsOptionsOptions de chargement. Tous les champs sont facultatifs.
packing_modestringauto = lorsque les véhicules listés sont pleins, d'autres exemplaires du véhicule le plus adapté sont ajoutés (dans la limite de véhicules de la tâche) ; fleet_only = seuls les véhicules listés sont utilisés, et ce qui ne rentre pas est signalé comme non placé.
autofleet_onlyPar défaut "auto"group_routingstringnone = les groupes sont informatifs ; wall = chaque groupe dispose de sa propre section du véhicule ; routing = les groupes sont chargés dans l'ordre et un groupe ultérieur peut se placer sur ou à côté d'un groupe précédent, mais jamais en dessous (livraison multi-arrêts) ; no_stack = les groupes sont chargés dans l'ordre côte à côte, jamais les uns sur les autres.
nonewallroutingno_stackPar défaut "none"allow_overweightbooleanIgnore les limites de charge utile des véhicules.
falsemax_stack_itemsintegerNombre maximal d'articles par pile. 0 = illimité.
0max_stack_density_kg_m2number · kg/m²Poids maximal d'une pile par surface au sol. 0 = illimité.
0lock_rotationsbooleanConserve la première orientation compatible avec la hauteur du véhicule.
falsegroup_identical_binsbooleanTraite les véhicules identiques comme un seul ensemble.
falsetime_limitnumber · sBorne supérieure du temps de calcul pour l'ensemble de la tâche. 0 = automatique (plafonné à max_time_limit_seconds de GET /v1/limits). Une fois la limite atteinte, le meilleur plan trouvé jusque-là est renvoyé. Vous ne payez que le temps de calcul réellement consommé.
0enforce_axleAccès requisbooleanRejette les placements qui surchargent un groupe d'essieux, sur les véhicules qui renseignent les dix champs du modèle d'essieux.
falseExemple de requête
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.bodyExemple de réponse
{
"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"
}Réponses
200OKTâche terminée dans le délai ?wait, résultat inclus. Également le rejeu idempotent d'une tâche terminée.
NomTypeObligatoireDescriptionidstringobligatoirestringOuiID de la tâche (job_…).
objectstringobligatoirestringOuiToujours
job.jobstatusstringobligatoirestringOuiqueued→running→succeeded|failed|canceled.queuedrunningsucceededfailedcanceledreferencestringstringNonVotre référence, reprise de la requête.
sourcestringstringNonOrigine de la tâche.
apiplaygroundproject_idstringstringNonLe projet (prj_…) dans lequel une tâche POST /v1/projects/{id}/pack enregistre son plan. Absent pour les autres tâches.
created_atstringobligatoirestringOuiHorodatage RFC 3339.
started_atstring | nullstring | nullNonDate de début du calcul (RFC 3339) ou
null.finished_atstring | nullstring | nullNonDate de fin de la tâche (RFC 3339) ou
null.progressJobProgressJobProgressNonProgression en direct pendant l'attente ou l'exécution.
stagestringstringNonÉtape en cours, par exemple
queued,running,finalizingoudone. Informative uniquement : basez votre logique surJob.status.vehicles_doneintegerintegerNonVéhicules chargés jusqu'ici.
placed_itemsintegerintegerNonUnités d'articles placées jusqu'ici.
summaryJobSummaryJobSummaryNonCompteurs et durées.
items_requestedintegerintegerNonNombre total d'unités d'articles (somme des quantités).
items_placedintegerintegerNonUnités placées.
items_unplacedintegerintegerNonUnités qui n'ont pas pu être placées.
vehicles_usedintegerintegerNonVéhicules transportant au moins un article.
total_weightnumber · kgnumber · kgNonPoids chargé.
volume_utilizationnumbernumberNonTaux de remplissage moyen (en volume) des véhicules utilisés, 0–1.
queue_msintegerintegerNonTemps d'attente d'un créneau de calcul (non facturé).
compute_msintegerintegerNonTemps de calcul (facturé).
costJobCostJobCostNonCrédits débités (définitifs une fois la tâche terminée) et réservation bloquée pendant son exécution.
creditsnumber · creditsnumber · creditsNonCrédits débités (0 jusqu'à la fin de la tâche). Les tâches en échec ne sont pas facturées, sauf time_limit_exceeded, facturée comme une tâche annulée.
reserved_creditsnumber · creditsnumber · creditsNonCrédits bloqués pendant que la tâche était en file d'attente ou en cours (le prix maximal possible). Libérés à la fin.
rate_card_versionintegerintegerNonGrille tarifaire appliquée à la tâche.
breakdownCostBreakdownCostBreakdownNonDétail du prix.
basenumber · creditsnumber · creditsNonFrais de tâche.
vehiclesnumber · creditsnumber · creditsNonPar véhicule chargé (non facturé pour les tâches annulées ou en time_limit_exceeded).
computenumber · creditsnumber · creditsNonPar seconde de calcul, au prorata à la milliseconde près.
large_loadnumber · creditsnumber · creditsNonSupplément par tranche de 100 articles entamée au-delà du seuil de gros chargement.
errorJobError | nullJobError | nullNonRaison de l'échec ou de l'annulation de la tâche ;
nullsinon.codestringstringNonCode lisible par machine (voir Erreurs).
messagestringstringNonExplication en anglais.
warningsWarning[]Warning[]NonRemarques non bloquantes sur la requête (également reprises dans le résultat).
codestringstringNonCode lisible par machine.
messagestringstringNonExplication en anglais.
result_urlstringstringNonAppelez cette URL en GET pour obtenir le résultat complet une fois que
statusvautsucceeded.pdf_urlstringstringNonLien à ouvrir dans un navigateur, qui génère le plan de chargement en PDF (vues 3D + étapes de chargement). Valide jusqu'à expires_at. Vide après expiration.
expires_atstringstringNonDate de suppression des corps de requête et de résultat et du lien PDF (RFC 3339). Les métadonnées et la facturation de la tâche sont conservées.
resultResultResultNonLe résultat complet, inclus uniquement sur demande (?include=result) ou lorsque POST /v1/pack?wait= s'est terminé à temps.
job_idstringstringNonLa tâche.
vehiclesResultVehicle[]ResultVehicle[]NonVéhicules chargés, dans l'ordre de chargement (les véhicules vides sont omis).
indexintegerintegerNonPosition dans le plan, à partir de 0.
vehicle_idstringstringNonL'ID de votre définition de véhicule (pour une tâche de projet : l'ID du véhicule du projet, pv_…).
copyintegerintegerNonNuméro d'exemplaire de cette définition, à partir de 1 (quantity > 1, ou ajouté en mode auto).
auto_addedbooleanbooleanNonAjouté par
packing_modeautoau-delà de laquantityindiquée.namestringstringNonNom du véhicule.
typestringstringNonType de véhicule.
lengthnumber · cmnumber · cmNonLongueur de l'espace de chargement.
widthnumber · cmnumber · cmNonLargeur de l'espace de chargement.
heightnumber · cmnumber · cmNonHauteur de l'espace de chargement.
max_weightnumber · kgnumber · kgNonLimite de charge utile.
items_placedintegerintegerNonUnités dans ce véhicule.
total_weightnumber · kgnumber · kgNonPoids dans ce véhicule.
volume_utilizationnumbernumberNonVolume utilisé / volume de l'espace de chargement, 0–1.
weight_utilizationnumbernumberNontotal_weight / max_weight, 0–1 (peut dépasser 1 avec allow_overweight).
center_of_gravityPointPointNonCentre de gravité du chargement (cm).
xnumber · cmnumber · cmNonynumber · cmnumber · cmNonznumber · cmnumber · cmNonplacementsPlacement[]Placement[]NonToutes les unités de ce véhicule.
item_idstringstringNonL'ID de votre définition d'article (pour une tâche de projet : l'ID de l'article, item_…).
instanceintegerintegerNonNuméro d'unité, à partir de 1, au sein de cette définition d'article (unique dans tout le plan).
labelstringstringNonLibellé de l'article.
xnumber · cmnumber · cmNonPosition du coin minimal sur la longueur.
ynumber · cmnumber · cmNonHauteur du coin minimal au-dessus du plancher.
znumber · cmnumber · cmNonPosition du coin minimal sur la largeur.
lengthnumber · cmnumber · cmNonDimension selon x, telle que placée.
widthnumber · cmnumber · cmNonDimension selon z, telle que placée.
heightnumber · cmnumber · cmNonDimension selon y, telle que placée.
rotatedbooleanbooleanNonPlacé dans une orientation différente de celle définie.
orientationstringstringNonQuel côté défini est orienté selon x, z et y :
lwh= tel que défini,wlh= tourné de 90° autour de l'axe vertical,lhw,hwl,whl,hlw= basculé sur un côté.stepintegerintegerNonÉtape de chargement dans le véhicule, à partir de 1 (chargez dans l'ordre croissant).
weightnumber · kgnumber · kgNonPoids unitaire.
axle_loadsAccès requisAxleLoad[]AxleLoad[]NonCharge par essieu (véhicules avec données d'essieux uniquement).
namestringstringNonAxle 1,Axle 2… dans l'ordre du champaxle_positions.positionnumber · cmnumber · cmNonPosition de l'essieu depuis l'avant de l'espace de chargement.
loadnumber · kgnumber · kgNonCharge de la marchandise sur l'essieu.
maxnumber · kgnumber · kgNonMaximum configuré (0 = aucun).
okbooleanbooleanNonload≤max(toujourstrueen l'absence de maximum).unplacedUnplacedItem[]UnplacedItem[]NonUnités qui n'ont pas pu être placées, avec la raison.
item_idstringstringNonL'ID de votre définition d'article.
instanceintegerintegerNonNuméro d'unité, à partir de 1.
labelstringstringNonLibellé de l'article.
reasonstringstringNonRaison pour laquelle l'unité n'a pas pu être placée.
warningsWarning[]Warning[]NonRemarques sur le plan.
codestringstringNonCode lisible par machine.
messagestringstringNonExplication en anglais.
pdf_urlstringstringNonLien à ouvrir dans un navigateur, qui génère le plan en PDF.
expires_atstringstringNonDate de suppression de ce résultat (RFC 3339).
202AcceptedTâche acceptée (en file d'attente ou en cours).
NomTypeObligatoireDescriptionidstringobligatoirestringOuiID de la tâche (job_…).
objectstringobligatoirestringOuiToujours
job.jobstatusstringobligatoirestringOuiqueued→running→succeeded|failed|canceled.queuedrunningsucceededfailedcanceledreferencestringstringNonVotre référence, reprise de la requête.
sourcestringstringNonOrigine de la tâche.
apiplaygroundproject_idstringstringNonLe projet (prj_…) dans lequel une tâche POST /v1/projects/{id}/pack enregistre son plan. Absent pour les autres tâches.
created_atstringobligatoirestringOuiHorodatage RFC 3339.
started_atstring | nullstring | nullNonDate de début du calcul (RFC 3339) ou
null.finished_atstring | nullstring | nullNonDate de fin de la tâche (RFC 3339) ou
null.progressJobProgressJobProgressNonProgression en direct pendant l'attente ou l'exécution.
stagestringstringNonÉtape en cours, par exemple
queued,running,finalizingoudone. Informative uniquement : basez votre logique surJob.status.vehicles_doneintegerintegerNonVéhicules chargés jusqu'ici.
placed_itemsintegerintegerNonUnités d'articles placées jusqu'ici.
summaryJobSummaryJobSummaryNonCompteurs et durées.
items_requestedintegerintegerNonNombre total d'unités d'articles (somme des quantités).
items_placedintegerintegerNonUnités placées.
items_unplacedintegerintegerNonUnités qui n'ont pas pu être placées.
vehicles_usedintegerintegerNonVéhicules transportant au moins un article.
total_weightnumber · kgnumber · kgNonPoids chargé.
volume_utilizationnumbernumberNonTaux de remplissage moyen (en volume) des véhicules utilisés, 0–1.
queue_msintegerintegerNonTemps d'attente d'un créneau de calcul (non facturé).
compute_msintegerintegerNonTemps de calcul (facturé).
costJobCostJobCostNonCrédits débités (définitifs une fois la tâche terminée) et réservation bloquée pendant son exécution.
creditsnumber · creditsnumber · creditsNonCrédits débités (0 jusqu'à la fin de la tâche). Les tâches en échec ne sont pas facturées, sauf time_limit_exceeded, facturée comme une tâche annulée.
reserved_creditsnumber · creditsnumber · creditsNonCrédits bloqués pendant que la tâche était en file d'attente ou en cours (le prix maximal possible). Libérés à la fin.
rate_card_versionintegerintegerNonGrille tarifaire appliquée à la tâche.
breakdownCostBreakdownCostBreakdownNonDétail du prix.
basenumber · creditsnumber · creditsNonFrais de tâche.
vehiclesnumber · creditsnumber · creditsNonPar véhicule chargé (non facturé pour les tâches annulées ou en time_limit_exceeded).
computenumber · creditsnumber · creditsNonPar seconde de calcul, au prorata à la milliseconde près.
large_loadnumber · creditsnumber · creditsNonSupplément par tranche de 100 articles entamée au-delà du seuil de gros chargement.
errorJobError | nullJobError | nullNonRaison de l'échec ou de l'annulation de la tâche ;
nullsinon.codestringstringNonCode lisible par machine (voir Erreurs).
messagestringstringNonExplication en anglais.
warningsWarning[]Warning[]NonRemarques non bloquantes sur la requête (également reprises dans le résultat).
codestringstringNonCode lisible par machine.
messagestringstringNonExplication en anglais.
result_urlstringstringNonAppelez cette URL en GET pour obtenir le résultat complet une fois que
statusvautsucceeded.pdf_urlstringstringNonLien à ouvrir dans un navigateur, qui génère le plan de chargement en PDF (vues 3D + étapes de chargement). Valide jusqu'à expires_at. Vide après expiration.
expires_atstringstringNonDate de suppression des corps de requête et de résultat et du lien PDF (RFC 3339). Les métadonnées et la facturation de la tâche sont conservées.
resultResultResultNonLe résultat complet, inclus uniquement sur demande (?include=result) ou lorsque POST /v1/pack?wait= s'est terminé à temps.
job_idstringstringNonLa tâche.
vehiclesResultVehicle[]ResultVehicle[]NonVéhicules chargés, dans l'ordre de chargement (les véhicules vides sont omis).
indexintegerintegerNonPosition dans le plan, à partir de 0.
vehicle_idstringstringNonL'ID de votre définition de véhicule (pour une tâche de projet : l'ID du véhicule du projet, pv_…).
copyintegerintegerNonNuméro d'exemplaire de cette définition, à partir de 1 (quantity > 1, ou ajouté en mode auto).
auto_addedbooleanbooleanNonAjouté par
packing_modeautoau-delà de laquantityindiquée.namestringstringNonNom du véhicule.
typestringstringNonType de véhicule.
lengthnumber · cmnumber · cmNonLongueur de l'espace de chargement.
widthnumber · cmnumber · cmNonLargeur de l'espace de chargement.
heightnumber · cmnumber · cmNonHauteur de l'espace de chargement.
max_weightnumber · kgnumber · kgNonLimite de charge utile.
items_placedintegerintegerNonUnités dans ce véhicule.
total_weightnumber · kgnumber · kgNonPoids dans ce véhicule.
volume_utilizationnumbernumberNonVolume utilisé / volume de l'espace de chargement, 0–1.
weight_utilizationnumbernumberNontotal_weight / max_weight, 0–1 (peut dépasser 1 avec allow_overweight).
center_of_gravityPointPointNonCentre de gravité du chargement (cm).
xnumber · cmnumber · cmNonynumber · cmnumber · cmNonznumber · cmnumber · cmNonplacementsPlacement[]Placement[]NonToutes les unités de ce véhicule.
item_idstringstringNonL'ID de votre définition d'article (pour une tâche de projet : l'ID de l'article, item_…).
instanceintegerintegerNonNuméro d'unité, à partir de 1, au sein de cette définition d'article (unique dans tout le plan).
labelstringstringNonLibellé de l'article.
xnumber · cmnumber · cmNonPosition du coin minimal sur la longueur.
ynumber · cmnumber · cmNonHauteur du coin minimal au-dessus du plancher.
znumber · cmnumber · cmNonPosition du coin minimal sur la largeur.
lengthnumber · cmnumber · cmNonDimension selon x, telle que placée.
widthnumber · cmnumber · cmNonDimension selon z, telle que placée.
heightnumber · cmnumber · cmNonDimension selon y, telle que placée.
rotatedbooleanbooleanNonPlacé dans une orientation différente de celle définie.
orientationstringstringNonQuel côté défini est orienté selon x, z et y :
lwh= tel que défini,wlh= tourné de 90° autour de l'axe vertical,lhw,hwl,whl,hlw= basculé sur un côté.stepintegerintegerNonÉtape de chargement dans le véhicule, à partir de 1 (chargez dans l'ordre croissant).
weightnumber · kgnumber · kgNonPoids unitaire.
axle_loadsAccès requisAxleLoad[]AxleLoad[]NonCharge par essieu (véhicules avec données d'essieux uniquement).
namestringstringNonAxle 1,Axle 2… dans l'ordre du champaxle_positions.positionnumber · cmnumber · cmNonPosition de l'essieu depuis l'avant de l'espace de chargement.
loadnumber · kgnumber · kgNonCharge de la marchandise sur l'essieu.
maxnumber · kgnumber · kgNonMaximum configuré (0 = aucun).
okbooleanbooleanNonload≤max(toujourstrueen l'absence de maximum).unplacedUnplacedItem[]UnplacedItem[]NonUnités qui n'ont pas pu être placées, avec la raison.
item_idstringstringNonL'ID de votre définition d'article.
instanceintegerintegerNonNuméro d'unité, à partir de 1.
labelstringstringNonLibellé de l'article.
reasonstringstringNonRaison pour laquelle l'unité n'a pas pu être placée.
warningsWarning[]Warning[]NonRemarques sur le plan.
codestringstringNonCode lisible par machine.
messagestringstringNonExplication en anglais.
pdf_urlstringstringNonLien à ouvrir dans un navigateur, qui génère le plan en PDF.
expires_atstringstringNonDate de suppression de ce résultat (RFC 3339).
400Bad request
invalid_jsonidempotency_key_invalidinvalid_jsonLe corps n'est pas un JSON valide ou un champ a un type incorrect.idempotency_key_invalidL'en-tête Idempotency-Key dépasse 128 caractères.
Tous les codes d'erreurNomTypeObligatoireDescriptionerrorErrorBodyobligatoireErrorBodyOuicodestringobligatoirestringOuiCode lisible par machine (snake_case). Basez votre logique sur ce champ, jamais sur
message.messagestringobligatoirestringOuiExplication en anglais.
request_idstringobligatoirestringOuiIdentique à l'en-tête X-Request-Id. Indiquez-le lorsque vous contactez le support.
detailsErrorDetail[]ErrorDetail[]NonProblèmes par champ (
validation_failed).pathstringstringNonChemin JSON du champ en cause, par ex. items[3].length.
codestringstringNonrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringNonExplication en anglais.
401Unauthorized
unauthorizedkey_revokedkey_expiredunauthorizedClé API absente, mal formée ou inconnue.key_revokedLa clé a été révoquée.key_expiredLa clé a dépassé sa date d'expiration.
Tous les codes d'erreurNomTypeObligatoireDescriptionerrorErrorBodyobligatoireErrorBodyOuicodestringobligatoirestringOuiCode lisible par machine (snake_case). Basez votre logique sur ce champ, jamais sur
message.messagestringobligatoirestringOuiExplication en anglais.
request_idstringobligatoirestringOuiIdentique à l'en-tête X-Request-Id. Indiquez-le lorsque vous contactez le support.
detailsErrorDetail[]ErrorDetail[]NonProblèmes par champ (
validation_failed).pathstringstringNonChemin JSON du champ en cause, par ex. items[3].length.
codestringstringNonrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringNonExplication en anglais.
402Payment required
insufficient_creditsinsufficient_creditsLes crédits disponibles ne couvrent pas le coût minimal possible de cette tâche.
Tous les codes d'erreurNomTypeObligatoireDescriptionerrorErrorBodyobligatoireErrorBodyOuicodestringobligatoirestringOuiCode lisible par machine (snake_case). Basez votre logique sur ce champ, jamais sur
message.messagestringobligatoirestringOuiExplication en anglais.
request_idstringobligatoirestringOuiIdentique à l'en-tête X-Request-Id. Indiquez-le lorsque vous contactez le support.
detailsErrorDetail[]ErrorDetail[]NonProblèmes par champ (
validation_failed).pathstringstringNonChemin JSON du champ en cause, par ex. items[3].length.
codestringstringNonrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringNonExplication en anglais.
403Forbidden
ip_not_allowedsubscription_inactiveaccount_inactivescope_missingip_not_allowedL'adresse IP appelante ne figure pas dans la liste des adresses IP autorisées de la clé.subscription_inactiveL'organisation n'a aucun abonnement actif incluant l'API.account_inactiveL'organisation est suspendue ou n'a aucun propriétaire dont le compte est actif.scope_missingIl manque à la clé une autorisation requise par cet endpoint.
Tous les codes d'erreurNomTypeObligatoireDescriptionerrorErrorBodyobligatoireErrorBodyOuicodestringobligatoirestringOuiCode lisible par machine (snake_case). Basez votre logique sur ce champ, jamais sur
message.messagestringobligatoirestringOuiExplication en anglais.
request_idstringobligatoirestringOuiIdentique à l'en-tête X-Request-Id. Indiquez-le lorsque vous contactez le support.
detailsErrorDetail[]ErrorDetail[]NonProblèmes par champ (
validation_failed).pathstringstringNonChemin JSON du champ en cause, par ex. items[3].length.
codestringstringNonrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringNonExplication en anglais.
413Payload too large
payload_too_largepayload_too_largeLe corps de la requête dépasse 10 MB.
Tous les codes d'erreurNomTypeObligatoireDescriptionerrorErrorBodyobligatoireErrorBodyOuicodestringobligatoirestringOuiCode lisible par machine (snake_case). Basez votre logique sur ce champ, jamais sur
message.messagestringobligatoirestringOuiExplication en anglais.
request_idstringobligatoirestringOuiIdentique à l'en-tête X-Request-Id. Indiquez-le lorsque vous contactez le support.
detailsErrorDetail[]ErrorDetail[]NonProblèmes par champ (
validation_failed).pathstringstringNonChemin JSON du champ en cause, par ex. items[3].length.
codestringstringNonrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringNonExplication en anglais.
422Unprocessable entity
validation_failedvalidation_failedLa requête est un JSON bien formé, mais décrit une tâche invalide. details[] liste tous les problèmes.
Tous les codes d'erreurNomTypeObligatoireDescriptionerrorErrorBodyobligatoireErrorBodyOuicodestringobligatoirestringOuiCode lisible par machine (snake_case). Basez votre logique sur ce champ, jamais sur
message.messagestringobligatoirestringOuiExplication en anglais.
request_idstringobligatoirestringOuiIdentique à l'en-tête X-Request-Id. Indiquez-le lorsque vous contactez le support.
detailsErrorDetail[]ErrorDetail[]NonProblèmes par champ (
validation_failed).pathstringstringNonChemin JSON du champ en cause, par ex. items[3].length.
codestringstringNonrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringNonExplication en anglais.
429Too many requests
too_many_jobsrate_limitedtoo_many_jobsL'organisation a déjà le nombre maximal de tâches en file d'attente + en cours.rate_limitedTrop de requêtes dans la minute, l'heure ou la journée en cours (par clé ou par organisation), ou plus de 60 échecs d'authentification par minute depuis votre adresse IP.
Tous les codes d'erreurNomTypeObligatoireDescriptionerrorErrorBodyobligatoireErrorBodyOuicodestringobligatoirestringOuiCode lisible par machine (snake_case). Basez votre logique sur ce champ, jamais sur
message.messagestringobligatoirestringOuiExplication en anglais.
request_idstringobligatoirestringOuiIdentique à l'en-tête X-Request-Id. Indiquez-le lorsque vous contactez le support.
detailsErrorDetail[]ErrorDetail[]NonProblèmes par champ (
validation_failed).pathstringstringNonChemin JSON du champ en cause, par ex. items[3].length.
codestringstringNonrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringNonExplication en anglais.
500Internal server error
internal_errorinternal_errorUne erreur s'est produite de notre côté.
Tous les codes d'erreurNomTypeObligatoireDescriptionerrorErrorBodyobligatoireErrorBodyOuicodestringobligatoirestringOuiCode lisible par machine (snake_case). Basez votre logique sur ce champ, jamais sur
message.messagestringobligatoirestringOuiExplication en anglais.
request_idstringobligatoirestringOuiIdentique à l'en-tête X-Request-Id. Indiquez-le lorsque vous contactez le support.
detailsErrorDetail[]ErrorDetail[]NonProblèmes par champ (
validation_failed).pathstringstringNonChemin JSON du champ en cause, par ex. items[3].length.
codestringstringNonrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringNonExplication en anglais.
503Service unavailable
api_disabledapi_disabledL'API est temporairement désactivée (maintenance) ou désactivée pour l'organisation.
Tous les codes d'erreurNomTypeObligatoireDescriptionerrorErrorBodyobligatoireErrorBodyOuicodestringobligatoirestringOuiCode lisible par machine (snake_case). Basez votre logique sur ce champ, jamais sur
message.messagestringobligatoirestringOuiExplication en anglais.
request_idstringobligatoirestringOuiIdentique à l'en-tête X-Request-Id. Indiquez-le lorsque vous contactez le support.
detailsErrorDetail[]ErrorDetail[]NonProblèmes par champ (
validation_failed).pathstringstringNonChemin JSON du champ en cause, par ex. items[3].length.
codestringstringNonrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringNonExplication en anglais.