Connecter ReturnGO : importer les RMA via l’API, avec étiquettes de retour

Générez une API key dans le dashboard ReturnGO sous Settings → API, copiez l’URL du serveur API depuis la section Servers de la documentation officielle de l’API, saisissez la clé, le domaine de la boutique et l’URL du serveur dans Integration, réussissez un test réel en lecture seule, puis activez.

Le connecteur ReturnGO importe les retours (RMA) de ReturnGO dans le système de retours (RMS) via l’API ReturnGO : il lit la liste des RMA et les détails de chaque RMA, et cette connexion prend en charge les étiquettes de retour. Elle fonctionne par extraction API selon un programme — il n’y a pas de webhook sur cette connexion, donc un nouveau retour dans ReturnGO apparaît ici à la prochaine extraction, pas à l’instant où il est créé. La connexion a quatre champs : une API key, le domaine de votre boutique, l’URL du serveur API que vous copiez depuis la documentation officielle de l’API, et un nom d’en-tête facultatif.

Prérequis#

• Un compte ReturnGO auquel vous pouvez vous connecter, avec accès à la page Settings → API du dashboard.
• Vous connaissez le domaine de la boutique enregistré dans ReturnGO pour la boutique que vous connectez — un domaine comme demo-store.myshopify.com, et non le nom d’affichage de la boutique que voient les acheteurs.
• Vous pouvez ouvrir la documentation officielle de l’API ReturnGO et trouver la section Servers — l’URL du serveur API de cette connexion se copie depuis là, par vous ; il n’y a pas de valeur par défaut intégrée sur laquelle se rabattre.
• Une API key ReturnGO peut gérer plusieurs boutiques, donc gardez la trace de la boutique de chaque connexion — le champ de domaine de la boutique est ce qui dit à cette connexion de quelle boutique elle extrait.

Obtenir les identifiants#

1. Connectez-vous au dashboard ReturnGO et ouvrez Settings → API.
2. Générez-y une API key et copiez-la en entier. Une clé peut gérer plusieurs boutiques, donc la même clé peut servir pour plus d’une connexion de boutique.
3. Notez le domaine de la boutique exactement comme il est enregistré dans ReturnGO, par ex. demo-store.myshopify.com. Pendant les requêtes, cette valeur est envoyée dans l’en-tête x-shop-name, donc copiez le domaine lui-même, pas un nom d’affichage.
4. Ouvrez la documentation officielle de l’API ReturnGO, trouvez la section Servers et copiez l’adresse du serveur API qui y est affichée. Cette adresse est obligatoire et doit venir de cette section — n’en devinez pas une et ne réutilisez pas une adresse d’un autre document.
5. Uniquement si ReturnGO vous a donné un autre nom d’en-tête d’API key pendant la mise en place, notez aussi ce nom. Dans la plupart des cas, le nom d’en-tête est x-api-key et il n’y a rien de plus à recueillir.

Remplir dans Integration#

1. Ouvrez Integration → Marketplace → ReturnGO → Nouvelle connexion.
2. api_key, obligatoire, ReturnGO API Key : collez la clé générée dans ReturnGO dashboard → Settings → API, en entier. C’est un champ de type mot de passe, conservé comme secret.
3. shop_name, obligatoire, domaine de la boutique : saisissez le domaine de la boutique enregistré dans ReturnGO, par ex. demo-store.myshopify.com. Saisissez le domaine lui-même, pas le nom d’affichage de la boutique — les requêtes transportent cette valeur dans l’en-tête x-shop-name.
4. base_url, obligatoire, URL du serveur API : collez l’adresse du serveur API copiée depuis la section Servers de la documentation officielle de l’API ReturnGO, sous la forme https://… exactement comme elle y est affichée. Ce champ n’a pas de valeur par défaut : s’il reste vide, le test s’arrête avant tout envoi.
5. api_key_header, facultatif, nom d’en-tête de l’API key : laissez-le à x-api-key dans le cas normal. Ne le remplissez que lorsque ReturnGO vous a donné un autre nom d’en-tête pendant la mise en place, et saisissez alors ce nom exactement.

Tester la connexion#

Cliquez sur Tester la connexion. Avec les identifiants saisis, le test exécute une sonde réelle en lecture seule : il envoie GET {base_url}/rmas?pagesize=1 à l’adresse du serveur API que vous avez saisie, en transportant votre API key dans son en-tête (x-api-key par défaut, ou le nom d’en-tête que vous avez saisi) et votre domaine de boutique dans l’en-tête x-shop-name, et il laisse 12 secondes pour la réponse. Une réponse réussie — le message de sonde réussie pour GET /rmas — compte comme un succès, car la sonde prouve que l’adresse du serveur répond, que la clé est acceptée et que le domaine de la boutique est reconnu, sans rien modifier. Si base_url manque, le test s’arrête avec MISSING_BASE_URL et n’envoie aucune requête ; si la clé ou le domaine de la boutique manque, il échoue ouvertement sur l’identifiant manquant au lieu d’annoncer un faux succès. Si vous testez sans aucun identifiant saisi, le résultat est un contrôle simulé uniquement et il est étiqueté comme simulé — saisissez les trois champs obligatoires et retestez pour la vraie sonde.

Mapping / choisir un modèle#

