Connecter Loop Returns : les retours arrivent par webhook, signalez-les et traitez-les en entrepôt

Créez une API key avec le scope returns dans Loop admin sous Returns Management → Tools & integrations → Developer Tools, saisissez cette unique clé dans Integration, comprenez pourquoi le test reste en attente de vérification, puis activez.

Le connecteur Loop Returns relie votre portail de retours Loop au système de retours (RMS). Les retours ne sont pas importés via l’API : ils arrivent par webhook lorsque les acheteurs les créent dans Loop. Une fois le retour entré, l’entrepôt le traite ici : signaler un retour et traiter un retour sont les deux actions de cette connexion. Elle ne crée pas d’étiquettes de retour. La connexion n’a qu’un seul champ, la Loop API Key.

Prérequis#

• Un compte Loop auquel vous pouvez vous connecter en tant qu’administrateur, avec accès à Returns Management → Tools & integrations → Developer Tools.
• Les retours se font d’abord dans Loop : les acheteurs démarrent le retour dans Loop et cette connexion le reçoit ; ce n’est pas un endroit pour créer un retour de toutes pièces.
• Comprenez la voie d’entrée avant de commencer : les retours arrivent uniquement par webhook, il n’y a pas d’extraction API programmée à attendre et cette connexion ne fournit pas d’étiquettes de retour.

Obtenir les identifiants#

1. Connectez-vous à Loop admin.
2. Allez dans Returns Management → Tools & integrations → Developer Tools.
3. Créez-y une nouvelle API key et assurez-vous d’inclure le scope returns. Le scope returns est une exigence stricte : sans lui, les actions de signalement et de traitement des retours échoueront ensuite.
4. Copiez la clé en entier. Quand ce système communique avec Loop, la clé est envoyée dans l’en-tête X-Authorization : vous ne saisissez cet en-tête nulle part, vous saisissez uniquement la clé.

Remplir dans Integration#

1. Ouvrez Integration → Marketplace → Loop Returns → Nouvelle connexion.
2. api_key, obligatoire, Loop API Key : collez la clé créée dans Loop admin → Returns Management → Tools & integrations → Developer Tools, en entier et avec le scope returns. C’est un champ de type mot de passe, conservé comme secret. Cette connexion n’a aucun autre champ : ni adresse de boutique, ni adresse de serveur, rien d’autre à saisir.
3. Enregistrez la connexion, puis lancez le test — et lisez d’abord la section suivante, car le résultat du test de ce canal ne ressemble pas à celui des autres.

Tester la connexion#

Cliquez sur Tester la connexion et attendez-vous à ce résultat : avec une vraie clé saisie, le test ne revient pas comme réussi — il revient comme non réussi, en attente de vérification, et il n’envoie aucune requête à Loop. C’est le comportement attendu pour ce canal, et non le signe que votre clé est fausse. La raison est simple : Loop n’a pas de contrôle en lecture seule vérifié capable de prouver que la clé fonctionne sans modifier de données. Les actions Loop connues, signaler et traiter, modifient un retour, donc elles ne peuvent pas servir de test sans danger, et le chemin de lecture des détails d’un retour n’a pas été confirmé depuis la documentation officielle. Le test vérifie donc seulement qu’une clé est présente, envoie zéro requête et signale une vérification en attente. Ne recréez pas des clés en boucle pour obtenir un résultat vert : une clé correcte avec le scope returns affiche exactement ce résultat. Si vous testez avec la clé laissée vide, le résultat est un contrôle simulé uniquement et il est étiqueté comme simulé ; il ne prouve rien sur un vrai compte Loop.

Mapping / choisir un modèle#

Choisissez le mapping standard Loop Returns. Il prend un retour arrivé par webhook et l’enregistre comme un retour dans le système de retours, avec sa référence de retour, sa référence de commande, ses articles et ses quantités tels qu’envoyés par Loop. Avant d’activer, faites passer un vrai retour : démarrez un retour dans Loop, laissez-le arriver et comparez le retour ici avec Loop côte à côte — référence, articles et quantités. Si quelque chose ne correspond pas, ajustez ce champ dans le mapping plutôt que de changer quoi que ce soit dans Loop.

Activer#

Après activation, les retours créés dans Loop arrivent par webhook et apparaissent comme des retours à traiter. L’entrepôt ouvre un retour ici, le signale quand il demande attention et le traite quand le retour est géré — ces deux actions sont envoyées à Loop pour ce retour. Surveillez les premiers retours réels dans Runs / Logs et comparez-les avec Loop avant de laisser la connexion sans surveillance.

