Documentation API

L'API REST de Cargamento permet à une autre application (ERP, logiciel d'entrepôt, TMS, application mobile) de calculer une palettisation, un plan de chargement et un ordre de préparation au quai, et d'enregistrer des plans consultables par un lien.

• Base : https://cargamento.vozit.dev/api/v1
• Format : JSON en UTF-8, en entrée comme en sortie.
• Contrat OpenAPI 3 : https://cargamento.vozit.dev/api/v1/openapi.json
• Unités : centimètres, kilogrammes ; volumes en m³ sauf mention contraire.

Le calcul de l'API est exactement celui de l'outil en ligne : mêmes règles, mêmes résultats, mêmes messages.

Authentification

Chaque application reçoit une clé, créée par un administrateur dans Administration › Clés d'API. Envoyez-la dans l'en-tête Authorization :

Authorization: Bearer cg_0123456789abcdef0123456789abcdef01234567

L'en-tête X-Api-Key: cg_… est accepté aussi. La clé ne doit jamais être exposée dans du code exécuté par un navigateur public : appelez l'API depuis votre serveur.

Limites

Erreurs

Toute erreur renvoie un objet error :

{
  "error": {
    "code": "validation_error",
    "message": "Saisie invalide.",
    "details": [
      { "field": "carton.length", "message": "Doit être supérieur à 0." },
      { "field": "lines[2].palletCode", "message": "Type de palette inconnu « xyz »." }
    ]
  }
}

Erreur de saisie et impossibilité métier sont distinctes : un colis plus grand que la palette n'est pas une saisie invalide. POST /palletize répond alors 200 avec result.ok = false et un result.error lisible.

Saisie des valeurs

• Les nombres peuvent être envoyés en JSON (12.5) ou en texte ("12,5", "12.5").
• Les booléens acceptent true / false, 1 / 0, "oui" / "non".
• Les codes de référentiel (palletCode, vehicleCode) sont résolus en cotes ; les cotes envoyées explicitement priment sur celles du référentiel.

Points d'accès

GET /ping

curl -s https://cargamento.vozit.dev/api/v1/ping -H "Authorization: Bearer $CLE"

{ "ok": true, "key": "ERP Cyprès", "version": "v1", "time": "2026-10-19T14:02:11+02:00" }

GET /referentials

{
  "pallets": [
    { "code": "eur", "label": "EUR / EPAL 120 × 80", "shortLabel": "EUR 120×80", "length": 120, "width": 80, "deckHeight": 14.4, "tare": 25, "active": true }
  ],
  "vehicles": [
    { "code": "semi", "label": "Semi-remorque standard (13,60 m)", "length": 1360, "width": 248, "height": 270, "payload": 24000, "active": true }
  ],
  "thresholds": { "cogMin": 0.3, "cogMax": 0.65, "lateral": 0.05 }
}

Codes livrés : palettes eur, ind, demi, quart, us ; véhicules semi, mega, p19, p12, vl20, c20, c40, c40hc. L'administrateur peut en ajouter ou les modifier : lisez cette route plutôt que de figer les codes.

POST /palletize

Corps :

Il faut palletCode ou pallet (ou les deux).

curl -s https://cargamento.vozit.dev/api/v1/palletize \
  -H "Authorization: Bearer $CLE" -H "Content-Type: application/json" \
  -d '{"ref":"Carton 40x30x25","carton":{"length":40,"width":30,"height":25,"weight":8},
       "palletCode":"eur","maxHeight":180,"maxWeight":800,"orderQty":500,"stop":2,"stackable":true}'

Réponse (le tableau layout est abrégé) :

{
  "result": {
    "ok": true,
    "ref": "Carton 40x30x25",
    "orientation": "upright",
    "orientationLabel": "debout",
    "footprint": { "length": 40, "width": 30 },
    "cartonHeight": 25,
    "perLayer": 8,
    "layers": 6,
    "total": 48,
    "pattern": "columns",
    "layout": [ { "x": 0, "y": 0, "length": 30, "width": 40 }, "…" ],
    "usable": { "length": 120, "width": 80, "height": 165.6, "weight": 775 },
    "overhang": 0,
    "palletHeight": 164.4,
    "grossWeight": 409,
    "fillVolume": 0.905797,
    "fillArea": 1,
    "palletVolume": 1.57824,
    "cartonsVolume": 1.44,
    "limit": "height",
    "order": {
      "qty": 500, "fullPallets": 10, "pallets": 11,
      "partial": { "cartons": 20, "layers": 3, "height": 89.4, "weight": 185 }
    },
    "loadLines": [
      { "name": "Carton 40x30x25", "palletCode": "eur", "length": 120, "width": 80, "stackable": true, "stop": 2, "height": 164.4, "weight": 409, "qty": 10 },
      { "name": "Carton 40x30x25 (incomplète)", "palletCode": "eur", "length": 120, "width": 80, "stackable": true, "stop": 2, "height": 89.4, "weight": 185, "qty": 1 }
    ]
  },
  "input": { "…": "saisie normalisée" }
}

