Connecter Sage X3 : vérifier la connectivité Sync API de votre folder

Réunissez les sept valeurs remises lors de l’onboarding du tenant (environnement, URL de base Sync API, folder, clé API du tenant et le couple OAuth d’identité Sage), saisissez-les dans Integration puis testez : le test échange un token et sonde votre folder. Cette connexion vérifie uniquement la connectivité et ne synchronise ni commandes, ni stock, ni clients.

La connexion Sage X3 vérifie que ce système peut atteindre la Sync API d’un folder Sage X3 de votre tenant : elle échange un token d’identité Sage et lit une fois le flux de changements de ce folder. Gardez la portée en tête : vérifier la connectivité est tout ce que cette connexion fait aujourd’hui. Elle n’importe ni commandes, ni clients, ni stock, et ne renvoie pas de stock, car la Sync API est une interface générale de synchronisation au niveau des tables, et les noms de tables ainsi que le mapping des colonnes pour les commandes, le stock et les clients doivent être confirmés à partir des métadonnées de votre propre folder pour votre déploiement. Un test réussi prouve seulement que les sept valeurs ci-dessous fonctionnent ensemble pour ce folder, et rien de plus.

Prérequis#

• Un déploiement Sage X3 dont le tenant dispose de la Sync API, et un folder X3 à vérifier, par exemple SEED.
• Le pack d’onboarding du tenant de ce déploiement : l’URL de base Sync API, la clé API du tenant et le nom exact du folder. Les noms de folder sont sensibles à la casse, conservez donc l’orthographe exacte qui vous a été remise.
• Un couple d’identifiants client OAuth d’identité Sage (un client ID et un client secret) émis pour ce tenant, issu du même onboarding.
• Vous savez quel environnement vous connectez : production ou test. Le mot que vous saisissez décide quelle adresse de token Sage le test utilise.

Obtenir les identifiants#

1. Demandez à votre administrateur Sage X3, ou à l’équipe qui a fait l’onboarding de votre tenant, le pack d’onboarding de ce déploiement. Les sept valeurs de cette connexion viennent de cet onboarding : il n’y a aucune page d’inscription séparée dans ce guide, et aucune valeur ne doit être inventée ni empruntée à un autre tenant.
2. Dans le pack, notez l’URL de base Sync API de votre tenant, sous la forme https://tenant-host/syncapi, avec l’hôte de votre propre tenant.
3. Notez le nom du folder exactement comme il est écrit dans le pack, casse comprise — par exemple SEED. Le test interrogera ensuite ce folder sous ce nom exact.
4. Notez la clé API du tenant du pack et gardez-la secrète. Pendant le test, elle est envoyée comme en-tête X-API-KEY, avec le token.
5. Notez le client ID et le client secret OAuth d’identité Sage du même pack. Les deux forment un couple : ne mélangez pas le secret d’un couple avec l’ID d’un autre.
6. Vérifiez si le pack demande un token audience. Vous n’avez besoin de cette valeur que si vos documents d’onboarding l’exigent ; sinon, laissez-la vide lors de la saisie.

Remplir dans Integration#

1. Ouvrez Integration → Marketplace → Sage X3 → Nouvelle connexion.
2. environment, obligatoire, environnement : saisissez le mot littéral production pour votre tenant réel, ou test pour votre tenant de test. production utilise l’adresse de token Sage https://id.sage.com/oauth/token, et test utilise https://id-shadow.sage.com/oauth/token.
3. tenant_base_url, obligatoire, URL de base Sync API du tenant : collez l’URL de base Sync API remise lors de l’onboarding, par exemple https://tenant-host/syncapi, avec l’hôte de votre propre tenant.
4. folder, obligatoire, folder X3 : saisissez le nom du folder exactement comme il a été remis, par exemple SEED. Ce champ est sensible à la casse : ici, seed et SEED sont des noms différents.
5. tenant_api_key, obligatoire, clé API du tenant : collez la clé API du tenant du pack d’onboarding. C’est un champ de type mot de passe, conservé comme secret et envoyé comme en-tête X-API-KEY pendant le test.
6. client_id, obligatoire, OAuth client ID : collez le client ID du couple OAuth d’identité Sage du même pack. C’est un champ de type mot de passe, conservé comme secret.
7. client_secret, obligatoire, OAuth client secret : collez le client secret de ce même couple OAuth. C’est un champ de type mot de passe, conservé comme secret. L’ID et le secret doivent venir du même couple.
8. audience, facultatif, token audience : ne le remplissez que si les documents d’onboarding de votre tenant demandent expressément un token audience. Sinon, laissez-le vide : le test demandera le token sans audience.

Tester la connexion#

Cliquez sur Tester la connexion. Le test vérifie d’abord les cinq valeurs d’identifiants obligatoires et s’arrête avec un résultat nommé s’il en manque une : MISSING_TENANT_BASE_URL, MISSING_FOLDER, MISSING_TENANT_API_KEY, MISSING_CLIENT_ID ou MISSING_CLIENT_SECRET. Il exécute ensuite deux étapes réelles dans une limite partagée de 12 secondes. D’abord, il échange votre client_id et votre client_secret contre un token d’identité Sage à l’adresse que votre environment sélectionne, en ajoutant audience si vous l’avez rempli. Ensuite, il demande à la Sync API de votre tenant les changements de votre folder, en envoyant à la fois le token comme Authorization: Bearer et votre clé API du tenant comme X-API-KEY. Une réponse 200 réussit, et le résultat nomme le folder atteint. Un 401 est signalé comme INVALID_TOKEN, un 403 comme MISSING_SCOPE et un 404 comme NOT_FOUND : voir la FAQ pour la signification de chacun.

