Intégrations : API Qargo – quoi, pourquoi et comment
Découvrir comment connecter Qargo à des systèmes externes pour les commandes, les mises à jour de tournées, les données de référence et la comptabilité : configuration de l'API, identifiants, tests et dépannage.
Table des matières
Introduction
Qu’est-ce que l’API Qargo ?
- Un ensemble de connexions qui permettent à d’autres systèmes d’envoyer des données à Qargo et d’en recevoir.
- Elle couvre la saisie de commande et les statuts, l’exécution des tournées avec les sous-traitants, la synchronisation des données de référence et la comptabilité.
Pourquoi l’utiliser ?
- Elle supprime la double saisie entre Qargo et les autres systèmes utilisés par une entreprise de transport : systèmes des clients, systèmes des sous-traitants, logiciels de comptabilité, outils de gestion de flotte ou RH.
- Les données restent à jour dans les deux systèmes, sans importation manuelle.
Comment ça fonctionne ?
- Qargo attribue un ID d’intégrateur à la partie qui développe la connexion.
- Un super admin crée un client API pour le bon rôle et partage les identifiants de façon sécurisée.
- Qargo termine la configuration nécessaire sur le compte, puis l’intégration est testée et mise en production.
Prérequis
- Droits super admin dans Qargo.
- Un ID d’intégrateur délivré par Qargo (voir Étape 1 ci-dessous).
- Pour le rôle Client : Accès au portail client activé pour le client concerné.
- Pour les clients API Comptabilité qui comptabilisent des factures : une intégration API comptable configurée et liée à la bonne entité de facturation.
Types d’intégration
Il existe trois types d’intégration. Le type détermine la façon dont l’intégration est configurée.
- Tenant : une connexion directe entre Qargo et un système tiers utilisé par l’entreprise de transport, par exemple un logiciel de comptabilité.
- Client : une connexion depuis le système propre d’un client vers Qargo, par exemple pour soumettre des commandes via le portail client.
- Sous-traitant : une connexion depuis le système propre d’un sous-traitant vers Qargo, par exemple pour renvoyer à Qargo les mises à jour de tournées depuis son propre TMS.
Cas d’utilisation
- Un client souhaite envoyer ses commandes directement depuis son propre système vers Qargo, au lieu de les saisir dans le portail client.
- Un sous-traitant souhaite recevoir les affectations de tournées et renvoyer les mises à jour des arrêts et les POD depuis son propre TMS.
- Un nouveau chauffeur ou véhicule ajouté dans un système externe de gestion de flotte ou RH doit apparaître automatiquement dans les ressources Qargo.
- Le service financier souhaite que les factures et les avoirs soient transmis au logiciel de comptabilité, et que les statuts de paiement soient renvoyés à Qargo.
- Un groupe composé de plusieurs entités juridiques souhaite que le système comptable de chaque entité ne comptabilise que ses propres factures.
Terminologie
| Terme | Définition |
|---|---|
| API | Moyen permettant à deux systèmes d’échanger des données automatiquement. |
| Tenant | Le compte Qargo lui-même, c’est-à-dire l’entreprise de transport qui utilise Qargo. |
| Type d’intégration | Le bénéficiaire de la connexion : le tenant, l’un de ses clients ou l’un de ses sous-traitants. |
| Client API | Un ensemble d’identifiants de connexion (un ID client et un secret) qui permet à un système externe de se connecter à Qargo pour un rôle. |
| Rôle | Le type d’accès d’un client API : Gestion des commandes, Client, Gestion des données de référence ou Comptabilité. |
| ID d’intégrateur | Un ID unique fourni par Qargo qui identifie la partie qui développe l’intégration, afin de pouvoir contacter la bonne personne en cas de problème. |
| Secret | La clé privée affichée une seule fois lors de la création d’un client API. Elle ne peut plus être consultée ensuite. |
| Données de référence | Les enregistrements de base tels que les clients, les sous-traitants, les chauffeurs et les véhicules. |
| Entité de facturation | L’entreprise juridique ou interne du groupe qui émet une facture. |
| POD | Preuve de livraison : le document signé ou la photo qui confirme une livraison. |
| Order Export | Un point de terminaison qui renvoie toutes les données d’une commande existante, utilisé comme modèle pour construire de nouvelles requêtes de commande. |
| Configuration de l’importation de commande | Paramètres au niveau du compte, gérés par Qargo, qui déterminent la façon dont les commandes reçues via l’API entrent dans Qargo. |
| Contrôle API | La première étape d’une importation de commande. Qargo vérifie que le message est correctement construit (validation de la charge utile). |
| Importation Qargo | La deuxième étape d’une importation de commande. Qargo applique les données au compte (validation par le tenant). |
Configurer une connexion API
Étape 1 : demander l’intégration et un ID d’intégrateur
-
Envoyer un e-mail à success@qargo.com pour lancer la demande d’intégration.
-
Fournir les informations suivantes :
- Partenaire d’intégration : coordonnées de l’entreprise, ainsi que le nom et l’adresse e-mail du contact principal avec lequel Qargo travaillera. Si un tiers ou un intégrateur externe développe la connexion, indiquer ses coordonnées plutôt que celles du titulaire du compte Qargo.
- Type et périmètre : le type d’intégration nécessaire (par exemple la saisie de commande) et les fonctionnalités attendues. Voir Documentation associée à la fin de cet article.
- Exigences spécifiques : toute exigence fonctionnelle spécifique.
-
Attendre qu’un responsable de la mise en œuvre des intégrations (IDM) prenne contact. Qargo délivre ensuite l’ID d’intégrateur.
Étape 2 : ajouter un client API pour le rôle requis
- Aller dans Configuration > Paramètres de l’organisation > Utilisateurs et faire défiler jusqu’en bas de la page.
- Cliquer sur « Ajouter un client API ».