Cas d'impossibilité (200) :

{ "result": { "ok": false, "error": { "code": "tooBig", "message": "Le colis est plus grand que la palette." } } }

Codes possibles : dimensions, pallet, weight, maxHeight, maxWeight, tooBig, tooHigh, tooHeavy.

POST /load-plan

Corps :

Il faut vehicleCode ou vehicle (ou les deux).

Ligne de palettes (palettes déjà constituées) :

Ligne de commande : une ligne qui contient carton est une commande de colis. Elle accepte tous les champs de /palletize (plus id et name), est palettisée puis remplacée par ses palettes complètes (identifiant id) et sa palette incomplète (identifiant id-partial). Le résumé de chaque palettisation est renvoyé dans orders.

curl -s https://cargamento.vozit.dev/api/v1/load-plan \
  -H "Authorization: Bearer $CLE" -H "Content-Type: application/json" \
  -d '{
    "vehicleCode": "p19",
    "maxStack": 2,
    "lines": [
      { "id": "CMD-1", "name": "Commande Dupont", "stop": 2,
        "carton": { "length": 40, "width": 30, "height": 25, "weight": 8 },
        "palletCode": "eur", "maxHeight": 180, "maxWeight": 800, "orderQty": 500 },
      { "id": "P-2", "name": "Palettes prêtes", "palletCode": "demi",
        "height": 90, "weight": 150, "qty": 4, "stackable": true, "stop": 1 }
    ]
  }'

Réponse (tableaux abrégés au premier élément) :

{
  "plan": {
    "vehicle": { "code": "p19", "label": "Porteur 19 t (7,50 m)", "length": 750, "width": 248, "height": 260, "payload": 10000 },
    "gap": 0,
    "maxStack": 2,
    "thresholds": { "cogMin": 0.3, "cogMax": 0.65, "lateral": 0.05 },
    "lines": [ { "index": 0, "id": "CMD-1", "name": "Commande Dupont", "stop": 2 } ],
    "rows": [ { "row": 1, "x": 0, "depth": 120, "stop": 2, "steps": [1, 2, 3] } ],
    "placements": [
      {
        "step": 1, "row": 1, "x": 0, "y": 4, "alongL": 120, "acrossW": 80,
        "side": "Gauche", "crosswise": false,
        "stack": {
          "units": ["CMD-1"], "levels": 1, "length": 120, "width": 80,
          "height": 164.4, "weight": 409, "volume": 1578240, "stop": 2,
          "baseLineIndex": 0, "topLineIndex": 0, "mixed": false, "content": "Commande Dupont"
        }
      }
    ],
    "overflow": [],
    "indicators": {
      "palletsRequested": 15, "palletsLoaded": 15, "floorSpots": 13, "rows": 5,
      "loadingMeters": 500, "remainingLength": 250,
      "weight": 4875, "payload": 10000, "volume": 18.3686, "boxVolume": 48.36,
      "cog": { "x": 242.5, "y": 124, "xRatio": 0.323333, "yOffset": 0 },
      "gauges": {
        "weight": { "ratio": 0.4875, "level": "ok" },
        "loadingMeters": { "ratio": 0.666667, "level": "ok" },
        "floor": { "ratio": 0.619355, "level": "ok" },
        "volume": { "ratio": 0.379831, "level": "ok" }
      }
    },
    "alerts": [ { "level": "ok", "code": "ok", "message": "Tout est chargé, dans les limites de poids et de dimensions." } ],
    "dock": {
      "width": 248, "depth": 500, "area": 12.4,
      "rows": [ { "row": 1, "y": 0, "depth": 120 } ],
      "spots": [ { "step": 1, "row": 1, "x": 4, "y": 0, "width": 80, "depth": 120, "levels": 1, "lineIndex": 0 } ],
      "sequence": [ { "step": 1, "row": 1, "side": "Gauche", "content": "Commande Dupont", "crosswise": false, "height": 164.4, "weight": 409, "stop": 2, "lineIndex": 0 } ]
    }
  },
  "orders": [
    { "lineIndex": 0, "id": "CMD-1", "ref": "Colis", "perLayer": 8, "layers": 6, "perPallet": 48,
      "palletHeight": 164.4, "grossWeight": 409, "limit": "height",
      "order": { "qty": 500, "fullPallets": 10, "pallets": 11, "partial": { "cartons": 20, "layers": 3, "height": 89.4, "weight": 185 } } }
  ],
  "input": { "vehicle": { "…": "…" }, "lines": [ { "id": "CMD-1", "…": "…" }, { "id": "CMD-1-partial", "…": "…" }, { "id": "P-2", "…": "…" } ] }
}