Mapping / choisir un modèle#

Pour cette connexion, il n’y a aucun mapping standard à configurer et aucun modèle à choisir. La Sync API travaille au niveau des tables, et les noms de tables et les colonnes pour les commandes, le stock et les clients diffèrent selon le folder : ils se confirment donc à partir des métadonnées de votre folder lorsqu’une connexion de données est préparée pour votre déploiement — ce n’est pas quelque chose à deviner ni à saisir ici. Tant que cette confirmation par déploiement n’existe pas pour votre folder, cette connexion en reste à la vérification de connectivité effectuée à l’étape de test. Ne renommez ni tables ni champs dans Sage X3 pour les adapter à un mapping deviné.

Activer#

Une fois le test réussi, activez la connexion pour l’enregistrer dans Integration avec ces valeurs vérifiées, afin que le même folder puisse être revérifié plus tard avec les mêmes identifiants. L’activation ne démarre aucun flux de données : via cette connexion, ni commandes, ni clients, ni stock ne circulent, dans aucun sens. Si votre onboarding émet plus tard une nouvelle clé API du tenant ou un nouveau couple OAuth, mettez à jour les champs ici et testez à nouveau avant de vous fier à la connexion.

FAQ#

Le test échoue avec INVALID_TOKEN (401)

Le côté token de la vérification a été refusé. Soit l’échange de token lui-même a rejeté votre couple client_id et client_secret, soit le token renvoyé n’a pas été accepté par la Sync API du tenant. Causes habituelles : une valeur copiée avec des espaces en trop, le secret d’un couple OAuth utilisé avec l’ID d’un autre, ou un mot d’environment qui envoie l’échange vers l’autre adresse de token Sage que celle pour laquelle le couple a été émis.

Recopiez client_id et client_secret depuis le même pack d’onboarding, sans espaces en trop, et confirmez que environment correspond au tenant pour lequel ce couple a été émis : production pour le tenant réel, test pour le tenant de test. Si vous avez rempli audience, retirez-le sauf si vos documents d’onboarding l’exigent, puis testez à nouveau.

Le test échoue avec MISSING_SCOPE (403)

Le token a été accepté, mais votre clé API du tenant n’a aucun droit sur le folder indiqué dans le champ folder. La requête a bien atteint la Sync API de votre tenant : c’est la clé elle-même qui limite, pas l’adresse ni le couple OAuth.

Demandez à votre administrateur Sage X3 d’accorder à cette clé API du tenant l’accès à ce folder, ou d’émettre une clé qui le couvre. Profitez-en pour confirmer le nom du folder, puis testez à nouveau avec la clé mise à jour.

Le test échoue avec NOT_FOUND (404)

Le folder indiqué dans le champ folder n’est pas activé pour la Sync API sur ce tenant, ou le nom ne correspond à aucun folder là-bas. Les noms de folder étant sensibles à la casse, même le bon nom avec une mauvaise casse est lu comme un autre folder.

Comparez la valeur de folder caractère par caractère avec le pack d’onboarding, majuscules comprises. Si l’orthographe est exacte, demandez à votre administrateur Sage X3 d’activer ce folder pour la Sync API, puis testez à nouveau.

Le test s’arrête avec MISSING_TENANT_BASE_URL, MISSING_FOLDER, MISSING_TENANT_API_KEY, MISSING_CLIENT_ID ou MISSING_CLIENT_SECRET

Le résultat nomme le champ exact qui est vide. Le test vérifie d’abord les champs et n’envoie rien tant que les cinq ne sont pas présents, car la sonde du folder a besoin du token et de la clé API ensemble.

Remplissez le champ nommé à partir de votre pack d’onboarding (URL de base, folder, clé API du tenant, OAuth client ID ou OAuth client secret), enregistrez, puis testez à nouveau. Répétez jusqu’à ce qu’aucun résultat de manque n’apparaisse.

J’ai saisi une adresse de serveur ou une URL complète dans environment et le test échoue

environment n’est pas un champ d’adresse. Il n’accepte que l’un de deux mots littéraux, et ce mot sélectionne quelle adresse de token Sage le test utilise. Tout autre contenu envoie l’échange de token au mauvais endroit, ou nulle part d’utilisable.

Remplacez la valeur d’environment par le seul mot production si cette connexion concerne votre tenant réel, ou test si elle concerne votre tenant de test. Mettez l’adresse du serveur dans tenant_base_url à la place, puis testez à nouveau.

Le test a réussi, mais ni commandes, ni stock, ni clients ne sont synchronisés

C’est la portée actuelle de cette connexion, pas une erreur dans vos valeurs. Le test prouve seulement que l’échange de token et la sonde du folder fonctionnent. Le transfert de données ne fait pas encore partie de cette connexion, car la Sync API est au niveau des tables, et les tables et colonnes de commandes, de stock et de clients de votre folder doivent d’abord être confirmées à partir des métadonnées de votre folder pour votre déploiement.

Considérez un test réussi comme une connexion vérifiée pour ce folder, et gardez pour l’instant le travail sur les commandes, le stock et les clients dans Sage X3 même. Lorsqu’une connexion de données sera préparée pour votre déploiement, elle partira de ces mêmes valeurs vérifiées : vous n’aurez pas à réunir les identifiants à nouveau.