-
Sélectionner le rôle nécessaire :
- Comptabilité : pour comptabiliser des factures, voir API comptable et entités de facturation ci-dessous
- Client : utilisé lorsqu’un client du compte souhaite se connecter via l’API
- Gestion des données de référence
- Gestion des commandes
Étape 3 : compléter les informations du client API

-
ID d’intégrateur : toujours obligatoire. Saisir l’ID reçu de Qargo.
-
Entreprise : obligatoire uniquement pour le rôle Client.

‼️ Étape 4 : copier le secret avant d’enregistrer‼️

Étape 5 : partager les identifiants de façon sécurisée
Partager l’ID client et le secret de façon sécurisée avec la partie qui développe l’intégration.
Étape 6 : informer Qargo
Informer Qargo une fois les clients API configurés. Une configuration supplémentaire au niveau du compte peut être nécessaire avant le début des tests, par exemple le mappage d’importation de commande pour l’API des commandes, ou la configuration de l’API comptable.
Tester l’API des commandes
Le plus simple pour commencer est de créer manuellement dans Qargo quelques commandes de test typiques, puis de les utiliser comme modèle pour construire les requêtes API.
Obtenir un modèle avec Order Export
-
Ouvrir une commande de test dans Qargo et copier l’order_id depuis l’URL (la partie située après orders/).
-
Appeler le point de terminaison Order Export :
GET<https://api.qargo.com/v1/orders/order/{order_id}/export> -
Examiner les données renvoyées. La comparaison d’une vraie commande Qargo avec sa structure de données montre comment compléter chaque champ.

Créer une nouvelle commande
- Retirer les champs générés automatiquement, comme les codes-barres.
- Inclure le code de configuration d’importation (par défaut : API).
- Modifier les identifiants uniques, comme le numéro de référence client et l’order_identifier.
- Téléverser la commande POST <https://api.qargo.com/v1/orders/order/upload>
La commande apparaît ensuite dans l’onglet Commandes ou dans l’onglet Importations de commandes, selon la configuration de l’importation de commande.