Repère : origine à l'avant gauche du plancher (côté cabine, côté conducteur). x le long du camion vers les portes, y en travers vers la droite.

POST /plans

Même corps que /load-plan, avec deux champs facultatifs : name (nom affiché) et reference (votre numéro de tournée ou de commande, 190 car., filtrable). Réponse 201 :

{
  "id": "Hk3mQ7pXa2Lr9TbN",
  "name": "Tournée Lyon du 21/10",
  "reference": "TRN-2026-1021",
  "url": "https://cargamento.vozit.dev/p/Hk3mQ7pXa2Lr9TbN",
  "createdAt": "2026-10-19T14:05:00+02:00",
  "updatedAt": "2026-10-19T14:05:00+02:00",
  "input": { "…": "saisie normalisée enregistrée" },
  "plan": { "…": "même structure que /load-plan" },
  "orders": []
}

url ouvre l'outil sur l'écran Camion avec ce plan : à envoyer au chef de quai ou à afficher dans votre application. Il faut un compte Cargamento pour l'ouvrir : sans session, la personne passe par la page de connexion puis arrive sur le plan. L'identifiant est aléatoire (16 caractères) et la page n'est pas indexée.

Seules les saisies sont enregistrées ; le résultat est recalculé à chaque lecture. Le véhicule est enregistré avec ses cotes : modifier ensuite le référentiel ne change pas le plan.

GET /plans

Paramètres : limit (1 à 200, défaut 50), offset, reference (égalité exacte). Ne renvoie que les plans créés par la clé appelante.

{ "data": [ { "id": "Hk3mQ7pXa2Lr9TbN", "name": "Tournée Lyon du 21/10", "reference": "TRN-2026-1021", "url": "…", "createdAt": "…", "updatedAt": "…" } ], "limit": 50, "offset": 0 }

GET /plans/{id}, PUT /plans/{id}, DELETE /plans/{id}

• GET renvoie la même structure que la création.
• PUT prend le même corps que POST /plans et remplace les saisies ; name et reference absents sont conservés.
• DELETE renvoie { "deleted": true, "id": "…" } ; le lien partagé cesse de fonctionner.

Un plan créé par une autre clé répond 404.

Recette d'intégration type

1. Au démarrage, GET /referentials pour proposer les véhicules et palettes à l'utilisateur.
2. À la préparation d'une tournée, envoyez POST /plans avec une ligne de commande par référence (champ carton) ou une ligne de palettes par lot déjà constitué, stop = rang de livraison, reference = votre numéro de tournée.
3. Si plan.alerts contient une alerte blocking, proposez un autre véhicule ou de scinder la tournée.
4. Enregistrez id et url ; affichez le lien au chef de quai.
5. Si la tournée change, PUT /plans/{id}.

Exemple en PHP

$ch = curl_init('https://cargamento.vozit.dev/api/v1/load-plan');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CARGAMENTO_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'vehicleCode' => 'semi',
        'lines' => [['id' => 'A', 'palletCode' => 'eur', 'height' => 150, 'weight' => 500, 'qty' => 33]],
    ]),
]);
$res = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
echo $res['plan']['indicators']['loadingMeters'] / 100, " m de plancher\n";   // 13.2

Exemple en JavaScript (Node 18+, côté serveur)

const res = await fetch('https://cargamento.vozit.dev/api/v1/palletize', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CARGAMENTO_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ carton: { length: 40, width: 30, height: 25, weight: 8 }, palletCode: 'eur', maxHeight: 180, maxWeight: 800 }),
});
const { result } = await res.json();
console.log(result.ok ? `${result.total} colis par palette` : result.error.message);

Versions

La version v1 est stable : on n'y retire ni ne renomme aucun champ. Les ajouts (nouveaux champs, nouvelles routes) sont annoncés dans le journal des versions. Une rupture ferait l'objet d'une v2 en parallèle.