Intégration de l’API vendeur SHEIN : authentification et synchronisation

Ce que couvre l’API vendeur SHEIN

SHEIN propose ses solutions d’intégration via la SHEIN Developer Platform (également appelée SHEIN Open Platform). SHEIN la présente comme un ensemble de solutions technologiques connectées pour les flux liés aux produits, aux commandes, aux retours et aux approvisionnements. En pratique, une intégration de l’API vendeur SHEIN permet à votre propre système (ERP, outil multicanal, WMS ou back-office personnalisé) de communiquer avec SHEIN via HTTPS, au lieu de nécessiter des interventions manuelles dans le portail vendeur.

Le périmètre réaliste d’une première intégration reste limité. La plupart des équipes ont besoin de trois flux, dans cet ordre :

Des API dédiées aux retours et aux approvisionnements existent également, mais attendez que les commandes et les stocks soient fiables avant de les intégrer. Attention toutefois lorsque vous planifiez le projet : la documentation de la plateforme développeur est une application monopage qui évolue. Considérez donc chaque chemin d’endpoint et chaque nom de champ mentionnés dans cet article comme un point de départ, puis vérifiez-les dans la documentation SHEIN actuelle avant de coder votre intégration.

Comment fonctionne l’authentification de l’API SHEIN

SHEIN ne vous fournit pas une seule clé API statique. L’authentification repose sur deux niveaux d’identifiants, et les confondre est la cause la plus fréquente d’échec lors d’un premier appel.

Voici le fonctionnement généralement implémenté par les intégrations :

1. Le vendeur ouvre la page d’autorisation SHEIN avec votre appid, une redirectUrl encodée en Base64 et une valeur state de votre choix.
2. Une fois l’autorisation accordée, SHEIN redirige le vendeur vers votre URL avec un tempToken et votre valeur state. Le jeton est valable 10 minutes.
3. Votre serveur envoie en POST {"tempToken": "..."} à /open-api/auth/get-by-token sur le domaine de l’API.
4. La réponse contient openKeyId, supplierId, supplierSource, appid et un secretKey chiffré.
5. Vous déchiffrez le secretKey avec la clé secrète de votre application, puis vous stockez la paire pour ce vendeur.

Le SDK Java officiel de SHEIN reprend cette séparation : il propose un mode de signature APPID (utilisé pour l’échange du jeton via getToken(tempToken, authInfo)) et un mode OPEN_KEY_ID (utilisé pour les appels API classiques). Il répertorie également deux domaines API, openapi.sheincorp.com et openapi.sheincorp.cn. Les détails de l’échange sont disponibles sur la page officielle de SHEIN, Échanger openKeyId et secretKey, tandis que le SDK est publié sur sheinsight/open-sdk-java sur GitHub.

Conséquence pour la conception : le paramètre state est votre seul moyen de savoir lequel de vos clients vient d’autoriser l’application. Générez-le côté serveur, associez-le à la fiche du client et refusez tout callback dont la valeur state n’a pas été émise par votre système. Le négliger peut conduire, dans un outil multiclient, à associer les identifiants d’un vendeur au compte d’un autre.

Comment signer une requête API SHEIN

Chaque appel contient une signature construite à partir des identifiants du vendeur, du chemin de la requête et d’un horodatage en millisecondes. Le mécanisme utilisé par les intégrations est le suivant :

• Chaîne à signer : openKeyId&timestamp&path (par exemple le chemin /open-api/auth/get-by-token, sans le domaine).
• Clé HMAC : secretKey suivi d’une chaîne aléatoire de 5 caractères.
• Empreinte : HMAC-SHA256, encodée en hexadécimal, puis en Base64.
• Résultat : la chaîne aléatoire de 5 caractères placée devant la valeur Base64, puis envoyée dans l’en-tête x-lt-signature.

Vous envoyez également l’horodatage en millisecondes dans x-lt-timestamp, l’identifiant de l’application dans x-lt-appid, un type de contenu JSON et un en-tête language. Voici une version Python exécutable :

import base64, hashlib, hmac, secrets, string, time

def shein_signature(open_key_id: str, secret_key: str, path: str, timestamp_ms: int) -> str:
    alphabet = string.ascii_letters + string.digits
    random_key = ''.join(secrets.choice(alphabet) for _ in range(5))
    to_sign = f'{open_key_id}&{timestamp_ms}&{path}'
    hex_digest = hmac.new(
        (secret_key + random_key).encode(),
        to_sign.encode(),
        hashlib.sha256,
    ).hexdigest()
    return random_key + base64.b64encode(hex_digest.encode()).decode()

ts = int(time.time() * 1000)
sig = shein_signature('YOUR_OPEN_KEY_ID', 'YOUR_SECRET_KEY', '/open-api/auth/get-by-token', ts)

Deux détails posent souvent problème. Premièrement, Base64 s’applique à la chaîne hexadécimale, et non aux octets bruts de l’empreinte. Dans un langage qui renvoie par défaut des octets bruts (Go, ou digest() de Node sans encodage), vous devez donc ajouter explicitement l’étape hexadécimale. Deuxièmement, le chemin utilisé dans la chaîne à signer doit correspondre exactement à celui de l’appel, sans la chaîne de requête. Signer à un endroit et construire la route à un autre est une source classique d’erreurs de signature.

