---
title: "Intégrations - Importation de commandes dans Qargo"
description: "Importer des commandes dans Qargo via l'API ou des intégrations partenaires : mappage, validation et dépannage."
url: https://help.qargo.com/fr/articles/450378-integrations-importation-de-commandes-dans-qargo
locale: fr
updated: 2026-02-12
---

# Intégrations - Importation de commandes dans Qargo

## Introduction {#h_dd2958ae7f}

Qargo propose plusieurs façons d'intégrer des commandes en volume dans la plateforme. Cet article présente les concepts clés et les principaux modes d'importation utilisés par la plupart des clients : les partenaires d'intégration et l'API publique de Qargo. Il contient aussi des liens vers des ressources sur les importations manuelles et les flux des réseaux de palettes. Un guide de dépannage décrit les erreurs courantes et leur résolution.

## Terminologie {#h_59ca24e154}

| **Terme** | **Description** |
| --- | --- |
| Commande | Un enregistrement d'expédition dans Qargo. Une commande peut comporter un ou plusieurs arrêts et des documents associés. |
| Importation | Le processus de création ou de mise à jour de commandes dans Qargo par l'envoi de données structurées depuis un système externe. |
| Système source | Le système d'où proviennent les données, par exemple le TMS, l'ERP, le WMS ou la place de marché du client. |
| Mappage | La transformation des champs du système source vers le schéma de commande de Qargo. |
| DTO (Data Transfer Object) | La structure de données utilisée pour transmettre les données de commande à Qargo via des intégrations, l'EDI ou l'API. |
| Validation | Les contrôles effectués par Qargo pour vérifier que les données reçues sont complètes, correctement formatées et conformes aux règles métier. |
| Accusé de réception | La réponse renvoyée à l'expéditeur des données, qui indique un succès, un succès partiel avec avertissements ou un échec avec erreurs. |
| Clé d'idempotence | Un identifiant unique généré par le client et inclus dans une requête, généralement dans un en-tête HTTP. Elle permet de relancer une requête en toute sécurité, sans effet secondaire indésirable comme un doublon. |

### Aperçu des modes d'importation {#h_847e06915f}

Qargo prend en charge plusieurs méthodes d'importation. Cet article porte sur les trois modes automatisés les plus courants.

-   Partenaires d'intégration (connecteurs prêts à l'emploi)
-   Partenaires EDI (flux de documents aux normes du secteur)
-   API Qargo (intégration programmatique directe)

Pour les téléversements manuels de fichiers et les flux propres aux réseaux de palettes, consulter :