Ce que cette connexion ne fait pas : elle n’importe pas les retours de Loop via l’API selon un programme, donc il n’y a pas de bouton de synchronisation à attendre ; et elle ne crée pas d’étiquettes de retour, donc les acheteurs continuent de recevoir leurs étiquettes comme Loop les fournit lui-même. Les retours démarrent dans Loop, arrivent par webhook et sont signalés et traités ici.

FAQ#

J’ai saisi une vraie clé, mais le test dit non réussi, en attente de vérification

C’est le résultat attendu pour Loop Returns, même avec une clé parfaite. Loop n’a pas de contrôle en lecture seule vérifié capable de prouver qu’une clé fonctionne sans modifier de données, donc le test n’envoie aucune requête et signale une vérification en attente. Le résultat vous dit qu’une clé est présente — il ne vous dit pas que la clé est fausse.

Arrêtez de recréer des clés. Confirmez que la clé enregistrée est celle créée dans Loop admin → Returns Management → Tools & integrations → Developer Tools avec le scope returns, puis continuez vers le mapping et l’activation, et jugez la connexion au premier vrai retour arrivé par webhook.

Le test semblait bon sans clé, mais rien de réel ne se passe

Avec la clé laissée vide, le test exécute seulement un contrôle simulé et étiquette le résultat comme simulé. Ce résultat ne communique jamais avec votre compte Loop, donc il ne peut ni faire entrer des retours ni envoyer les actions de signalement et de traitement.

Créez une vraie API key avec le scope returns dans Loop admin → Returns Management → Tools & integrations → Developer Tools, collez-la dans le champ api_key et enregistrez. Ensuite, le test affichera une vérification en attente — pour ce canal, c’est à cela que ressemble une vraie clé.

Le signalement ou le traitement d’un retour échoue

La cause la plus probable est l’API key elle-même : signaler et traiter sont les actions qui communiquent avec Loop, et elles exigent une clé créée avec le scope returns. Une clé créée sans ce scope peut rester dans la connexion en ayant l’air complète, pendant que Loop refuse chaque action réelle sur un retour.

Créez une nouvelle clé dans Loop admin → Returns Management → Tools & integrations → Developer Tools, cette fois avec le scope returns, remplacez l’api_key enregistrée par celle-ci et réessayez l’action de signalement ou de traitement sur le même retour.

La connexion est active, mais aucun retour n’arrive

Sur cette connexion, les retours n’arrivent que d’une seule façon : par webhook, au moment où un acheteur crée un retour dans Loop. Il n’y a pas d’extraction API derrière, donc une connexion active sans nouveaux retours dans Loop n’affichera correctement rien de nouveau — et les retours créés avant l’activation ne sont pas importés après coup.

Démarrez un vrai retour dans Loop et guettez-le ici et dans Runs / Logs. S’il arrive, la connexion fonctionne et la période calme précédente n’avait simplement pas de nouveaux retours. S’il n’arrive jamais, confirmez que la connexion est activée avec la bonne clé enregistrée, puis vérifiez Runs / Logs sur cette période.

Les acheteurs demandent où est leur étiquette de retour

Cette connexion ne fournit aucune étiquette de retour. Elle reçoit les retours et envoie les actions de signalement et de traitement ; l’étiquette qu’un acheteur imprime vient de Loop lui-même, selon le dispositif d’étiquettes que vous avez déjà dans Loop.

Gardez le flux d’étiquettes de l’acheteur dans Loop et vérifiez-y vos réglages d’étiquettes Loop. Utilisez cette connexion pour ce qu’elle fait : recevoir le retour ici pour que l’entrepôt puisse le signaler et le traiter.

Quelle clé utiliser si j’ai plusieurs API keys Loop ?

Une seule clé convient à cette connexion : une clé créée sous Returns Management → Tools & integrations → Developer Tools avec le scope returns. Les clés créées pour d’autres usages, ou sans ce scope, rempliront le champ, mais les actions de signalement et de traitement des retours ne fonctionneront pas avec elles.

Choisissez la clé avec le scope returns, ou créez-en une nouvelle en suivant les étapes d’identifiants ci-dessus, collez-la en entier dans api_key et enregistrez. Il n’y a qu’un seul champ, donc aucune clé fausse ne peut se cacher dans un deuxième endroit.