Vérifiez les noms exacts des en-têtes ainsi que les règles relatives aux chemins pour les appels métier (par opposition à l’échange du jeton) dans la documentation actuelle de SHEIN. Si vous développez en Java, la signature intégrée au SDK officiel élimine toute cette catégorie de bugs.

Comment déchiffrer le secretKey SHEIN

Le secretKey renvoyé lors de l’échange du jeton n’est pas utilisable tel quel. Il est chiffré en AES-128-CBC et encodé en Base64, puis déchiffré avec la clé secrète de votre application et un IV fixe que les intégrateurs documentent sous la valeur space-station-de. Voici une version Python utilisant PyCryptodome :

import base64
from Crypto.Cipher import AES
from Crypto.Util.Padding import unpad

def decrypt_secret_key(encrypted_b64: str, app_secret: str) -> str:
    key = app_secret.encode()[:16].ljust(16, b'\0')
    cipher = AES.new(key, AES.MODE_CBC, iv=b'space-station-de')
    return unpad(cipher.decrypt(base64.b64decode(encrypted_b64)), 16).decode()

La ligne key reproduit le fonctionnement d’OpenSSL pour AES-128 : la clé est tronquée ou complétée par des zéros jusqu’à 16 octets. Avec une bibliothèque qui exige une longueur de clé exacte, c’est à cette étape que l’erreur se produit. Une fois déchiffrée, stockez la valeur dans un gestionnaire de secrets ou une colonne chiffrée. Ne l’écrivez jamais dans les journaux et ne l’envoyez jamais au navigateur.

Concevoir une synchronisation des commandes et des stocks fiable en production

Obtenir le code 200 avec un appel signé est la partie facile. Ce qui détermine la solidité de l’intégration, c’est la manière dont vous faites circuler les données pendant plusieurs semaines.

Utilisez les webhooks pour la rapidité et le polling pour la fiabilité

SHEIN documente un mécanisme de webhook sur sa plateforme développeur (voir sa page Webhook Instruction). Les notifications push réduisent la latence, mais tout canal push peut perdre ou retarder des événements. Le modèle fiable consiste à utiliser un webhook pour déclencher la récupération immédiate de la commande, puis un polling de réconciliation planifié qui demande toutes les données modifiées depuis la dernière synchronisation réussie. Si le polling ne trouve jamais d’événement manqué par le webhook, vous avez la preuve que la conception fonctionne ; dans le cas contraire, vous avez détecté une faille avant qu’un client ne la découvre.

Rendez chaque écriture idempotente

Les nouvelles tentatives sont inévitables : délais d’attente, déploiements et livraisons de webhooks en double. Identifiez chaque commande par son identifiant SHEIN dans votre base de données, avec une contrainte d’unicité, et faites en sorte que les mises à jour du traitement et des stocks définissent une valeur plutôt qu’elles n’appliquent un incrément. Une nouvelle tentative de l’opération « diminuer de 1 » entraîne une survente ; une nouvelle tentative de l’opération « définir sur 14 » est sans conséquence.

Gérez la paire de jetons comme un état propre à chaque vendeur

Stockez openKeyId, le secretKey déchiffré et le supplierId pour chaque vendeur, et enregistrez la date d’autorisation. Si un vendeur révoque son accès, votre prochain appel échoue ; présentez alors dans votre produit un état « reconnecter SHEIN » plutôt que de laisser la synchronisation s’arrêter silencieusement.

Surveillez l’horloge

La signature contient un horodatage en millisecondes. Un serveur dont l’horloge dérive produira donc des requêtes qui semblent valides, mais sont rejetées. Activez NTP sur chaque hôte qui signe les requêtes.

Développer en interne, utiliser le SDK ou confier l’intégration à une équipe spécialisée

La signature et l’authentification peuvent être mises en place en un week-end. C’est la longue traîne — correspondance entre votre catalogue et les attributs de catégories SHEIN, gestion des erreurs, supervision et intégration des vendeurs — qui consomme des semaines. Choisissez votre approche selon le nombre de vendeurs que vous servez et selon que SHEIN est ou non votre seul canal.

Si vous devez connecter SHEIN à Amazon, eBay, Walmart ou Etsy dans un même système, un modèle de données interne partagé est plus adapté que des scripts isolés pour chaque canal. Netalith réalise ce type de projet dans le cadre de son service d’intégration de marketplaces, et les mêmes principes de conception s’appliquent, quelle que soit l’équipe qui écrit le code.

Checklist avant le lancement d’une intégration de l’API vendeur SHEIN

Pour toute question concernant l’accès à la plateforme développeur, SHEIN indique [email protected] comme adresse de contact. Si vous préférez faire cadrer et développer l’intégration par une équipe spécialisée, transmettez les détails via le formulaire de devis gratuit de Netalith.