Configuration de l’importation de commande
La configuration de l’importation de commande est définie au niveau du compte et ne peut être modifiée que par Qargo. Ces paramètres déterminent le comportement des commandes reçues via l’API.
| Paramètre | Effet |
|---|---|
| Créer automatiquement les commandes | Envoie les commandes importées directement dans l’onglet Commandes, ou dans l’onglet Importations de commandes, où elles doivent d’abord être confirmées. |
| Activer les mises à jour | Détermine si les mises à jour sont acceptées via l’API. |
| Activer la détection des doublons | Signale automatiquement les importations en double pour éviter qu’elles soient importées deux fois. |
| Appliquer les modifications automatiquement | Applique les modifications sans contrôle manuel. Peut être limité à un statut de commande choisi, à partir duquel les mises à jour doivent de nouveau être approuvées manuellement. |
| Appliquer les annulations automatiquement | Fonctionne comme Appliquer les modifications automatiquement, mais pour les annulations. |
Vérifier qu’une importation de commande a réussi
Qargo vérifie une commande envoyée via l’API en deux étapes. La réussite de l’étape 1 ne signifie pas que la commande existe dans Qargo.
| Étape | Ce qui se passe | Où le résultat apparaît |
|---|---|---|
| 1. Contrôle API | Qargo vérifie que le message est correctement construit. | Dans la réponse de validation renvoyée au système externe. |
| 2. Importation Qargo | Qargo applique les données au compte. La commande est créée ou mise à jour. Cette étape s’exécute après l’étape 1, en arrière-plan. | Dans le statut d’importation et sur la commande dans Qargo. |
Ce que le contrôle API confirme
- Le message suit la structure attendue (JSON ou XML).
- Les champs obligatoires sont présents, avec les bons types de données et les bons formats.
- Les valeurs, comme les unités et les types de commande, sont autorisées.
Ce que le contrôle API ne confirme pas
- Les clients, emplacements, produits et ressources de la commande existent dans le compte Qargo.
- Les règles métier et la configuration du compte permettent de créer ou de modifier la commande.
- La référence de la commande correspond correctement, de sorte que Qargo crée une nouvelle commande ou met à jour la bonne commande existante.
- Une commande existante est toujours dans un statut qui autorise les modifications.
Une importation Qargo peut échouer ou être rejetée même si le contrôle API a réussi.
Confirmer qu’une importation a réussi
- Ne pas considérer un contrôle API positif comme la confirmation que la commande existe.
- Vérifier le statut d’importation de la commande. Un statut error signifie que l’importation Qargo a échoué. Une correction manuelle dans Qargo est alors nécessaire.
- Ouvrir l’onglet Importations de commandes, ou la commande dans Qargo, pour examiner le résultat.
- Envoyer à l’assistance Qargo la référence de la commande, l’horodatage et le message d’erreur si l’importation échoue toujours.
Exemples : résultats du contrôle API et de l’importation Qargo
Échec API (= échec de la validation API)

Succès API

Erreur d’upsert du statut API (= échec de l’importation dans l’interface)

Écran d’erreur d’importation de commande (= échec de l’importation dans l’interface)

Correction de l’importation de commande (interface)

Correction de l’importation de commande (API)

API comptable et entités de facturation
L’API comptable prend en charge plusieurs entités de facturation. Elle offre ainsi une sécurité et un contrôle d’accès renforcés aux groupes qui facturent depuis plusieurs entreprises.
Ce qui est inclus
- Entité de facturation sur les factures : les points de terminaison des factures comportent une section billing_entity qui indique à quelle entité appartient une facture.
- Intégrations multiples : plusieurs intégrations API comptables peuvent être créées, chacune liée à une entité de facturation.
- Filtrage : les factures et les tâches peuvent être filtrées par entité de facturation.
- Clients API dédiés : les clients de l’API comptable sont créés dans la page de paramètres Intégration API comptable. Ces clients API sont nécessaires pour bénéficier de toutes les fonctionnalités.

