Aller au contenu
Documentation développeursRéférence de l'APIChargement

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.

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

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

Clé API Bearer avec l'autorisationpack:writeEn savoir plus

Paramètres de requête

NomTypeObligatoireDescription
waitinteger
integer
Non

Nombre 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.

Par défaut 00–60

Paramètres d'en-tête

NomTypeObligatoireDescription
Idempotency-Keystring
string
Non

Toute 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.

≤ 128 chars

Paramètres du corps

application/json
NomTypeObligatoireDescription
referencestring
string
Non

Votre propre référence (numéro de commande, ID d'expédition…). Renvoyée telle quelle dans la tâche.

≤ 128 chars
vehiclesVehicle[]obligatoire
Vehicle[]
Oui

Définitions de véhicules. Chacune peut avoir quantity > 1. Au moins une.

itemsItem[]obligatoire
Item[]
Oui

Définitions d'articles. Chacune peut avoir quantity > 1. Au moins une.

groupsGroup[]
Group[]
Non

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.

optionsOptions
Options
Non

Options de chargement. Tous les champs sont facultatifs.

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

Exemple de réponse

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

Réponses

  • 200OKTâche terminée dans le délai ?wait, résultat inclus. Également le rejeu idempotent d'une tâche terminée.
    NomTypeObligatoireDescription
    idstringobligatoire
    string
    Oui

    ID de la tâche (job_…).

    objectstringobligatoire
    string
    Oui

    Toujours job.

    job
    statusstringobligatoire
    string
    Oui

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Non

    Votre référence, reprise de la requête.

    sourcestring
    string
    Non

    Origine de la tâche.

    apiplayground
    project_idstring
    string
    Non

    Le projet (prj_…) dans lequel une tâche POST /v1/projects/{id}/pack enregistre son plan. Absent pour les autres tâches.

    created_atstringobligatoire
    string
    Oui

    Horodatage RFC 3339.

    started_atstring | null
    string | null
    Non

    Date de début du calcul (RFC 3339) ou null.

    finished_atstring | null
    string | null
    Non

    Date de fin de la tâche (RFC 3339) ou null.

    progressJobProgress
    JobProgress
    Non

    Progression en direct pendant l'attente ou l'exécution.

    summaryJobSummary
    JobSummary
    Non

    Compteurs et durées.

    costJobCost
    JobCost
    Non

    Crédits débités (définitifs une fois la tâche terminée) et réservation bloquée pendant son exécution.

    errorJobError | null
    JobError | null
    Non

    Raison de l'échec ou de l'annulation de la tâche ; null sinon.

    warningsWarning[]
    Warning[]
    Non

    Remarques non bloquantes sur la requête (également reprises dans le résultat).

    result_urlstring
    string
    Non

    Appelez cette URL en GET pour obtenir le résultat complet une fois que status vaut succeeded.

    pdf_urlstring
    string
    Non

    Lien à 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_atstring
    string
    Non

    Date 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.

    resultResult
    Result
    Non

    Le résultat complet, inclus uniquement sur demande (?include=result) ou lorsque POST /v1/pack?wait= s'est terminé à temps.

  • 202AcceptedTâche acceptée (en file d'attente ou en cours).
    NomTypeObligatoireDescription
    idstringobligatoire
    string
    Oui

    ID de la tâche (job_…).

    objectstringobligatoire
    string
    Oui

    Toujours job.

    job
    statusstringobligatoire
    string
    Oui

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Non

    Votre référence, reprise de la requête.

    sourcestring
    string
    Non

    Origine de la tâche.

    apiplayground
    project_idstring
    string
    Non

    Le projet (prj_…) dans lequel une tâche POST /v1/projects/{id}/pack enregistre son plan. Absent pour les autres tâches.

    created_atstringobligatoire
    string
    Oui

    Horodatage RFC 3339.

    started_atstring | null
    string | null
    Non

    Date de début du calcul (RFC 3339) ou null.

    finished_atstring | null
    string | null
    Non

    Date de fin de la tâche (RFC 3339) ou null.

    progressJobProgress
    JobProgress
    Non

    Progression en direct pendant l'attente ou l'exécution.

    summaryJobSummary
    JobSummary
    Non

    Compteurs et durées.

    costJobCost
    JobCost
    Non

    Crédits débités (définitifs une fois la tâche terminée) et réservation bloquée pendant son exécution.

    errorJobError | null
    JobError | null
    Non

    Raison de l'échec ou de l'annulation de la tâche ; null sinon.

    warningsWarning[]
    Warning[]
    Non

    Remarques non bloquantes sur la requête (également reprises dans le résultat).

    result_urlstring
    string
    Non

    Appelez cette URL en GET pour obtenir le résultat complet une fois que status vaut succeeded.

    pdf_urlstring
    string
    Non

    Lien à 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_atstring
    string
    Non

    Date 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.

    resultResult
    Result
    Non

    Le résultat complet, inclus uniquement sur demande (?include=result) ou lorsque POST /v1/pack?wait= s'est terminé à temps.

  • 400Bad requestinvalid_jsonidempotency_key_invalid
    • invalid_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.
    NomTypeObligatoireDescription
    errorErrorBodyobligatoire
    ErrorBody
    Oui
    Tous les codes d'erreur
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedClé 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.
    NomTypeObligatoireDescription
    errorErrorBodyobligatoire
    ErrorBody
    Oui
    Tous les codes d'erreur
  • 402Payment requiredinsufficient_credits
    • insufficient_creditsLes crédits disponibles ne couvrent pas le coût minimal possible de cette tâche.
    NomTypeObligatoireDescription
    errorErrorBodyobligatoire
    ErrorBody
    Oui
    Tous les codes d'erreur
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_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.
    NomTypeObligatoireDescription
    errorErrorBodyobligatoire
    ErrorBody
    Oui
    Tous les codes d'erreur
  • 413Payload too largepayload_too_large
    • payload_too_largeLe corps de la requête dépasse 10 MB.
    NomTypeObligatoireDescription
    errorErrorBodyobligatoire
    ErrorBody
    Oui
    Tous les codes d'erreur
  • 422Unprocessable entityvalidation_failed
    • validation_failedLa requête est un JSON bien formé, mais décrit une tâche invalide. details[] liste tous les problèmes.
    NomTypeObligatoireDescription
    errorErrorBodyobligatoire
    ErrorBody
    Oui
    Tous les codes d'erreur
  • 429Too many requeststoo_many_jobsrate_limited
    • too_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.
    NomTypeObligatoireDescription
    errorErrorBodyobligatoire
    ErrorBody
    Oui
    Tous les codes d'erreur
  • 500Internal server errorinternal_error
    • internal_errorUne erreur s'est produite de notre côté.
    NomTypeObligatoireDescription
    errorErrorBodyobligatoire
    ErrorBody
    Oui
    Tous les codes d'erreur
  • 503Service unavailableapi_disabled
    • api_disabledL'API est temporairement désactivée (maintenance) ou désactivée pour l'organisation.
    NomTypeObligatoireDescription
    errorErrorBodyobligatoire
    ErrorBody
    Oui
    Tous les codes d'erreur