Skip to main content
Qargo

Intégrations - Importation de commandes dans Qargo

Importer des commandes dans Qargo via l'API ou des intégrations partenaires : mappage, validation et dépannage.

Table des matières
  1. Introduction
  2. Terminologie
  3. Dépannage

Introduction

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

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

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 via des partenaires d’intégration

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

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

Liste de contrôle du mappage des données

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

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

  • 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

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.

Pré-remplissages de commande (configurés par le Qargo admin)

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.

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

FAQ - Pré-remplissages

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.


Bonnes pratiques pour éviter les problèmes

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