Impact sur les intégrations externes
-
Comptabilisation restreinte : un intégrateur ne peut terminer (comptabiliser) que les factures de l’entité de facturation liée à ses identifiants.
-
Consultation : les factures des autres entités de facturation restent visibles, dans la limite des droits de consultation habituels, mais ne peuvent pas être comptabilisées.
-
L’endroit où les identifiants sont créés est important :
- Pour comptabiliser des factures (passer le statut à terminé), les identifiants doivent être créés dans la page de paramètres Intégration API comptable et liés à la bonne entité de facturation.
- Les identifiants créés dans Paramètres de l’organisation ne peuvent pas passer une facture au statut terminé, ni lister les factures en attente de synchronisation.
Dépannage
| Problème | Solution |
|---|---|
| Les commandes de test n’apparaissent pas dans l’onglet Commandes | Lorsque Créer automatiquement les commandes est désactivé, les importations arrivent dans l’onglet Importations de commandes et doivent y être confirmées. |
| Le contrôle API a réussi, mais la commande n’est pas dans Qargo | L’importation Qargo a peut-être échoué. Vérifier le statut d’importation et l’onglet Importations de commandes. Voir Vérifier qu’une importation de commande a réussi. |
| Le contrôle API a réussi, mais la commande n’est pas dans Qargo | L’importation Qargo a peut-être échoué. Vérifier le statut d’importation et l’onglet Importations de commandes. Voir Vérifier qu’une importation de commande a réussi. |
| Une commande importée via l’API affiche une erreur dans Qargo | Les erreurs qui ne bloquent pas l’API arrivent dans l’onglet Importations de commandes. Un utilisateur clé ou un admin peut les y examiner et les corriger. Un statut d’importation en erreur signifie que l’importation Qargo a échoué et qu’une correction manuelle est nécessaire. |
| Le secret a été perdu après la fermeture de l’écran | Le secret ne peut pas être récupéré. Créer un nouveau client API et copier le secret avant d’enregistrer. |
| Impossible de créer un client API pour le rôle Client | Activer d’abord l’Accès au portail client pour ce client. |
| Un client API Comptabilité ne peut pas comptabiliser de factures | Créer le client API dans Accounting API Integration settings et le lier à la bonne entité de facturation. Les clients API créés dans Organisation settings ne peuvent pas comptabiliser. |
| Un intégrateur ne peut pas comptabiliser certaines factures | Ces factures appartiennent à une autre entité de facturation. Utiliser des identifiants liés à cette entité de facturation. |
| Des commandes en double continuent d’être importées | Demander à Qargo d’activer Activer la détection des doublons. |
| Les mises à jour de l’API client ne sont pas appliquées automatiquement | C’est le comportement attendu. Les mises à jour des clients suivent les règles du portail client et doivent être approuvées dans l’écran d’importation de commande. |
FAQ
Q. Qargo propose-t-il une API ?
R. Oui ! Qargo propose des API pour la saisie de commande et les statuts, l’exécution des tournées, la synchronisation des données de référence et la comptabilité, pour les types d’intégration Tenant, Client et Sous-traitant.
Q. Une connexion API peut-elle être configurée sans Qargo ?
R. Non. La configuration d’une intégration nécessite des droits super admin et l’assistance de l’équipe Qargo. Commencer par envoyer un e-mail à success@qargo.com.
Q. Une seule intégration comptable peut-elle comptabiliser les factures de toutes les entités de facturation ?
R. Non. Chaque client de l’API comptable ne peut comptabiliser que les factures de l’entité de facturation à laquelle il est lié. Les factures des autres entités restent visibles mais ne peuvent pas être comptabilisées.
Documentation associée
Documentation de référence de l’API (api.qargo.com)
