Connecter Xero : recevoir commandes, clients, factures et produits, consulter le stock
Terminez le flux OAuth2 de votre application sur developer.xero.com avec les trois scopes de lecture, copiez le Tenant ID depuis la liste des connexions, collez les deux valeurs dans Integration, testez, mappez, activez.
Le connecteur Xero importe les commandes, clients, factures et produits de votre organisation Xero dans ce système, peut renvoyer clients, produits et factures vers Xero et peut consulter les quantités de stock via les Items de Xero. Il ne renvoie pas les changements de stock vers Xero : dans cette connexion, le stock est en lecture seule. Une connexion correspond à une organisation Xero, identifiée par son Tenant ID.
Prérequis#
- Une organisation Xero à laquelle vous pouvez vous connecter, et une application enregistrée pour elle sur developer.xero.com.
- Vous pouvez terminer le flux OAuth2 de cette application sur developer.xero.com et accorder les trois scopes de lecture : accounting.transactions.read, accounting.contacts.read et accounting.settings.read. Un token auquel il manque l’un d’eux échouera au test ou aux extractions.
- Vous savez pour quelle organisation est la connexion. Le Tenant ID est l’ID de l’organisation, pas l’ID de l’application : ce sont deux valeurs différentes, non interchangeables.
Obtenir les identifiants#
- Allez sur developer.xero.com, ouvrez votre application et terminez le flux OAuth2. Quand Xero demande les scopes, incluez au moins accounting.transactions.read, accounting.contacts.read et accounting.settings.read.
- Copiez l’access token renvoyé par le flux OAuth2. C’est ce token que vous collez dans Integration : il n’y a pas d’API key séparée à créer pour cette connexion.
- Obtenez le Tenant ID de votre organisation de l’une de ces deux façons : appelez GET https://api.xero.com/connections avec l’access token et copiez le tenantId de votre organisation dans la réponse ; ou ouvrez developer.xero.com → votre application → connections et lisez le tenantId affiché.
Remplir dans Integration#
- Ouvrez Integration → Marketplace → Xero → Nouvelle connexion.
- tenant_id, obligatoire, Tenant ID (Organisation) : collez le tenantId de votre organisation, sous la forme xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. C’est l’ID de l’organisation issu de la liste des connexions, pas l’ID de l’application.
- access_token, obligatoire, Access token : collez en entier l’access token renvoyé par le flux OAuth2. C’est un champ de type mot de passe, conservé comme secret. Vérifiez que le token a été accordé avec accounting.transactions.read, accounting.contacts.read et accounting.settings.read.
Tester la connexion#
Cliquez sur Tester la connexion. Le test envoie une vraie requête à GET https://api.xero.com/api.xro/2.0/Organisation avec deux en-têtes : Authorization: Bearer suivi de votre access token, et xero-tenant-id avec votre tenant_id. Une réponse 200 compte comme un succès, et le résultat affiche le nom de l’organisation renvoyé par Xero, pour confirmer que c’est bien l’organisation visée. Un 401 signifie que le token est invalide ou expiré ; un 403 signifie que le token n’a pas un scope suffisant. Si tenant_id ou access_token manque, le test s’arrête avant tout envoi, car les deux valeurs sont nécessaires pour cette sonde. La sonde expire après 12 secondes.
Mapping / choisir un modèle#
Choisissez le mapping standard Xero. Commandes, clients et factures suivent les enregistrements standard de Xero Accounting, et produits et consultations de stock suivent les Items de Xero. Après un test réussi, lancez une extraction et comparez une commande réelle côte à côte (numéro, client, lignes et montants), vérifiez une facture et un produit de la même façon, et comparez la quantité d’un item avec ce qu’affiche Xero, avant d’activer.
Activer#
Après activation, la connexion importe commandes, clients, factures et produits depuis l’organisation Xero désignée par votre tenant_id selon la fréquence définie, renvoie clients, produits et factures vers Xero quand ces flux s’exécutent, et lit les quantités de stock dans les Items de Xero lors des consultations de stock. Surveillez les premières exécutions dans Runs / Logs et comparez-les avec Xero avant de laisser la connexion sans surveillance.
Ce que cette connexion ne fait pas : elle ne renvoie pas les changements de stock vers Xero. Les quantités des Items de Xero sont lues pour consultation uniquement, donc les ajustements de stock doivent toujours être faits dans Xero même ou dans le système où l’ajustement a réellement lieu.
FAQ#
Le test échoue avec 401 — token invalide ou expiré
Xero a refusé l’access token lui-même : il est incorrect, incomplet ou n’est plus valide. Dans ce cas, la sonde d’organisation ne passe même pas l’authentification, donc le tenant_id n’est pas la première chose à vérifier.
Retournez sur developer.xero.com → votre application, refaites le flux OAuth2, copiez le nouvel access token en entier dans le champ access_token, puis retestez.
Le test échoue avec 403 — scope insuffisant
Le token a été accepté, mais il n’a pas reçu les scopes de lecture dont cette connexion a besoin. Les trois requis sont accounting.transactions.read, accounting.contacts.read et accounting.settings.read : l’absence de l’un d’eux peut produire ce résultat.
Refaites le flux OAuth2 sur developer.xero.com pour votre application et accordez cette fois les trois scopes, collez le nouvel access token dans Integration, puis retestez. Ne recollez pas simplement l’ancien token : ses scopes ne changent pas.
Le token est correct, mais le test échoue toujours — mauvaise organisation
Le tenant_id n’appartient pas à l’organisation pour laquelle le token a été autorisé. La sonde envoie votre tenant_id dans l’en-tête xero-tenant-id et Xero répond pour cette organisation uniquement : un token valide associé à l’ID d’une autre organisation échoue ici, et le nom de l’organisation dans un résultat réussi est le contrôle que vous avez choisi la bonne.
Recopiez le tenantId de l’organisation visée : appelez GET https://api.xero.com/connections avec l’access token et choisissez le tenantId de cette organisation dans la réponse, ou lisez-le sous developer.xero.com → votre application → connections. Remplacez tenant_id, enregistrez et retestez — puis confirmez que le nom d’organisation affiché correspond.
Le test s’arrête avant l’envoi — une valeur obligatoire manque
tenant_id ou access_token est vide. La sonde d’organisation a besoin des deux : le token pour l’en-tête Authorization et le tenant_id pour l’en-tête xero-tenant-id, donc le test s’arrête au lieu d’envoyer une requête qui ne peut pas réussir.
Remplissez les deux champs selon l’étape de saisie dans Integration — tenant_id depuis la liste des connexions et access_token collé en entier — enregistrez, puis retestez.
Connecté, mais les quantités de stock ne changent jamais dans Xero
C’est la limite de cette connexion, pas un échec : le stock est lu depuis les Items de Xero pour consultation, et les changements de stock ne sont pas renvoyés vers Xero. Commandes, clients, factures et produits circulent comme décrit ci-dessus ; les niveaux de stock dans Xero restent sous le contrôle de Xero.
Faites les ajustements de stock dans Xero même, ou dans le système où l’ajustement a réellement lieu, et utilisez la consultation de stock de cette connexion pour vérifier les quantités ensuite.
Le test expire après 12 secondes
La sonde d’organisation n’a pas reçu de réponse de Xero à temps. C’est un problème d’accès ou de réponse sur le chemin vers api.xero.com, pas un verdict sur votre token ou votre tenant_id : aucune des deux valeurs n’a réellement été jugée.
Attendez un moment et relancez Tester la connexion avec les mêmes deux valeurs. Si les expirations se répètent alors que d’autres connexions se testent bien, notez l’heure et le message exact de Runs / Logs avant de changer une valeur.