Choisissez le mapping standard ReturnGO. Il travaille avec ce que l’API renvoie : la liste des RMA et les détails de chaque RMA deviennent des enregistrements de retour ici, et une extraction peut être restreinte par numéro de commande quand vous cherchez un retour. Après un test réussi, lancez une extraction et comparez un vrai RMA côte à côte avec ReturnGO — référence de RMA, référence de commande, articles et quantités — et vérifiez le flux d’étiquette de retour pour ce retour, avant d’activer. Si un champ de ReturnGO diffère de ce que vous attendez, ajustez ce champ dans le mapping plutôt que de changer quoi que ce soit dans ReturnGO.

Activer#

Après activation, la connexion importe les RMA de ReturnGO dans le système de retours selon la fréquence définie — liste et détails ensemble — et l’entrepôt traite ces retours ici, avec des étiquettes de retour prises en charge par cette connexion. Surveillez les premières extractions dans Runs / Logs et comparez-les avec ReturnGO avant de laisser la connexion sans surveillance.

Ce que cette connexion ne fait pas : elle ne reçoit pas les retours par webhook, donc un retour créé dans ReturnGO n’est pas poussé ici à l’instant où il se produit — il arrive à la prochaine extraction programmée. Si un retour est urgent, lancez une extraction manuelle pour lui, restreinte par son numéro de commande, au lieu d’attendre le programme.

FAQ#

Le test s’arrête avec MISSING_BASE_URL

Le champ base_url est vide. Cette connexion n’a pas d’adresse de serveur intégrée : la sonde a besoin de l’URL du serveur API pour savoir où envoyer GET /rmas, donc sans adresse elle s’arrête avant tout envoi et signale MISSING_BASE_URL.

Ouvrez la documentation officielle de l’API ReturnGO, copiez l’adresse du serveur depuis la section Servers exactement comme elle est affichée, collez-la dans base_url sous la forme https://…, enregistrez et retestez.

La sonde échoue alors que l’API key est correcte

La sonde vérifie plus que la clé : elle envoie aussi votre domaine de boutique dans l’en-tête x-shop-name et communique avec l’adresse de base_url. La cause habituelle est shop_name : il contient un nom d’affichage de la boutique au lieu du domaine enregistré, donc ReturnGO ne reconnaît pas la boutique même si la clé elle-même est valide. Une base_url copiée au mauvais endroit échoue de la même façon.

Mettez shop_name au domaine enregistré dans ReturnGO, sous la forme demo-store.myshopify.com, et recopiez base_url depuis la section Servers de la documentation officielle de l’API. Gardez la clé telle quelle, enregistrez et retestez.

Dois-je remplir api_key_header ?

Dans la plupart des cas, non. L’en-tête qui transporte votre API key est x-api-key par défaut, et ce défaut est déjà celui que la connexion utilise. Le champ n’existe que pour les boutiques auxquelles ReturnGO a donné un autre nom d’en-tête pendant la mise en place — saisir un nom inventé, ou le changer sans y être invité, fait paraître cassée une clé qui fonctionne.

Laissez api_key_header à x-api-key, sauf si ReturnGO vous a donné un autre nom par écrit pendant la mise en place. Si c’est le cas, saisissez ce nom exact ; si vous l’avez changé pendant le dépannage, remettez-le à x-api-key et retestez.

Le test a réussi sans identifiants saisis — suis-je connecté ?

Non. Sans aucun identifiant, le test exécute seulement un contrôle simulé et étiquette le résultat comme simulé. Il n’atteint jamais ReturnGO, donc il ne prouve rien sur votre clé, votre domaine de boutique ni votre adresse de serveur.

Saisissez les trois champs obligatoires — api_key depuis Settings → API, shop_name comme le domaine enregistré et base_url copiée depuis la section Servers de la documentation officielle de l’API — enregistrez et retestez. Seul le résultat de la sonde GET /rmas compte comme un vrai succès.

Connecté, mais un nouveau retour dans ReturnGO n’apparaît pas ici

Cette connexion extrait via l’API selon un programme et n’a pas de webhook, donc un retour créé il y a une minute attend correctement la prochaine extraction. L’autre cause fréquente est la boutique : une API key peut gérer plusieurs boutiques et cette connexion n’extrait que la boutique nommée par son domaine shop_name — un retour créé dans une autre boutique sous la même clé n’apparaîtra pas ici.

Confirmez que le retour appartient à la boutique dont le domaine est dans shop_name, lancez une extraction manuelle — restreinte par le numéro de commande si vous cherchez ce retour — et vérifiez Runs / Logs. S’il arrive avec l’extraction manuelle, la connexion va bien et l’extraction programmée apportera les suivants.

La sonde expire sans réponse

La sonde attend 12 secondes que le serveur de base_url réponde à GET /rmas, et rien n’est revenu dans ce délai. Cela désigne l’adresse elle-même : une URL de serveur copiée depuis la mauvaise section, saisie avec un morceau en trop ou en moins, ou pour un environnement différent de celui de votre boutique ne répondra pas à cette sonde de boutique.

Recopiez base_url depuis la section Servers de la documentation officielle de l’API ReturnGO, collez-la exactement comme elle est affichée, sans rien ajouter ni retirer, enregistrez et retestez. Ne changez ni la clé ni le domaine de la boutique pendant que vous corrigez l’adresse — changez une valeur à la fois.