---
title: "Intégrations : API Qargo – quoi, pourquoi et comment"
description: "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."
url: https://help.qargo.com/fr/articles/865547-integrations-api-qargo-quoi-pourquoi-et-comment
locale: fr
updated: 2026-11-03
---

# Intégrations : API Qargo – quoi, pourquoi et comment

:::callout{tone="info"}
💬 Envoyer un e-mail à [success@qargo.com](mailto:success@qargo.com) pour lancer une demande d'intégration ou pour activer une configuration préalable.
:::

## Introduction {#h_ac41125bec}

**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 {#h_dbbc5364d0}

-   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 {#h_5966c3f172}

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 {#h_664a4407e6}

-   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 {#h_ef2b99bccb}

| **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 {#h_dacd260685}

### Étape 1 : demander l'intégration et un ID d'intégrateur {#h_7a4480cad0}

1.  **Envoyer un e-mail** à [success@qargo.com](mailto:success@qargo.com) pour lancer la demande d'intégration.
2.  **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.
3.  **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 {#h_e9b1ab14b3}

1.  **Aller** dans **Configuration > Paramètres de l'organisation > Utilisateurs** et faire défiler jusqu'en bas de la page.
2.  **Cliquer** sur **« Ajouter un client API »**.

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

1.  **Sélectionner** le rôle nécessaire :

    -   [Comptabilité](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Accounting) : pour comptabiliser des factures, voir _[API comptable et entités de facturation](#h_8268f9d1d9)_ ci-dessous
    -   [Client](https://api.qargo.com/customer21704fc3a2dc66a58d59414b/docs) : utilisé lorsqu'un client du compte souhaite se connecter via l'API
    -   [Gestion des données de référence](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Master-data-sync)
    -   [Gestion des commandes](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Order)

### Étape 3 : compléter les informations du client API {#h_0d48e98b07}

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

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

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


:::callout{tone="info"}
🧰 Pour le rôle **Client**, l'**Accès au portail client** doit être activé pour le client concerné avant de pouvoir créer un client API.
:::

### ‼️ Étape 4 : copier le secret avant d'enregistrer‼️ {#h_5d8948d080}

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

:::callout{tone="warning"}
‼️ **Le _secret_ n'est affiché qu'une seule fois.** Le copier dans un endroit sûr avant de cliquer sur **Enregistrer** et de fermer l'écran **Ajouter un client API**. Il ne peut plus être consulté ensuite, et un nouveau client API devrait alors être créé.
:::

### Étape 5 : partager les identifiants de façon sécurisée {#h_f2132d724b}

**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 {#h_293f38389d}

**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 {#h_b17ab36a5e}

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 {#h_668cb7e95e}

1.  **Ouvrir** une commande de test dans Qargo et copier l'_order\_id_ depuis l'URL (la partie située après _orders/_).
2.  **Appeler** le point de terminaison _Order Export_ :\
    _GET\<[https://api.qargo.com/v1/orders/order/{order\_id}/export](https://api.qargo.com/v1/orders/order/%7Border_id%7D/export)\>_

3.  **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.

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

### Créer une nouvelle commande {#h_50d96770f0}

1.  **Retirer** les champs générés automatiquement, comme les codes-barres.
2.  **Inclure** le code de configuration d'importation (par défaut : _API_).
3.  **Modifier** les identifiants uniques, comme le numéro de référence client et l'_order\_identifier_.
4.  **Téléverser** la commande **POST \<[https://api.qargo.com/v1/orders/order/upload](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.

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

* * *

## Configuration de l'importation de commande {#h_8f2bedce55}

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.

:::callout{tone="info"}
📚 Pour plus de détails sur le mappage et les erreurs, voir [Intégrations : importer des commandes dans Qargo](https://help.qargo.com/fr/articles/450378-integrations-importing-orders-into-qargo).
:::

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

:::callout{tone="info"}
📚 Pendant les tests, **Créer automatiquement les commandes** est souvent désactivé. Les commandes de test API restent ainsi séparées des commandes créées manuellement par les autres équipes.

📚 Les commandes qui passent le contrôle API mais échouent dans Qargo arrivent toujours dans l'onglet **Importations de commandes**, où un utilisateur clé ou un admin peut examiner et corriger l'erreur.

📚 **Exemple :** de nombreuses entreprises acceptent les mises à jour automatiquement jusqu'à ce qu'une commande soit planifiée. Pour configurer ce fonctionnement, activer **Appliquer les modifications automatiquement** et le désactiver à partir du statut **Planifié**.

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

:::callout{tone="note"}
‼️ **Exception de l'API client.** Pour le rôle **Client**, les mises à jour et les annulations suivent les règles du portail client, et non la configuration de l'importation de commande. Si les clients ne peuvent pas modifier les commandes dans le portail client, ils ne peuvent pas non plus les modifier automatiquement via l'API. Les mises à jour peuvent tout de même être envoyées, mais chacune doit être approuvée dans l'écran d'importation de commande.
:::

* * *

## Vérifier qu'une importation de commande a réussi {#h_0cf7fd7820}

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 {#h_0fb2e846b9}

-   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 {#h_a8ead373e6}

-   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 {#h_754ec40674}

1.  **Ne pas** considérer un contrôle API positif comme la confirmation que la commande existe.
2.  **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.
3.  **Ouvrir** l'onglet **Importations de commandes**, ou la commande dans Qargo, pour examiner le résultat.
4.  **Envoyer** à l'assistance Qargo la référence de la commande, l'horodatage et le message d'erreur si l'importation échoue toujours.

:::callout{tone="note"}
📚 Le _contrôle API_ et l'_importation Qargo_ sont deux étapes distinctes. Une même commande peut réussir la première et échouer à la seconde.
:::

#### Exemples : résultats du contrôle API et de l'importation Qargo {#h_c4e435ac7f}

##### Échec API (= échec de la validation API) {#h_c093b0fa78}

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

##### Succès API {#h_7c0daf9eb8}

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

##### Erreur d'upsert du statut API (= échec de l'importation dans l'interface) {#h_eb776ba8b1}

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

##### Écran d'erreur d'importation de commande (= échec de l'importation dans l'interface) {#h_29828d88b6}

![](https://help.qargo.com/media/970394050278-order-imports-list-green.png)

##### Correction de l'importation de commande (interface) {#h_47c23c97a3}

![](https://help.qargo.com/media/f547d77c2c75-fix-order-data-form-green.png)

##### Correction de l'importation de commande (API) {#h_9219b01e67}

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

* * *

## API comptable et entités de facturation {#h_8268f9d1d9}

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 {#h_eb25d542bf}

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

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

### Impact sur les intégrations externes {#h_666d05b4a7}

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

:::callout{tone="note"}
‼️ Les clients API Comptabilité créés dans _Paramètres de l'organisation_ ne peuvent pas comptabiliser de factures. Toujours créer les clients API qui comptabilisent des factures dans la page de paramètres _Intégration API comptable_.

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

* * *

## Dépannage {#h_e26ff07754}

| **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 {#h_07de834c15}

**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](mailto: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 {#h_cc6c5591eb}

**Documentation de référence de l'API ([api.qargo.com](http://api.qargo.com))**

-   [API Qargo TMS – Tenant : commandes](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Order)
-   [API Qargo TMS – Spécification client](https://api.qargo.com/customer21704fc3a2dc66a58d59414b/docs)
-   [API Qargo TMS – Spécification sous-traitant](https://api.qargo.com/dispatch164648e0838e990ed2d2b195/docs)
-   [API Qargo TMS – Synchronisation des données de référence](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Master-data-sync)
-   [API Qargo TMS – Comptabilité](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Accounting)


## Articles connexes

- [FAQ : Qu'est-ce que la prise en charge des entités de facturation dans l'API de comptabilité et quel est son impact sur les intégrations externes ?](https://help.qargo.com/fr/articles/482772-faq-qu-est-ce-que-la-prise-en-charge-des-entites-de-facturation-dans-l-api.md)
- [INTÉGRATIONS - Connecter un assistant IA à Qargo via MCP - Guide pas à pas](https://help.qargo.com/fr/articles/799560-integrations-connecter-un-assistant-ia-a-qargo-via-mcp-guide-pas-a-pas.md)
- [INTÉGRATIONS - Claude : se connecter à Qargo via MCP - Procédure](https://help.qargo.com/fr/articles/799799-integrations-claude-se-connecter-a-qargo-via-mcp-procedure.md)
- [FAQ – API Qargo : options disponibles](https://help.qargo.com/fr/articles/320484-faq-api-qargo-options-disponibles.md)
- [Intégrations : quoi, pourquoi et comment](https://help.qargo.com/fr/articles/348704-integrations-quoi-pourquoi-et-comment.md)