-   [Importation de données - Importer des données de commande](https://help.qargo.com/fr/articles/418636-data-import-importing-order-data)
-   [Importation de commandes PalletLine](https://help.qargo.com/fr/articles/143830-pn-palletline-order-import-export#h_34e1be7ccf)

### Importation via des partenaires d'intégration {#h_6e0d048f1b}

Idéal pour les entreprises qui utilisent des ERP, WMS ou plateformes logistiques courants disposant déjà d'un connecteur certifié par Qargo.

-   Fonctionnement

    -   Le connecteur du partenaire exporte les données de commande selon une planification ou sur événement.
    -   Le connecteur mappe le schéma du partenaire vers le DTO de commande de Qargo.
    -   Les données sont transmises à Qargo par un canal sécurisé défini par le connecteur.
    -   Qargo valide et intègre les données, puis renvoie les accusés de réception et le détail des erreurs.
-   Fonctionnalités habituelles

    -   Préréglages de mappage des champs gérés par le partenaire
    -   Mises à jour incrémentielles en cas de modification des commandes
    -   Prise en charge des pièces jointes lorsque le partenaire partage des documents
    -   Nouvelles tentatives automatiques et gestion des messages non distribuables (dead-letter)
-   Éléments à configurer

    -   Identifiants ou clés API fournis par Qargo ou le partenaire
    -   Remplacements de champs et règles de normalisation des valeurs (facultatifs)
    -   Comportements par défaut en cas de champs facultatifs manquants
    -   Préférences de notification en cas d'échec d'importation
-   Quand choisir cette option

    -   L'objectif est une mise en production la plus rapide possible, avec un minimum de code personnalisé
    -   Le partenaire prend déjà en charge Qargo ou un schéma très proche

### Importation via l'API Qargo {#h_baa8e418df}

Idéal pour les équipes qui veulent un contrôle total et un retour immédiat, ou lorsqu'aucun connecteur partenaire n'est disponible.

-   Modèle des points de terminaison

    -   Créer une commande
    -   Mettre à jour une commande
    -   Joindre des documents et des références
    -   Récupérer et rechercher des commandes pour confirmation
-   Recommandations sur le contenu des requêtes

    -   Utiliser la norme ISO 8601 pour les dates et heures, avec le décalage horaire
    -   Utiliser des unités cohérentes pour les poids, les volumes et les quantités
    -   Inclure des identifiants externes stables pour l'idempotence et le dédoublonnage
    -   Envoyer des adresses complètes dans la mesure du possible, codes pays compris
-   Bonnes pratiques de fiabilité

    -   Utiliser des clés d'idempotence pour relancer les requêtes en toute sécurité en cas de panne réseau
    -   Mettre en place un délai d'attente exponentiel (exponential backoff) pour les réponses 429 et les erreurs 5xx temporaires
    -   Consigner les erreurs de validation et les signaler aux équipes des opérations
-   Sécurité

    -   Utiliser des clés API à portée limitée ou OAuth, selon ce qui est fourni
    -   Renouveler régulièrement les identifiants et ne pas coder les secrets en dur
-   Quand choisir cette option

    -   L'entreprise maîtrise le système source et peut développer rapidement
    -   Un contrôle précis de la structure des données envoyées, du calendrier et des nouvelles tentatives est nécessaire

:::callout{tone="info"}
**🧰 Documentation technique de l'API Qargo disponible [ici](https://api.qargo.com/docs).**
:::

* * *

### Liste de contrôle du mappage des données {#h_1e6174b22f}

Avant la mise en production, vérifier que les éléments suivants sont alignés entre le système source et Qargo :

| Parties | Rôles de client, d'expéditeur, de destinataire, de payeur et de contact mappés de façon cohérente. |
| --- | --- |
| Emplacements | Noms, adresses, codes pays et géolocalisation facultative ; éviter le texte libre ambigu. |
| Dates et heures | Plages d'enlèvement, de livraison et de mise à disposition au format ISO 8601, avec des fuseaux horaires explicites. |
| Détails des marchandises | Lignes d'articles, colis, palettes, dimensions, indicateurs de marchandises dangereuses. |
| Prestations annexes et options | Suppléments et options de niveau de service mappés vers le modèle d'options de Qargo. |
| Références | Numéros de commande client, bons de commande et références des partenaires commerciaux. |
| Documents | Pièces jointes pour le CMR, le POD, les étiquettes et les documents douaniers, le cas échéant. |

### Contrôles opérationnels {#h_d12ae0008a}

| Dédoublonnage | Fournir un identifiant externe stable. Selon la configuration, Qargo peut rejeter les doublons ou les créer ou mettre à jour (upsert). |
| --- | --- |
| Mises à jour partielles | Décider si les mises à jour remplacent les objets complets ou modifient uniquement certains champs. |
| Gestion des statuts | Convenir des événements pouvant être définis par l'importation et de ceux pilotés par les opérations. |
| Stratégie de bascule | Définir une période pendant laquelle l'ancien et le nouveau système peuvent fonctionner en parallèle, et la manière d'éviter les doubles réservations. |

* * *

### Bonnes pratiques pour éviter les problèmes {#h_4c7206bfe1}

-   **Valider avant l'envoi**\
    Effectuer un contrôle préalable dans le système source : champs obligatoires, formats de date et d'heure, unités.

-   **Standardiser les codes**\
    Tenir une table de correspondance entre les services, les types d'équipement et les prestations annexes, et les codes Qargo.

-   **Utiliser l'idempotence**\
    Toujours envoyer des clés d'idempotence lors des créations. Consigner la correspondance entre chaque clé et le numéro de commande.

-   **Surveiller et alerter**\
    Configurer des notifications pour les importations en échec et intégrer les journaux d'erreurs aux outils d'observabilité.

-   **Documenter le mappage**\
    Tenir à jour un document de mappage afin que les modifications futures ne perturbent pas les importations.


-   Vérifier que toutes les données, en particulier les dates, respectent des formats valides.
-   Utiliser des identifiants uniques pour les nouvelles commandes afin d'éviter les erreurs de classification.
-   Valider régulièrement les fichiers d'importation pour détecter les fautes de frappe ou les incohérences de données.

## Dépannage {#h_b734cbfbc8}

Voici les erreurs courantes lors des importations de commandes, leurs causes probables et leur résolution. Le texte de l'erreur peut légèrement varier selon le mode d'importation.

:::callout{tone="info"}
**_Missing required field: customer\_id_**

-   Symptôme

    -   Erreur : Missing required field: customer\_id
-   Cause

    -   La source n'a pas fourni de client mappé ou a fourni une valeur inconnue.
-   Solution

    -   Vérifier que la fiche client existe dans Qargo et que le mappage utilise la bonne clé externe.
    -   Pour les partenaires, mettre à jour le mappage du connecteur.
    -   Pour l'API, inclure customer\_id ou une external\_customer\_ref résoluble.
:::

:::callout{tone="info"}
**_Invalid date-time format for pickup\_window.start_**

-   Symptôme

    -   Erreur : Invalid date-time. Expected ISO 8601 with timezone
-   Cause

    -   Date et heure envoyées sans fuseau horaire ou dans un format non ISO.
-   Solution

    -   Envoyer des chaînes au format ISO 8601, par exemple 2025-03-12T08:00:00+01:00.
    -   Valider les formats dans le système source avant l'envoi.
:::

:::callout{tone="info"}
**_Unknown location: consignee\_address_**

-   Symptôme

    -   Erreur : Location validation failed for consignee
-   Cause

    -   Adresse incomplète ou ambiguë, ou référence à un emplacement enregistré inexistant.
-   Solution

    -   Fournir l'adresse complète, code pays compris.
    -   En cas d'utilisation de références d'emplacement, synchroniser d'abord les données de référence.
:::

:::callout{tone="info"}
**_Unsupported addon code: LIFTGATE\_PREMIUM_**

-   Symptôme

    -   Erreur : Addon code not recognised
-   Cause

    -   La source utilise un code de service qui n'est pas configuré dans Qargo.
-   Solution

    -   Ajouter le code ou le mapper vers une option prise en charge dans Qargo.
    -   Normaliser les codes dans le connecteur avant la transmission.
:::

:::callout{tone="info"}
**_Duplicate order detected with external\_id=ABC-123_**

-   Symptôme

    -   Erreur : Duplicate order
-   Cause

    -   L'idempotence ou le dédoublonnage a signalé une création répétée.
-   Solution

    -   S'il s'agit d'une nouvelle tentative volontaire, réutiliser la même clé d'idempotence et vérifier le résultat précédent.
    -   S'il s'agit d'un véritable doublon, modifier l'external\_id ou convertir la requête en mise à jour.
:::

:::callout{tone="info"}
**_Document attachment rejected: file type not allowed_**

-   Symptôme

    -   Erreur : File type not supported
-   Cause

    -   Le type de pièce jointe ne figure pas dans la liste des types autorisés.
-   Solution

    -   Convertir le fichier dans un format pris en charge, généralement PDF ou les types d'image configurés pour l'espace de travail.
    -   Vérifier que l'intégration envoie correctement les types MIME.\
        ​
:::

:::callout{tone="info"}
**_API 429 Too Many Requests_**

-   Symptôme

    -   Réponses HTTP 429 et en-têtes de limitation du débit.
-   Cause

    -   Un pic de trafic dépasse les limites de débit.
-   Solution

    -   Mettre en place un délai d'attente exponentiel et respecter les en-têtes retry-after.
    -   Lisser la taille des lots et planifier les importations en dehors des heures de pointe.
:::

:::callout{tone="info"}
**_Message « Corriger les erreurs ? » sur l'écran d'importation de commandes_**

-   Symptôme

    -   L'utilisateur voit une bannière ou des messages dans les champs pendant la vérification.
-   Cause

    -   Une ou plusieurs commandes importées présentent des problèmes de validation qui nécessitent l'intervention d'un opérateur.
-   Solution

    -   Ouvrir la commande, vérifier les champs mis en évidence et corriger les valeurs.
    -   Si le même problème se reproduit, mettre à jour les règles de mappage à la source.
:::

### Pré-remplissages de commande (configurés par le Qargo admin) {#h_3ac5923fbb}

Si les données de commande pré-remplies semblent incorrectes ou ne correspondent pas à ce qui est attendu, la cause peut se trouver dans le mappage de l'importation de commande.

![](https://help.qargo.com/media/19487907ce21-image.png)

-   Les champs inclus dans le mappage de l'importation de commande ont priorité sur toutes les autres valeurs par défaut définies ailleurs dans la plateforme, par exemple les pré-remplissages issus de la fiche client.
-   Lorsque d'autres options sont définies et proposent **_plusieurs choix possibles_** (par ex. les extras), les valeurs issues de l'importation de commande sont ajoutées aux options déjà sélectionnées.

![](https://help.qargo.com/media/d020757bc01f-image.png)

### FAQ - Pré-remplissages {#h_c3aa0333a8}

**Q. Comment donner la priorité à certains pré-remplissages lorsqu'ils peuvent provenir de différentes sources pour un même champ cible ?**\
**Exemple : plages horaires de début et de fin ; des pré-remplissages peuvent être définis pour :**

-   **Service de transport**
-   **Client**
-   **Emplacement**
-   **Plage horaire**

**_R. Le pré-remplissage le plus spécifique est appliqué._** Dans l'exemple ci-dessus, la logique suit le niveau de précision des sélections : d'abord le service de transport, puis le client et les emplacements, et enfin la plage horaire de l'arrêt. Dans ce cas, le pré-remplissage provient de la dernière sélection (plage horaire), car c'est l'option considérée comme la plus spécifique

**Q. Est-il possible de pré-remplir les horaires d'ouverture de l'emplacement, ou faut-il les saisir manuellement pour chaque commande importée ? Existe-t-il un moyen rapide de récupérer les horaires de disponibilité des emplacements pour l'enlèvement ou la livraison ?**

**_R. Oui, il est possible de pré-remplir les horaires d'ouverture des emplacements lors de l'importation des commandes et de les inclure dans les paramètres de plage horaire de l'arrêt._** Cela permet de savoir clairement quand l'action d'arrêt peut être terminée, si aucun rendez-vous ni aucune plage horaire spécifique n'est requis. Un indicateur de fonctionnalité peut être activé afin d'utiliser automatiquement les horaires d'ouverture définis sur l'emplacement pour les importations de commandes.

::video{src="/media/video/25c8b24b68d9-2025-11-17_11-49-48-1-.mp4"}

:::callout{tone="note"}
💬 Pour activer cette fonctionnalité, contacter l'assistance Qargo ou le gestionnaire de compte.
:::

* * *

### Bonnes pratiques pour éviter les problèmes {#h_c79fd5b2a4}

-   Valider avant l'envoi\
    Effectuer un contrôle préalable dans le système source : champs obligatoires, formats de date et d'heure, unités.

-   Standardiser les codes\
    Tenir une table de correspondance entre les services, les types d'équipement et les prestations annexes, et les codes Qargo.

-   Utiliser l'idempotence\
    Toujours envoyer des clés d'idempotence lors des créations. Consigner la correspondance entre chaque clé et le numéro de commande.

-   Surveiller et alerter\
    Configurer des notifications pour les importations en échec et intégrer les journaux d'erreurs aux outils d'observabilité.

-   Documenter le mappage\
    Tenir à jour un document de mappage afin que les modifications futures ne perturbent pas les importations.


## Articles connexes

- [Intégrations : API Qargo – quoi, pourquoi et comment](https://help.qargo.com/fr/articles/865547-integrations-api-qargo-quoi-pourquoi-et-comment.md)
- [Importation de commande : routage des commandes par modèle – quoi, pourquoi et comment](https://help.qargo.com/fr/articles/681640-importation-de-commande-routage-des-commandes-par-modele-quoi-pourquoi-comment.md)
- [Importation de données – Importer des données d'emplacement](https://help.qargo.com/fr/articles/413082-importation-de-donnees-importer-des-donnees-d-emplacement.md)
- [Import de données : quoi, pourquoi, comment](https://help.qargo.com/fr/articles/169976-import-de-donnees-quoi-pourquoi-comment.md)
- [Commandes – Créer une commande](https://help.qargo.com/fr/articles/133885-commandes-creer-une-commande.md)
