Intégration de l’API Shopee : OAuth, signature et tokens

Comment fonctionne l’API Shopee Open Platform (v2)

Une intégration avec l’API Shopee Open Platform est une intégration REST signée. Votre serveur enregistre une application, chaque vendeur l’autorise via une redirection de type OAuth, puis chaque appel contient un identifiant partenaire, un horodatage et une signature HMAC-SHA256, ainsi qu’un token d’accès à durée limitée pour les appels au niveau de la boutique. La synchronisation des annonces, l’importation des commandes et la mise à jour des stocks reposent toutes sur ces éléments.

Shopee avait prévu la dépréciation complète de l’ancienne API v1 après le 26 décembre 2022 : tout nouveau développement cible donc la v2. C’est surtout le vocabulaire qui fait perdre du temps aux équipes lors d’une première intégration. Voici les principaux termes à connaître :

Enregistrer une application : la catégorie détermine tout

Shopee distingue deux profils de développeurs : les Third-Party Partners (entreprises qui créent des logiciels pour plusieurs vendeurs) et les Registered Business Sellers (vendeurs qui intègrent leur propre boutique). Une fois le profil approuvé, vous créez une application dans la console. C’est l’étape qui peut faire perdre plusieurs semaines aux équipes : la catégorie choisie lors de la création détermine toutes les API et autorisations que l’application pourra utiliser.

L’annonce de la FAQ développeurs de Shopee est très claire à ce sujet. L’équipe Open Platform n’active pas les API individuellement, les autorisations ne peuvent pas être ajoutées à une application existante et le besoin de fonctionnalités différentes peut imposer de créer une nouvelle application dans une autre catégorie.

• Choisissez la catégorie à partir de votre liste d’endpoints, pas de son intitulé. Notez les endpoints produit, commande, logistique et paiement dont vous avez besoin, puis vérifiez qu’ils appartiennent tous à une même catégorie avant de créer l’application.
• Ne promettez pas par défaut la messagerie avec les acheteurs. Les demandes d’applications Customer Service (Chat API) provenant de tiers individuels et les plateformes Third-party Partner sont fermées depuis le 18 novembre 2024. Vérifiez l’accès avant d’inclure une boîte de réception ou un chatbot dans le périmètre client.
• Une erreur « Permission denied » indique généralement une mauvaise catégorie, un endpoint retiré ou une modification documentée, et non un problème de signature.

Le processus d’autorisation, étape par étape

Quel que soit le type ou la catégorie de l’application, le processus commence par un lien d’autorisation construit à partir de l’URL fixe de Shopee et des paramètres requis. Le contrat complet figure dans le guide d’autorisation et d’authentification de Shopee. Voici le déroulement pratique :

1. Construire un lien signé. Appelez /api/v2/shop/auth_partner avec partner_id, timestamp, sign et votre URL de redirect.
2. Le vendeur approuve. Le vendeur se connecte sur la page Shopee et accorde l’accès. Il choisit la durée de l’autorisation : 7, 30, 90, 180 ou 365 jours, ou une date personnalisée dans la limite de 365 jours.
3. Shopee redirige le vendeur vers votre URL de redirection avec code et shop_id dans la chaîne de requête.
4. Échanger le code via /api/v2/auth/token/get contre un access_token et un refresh_token.
5. Appeler les API de la boutique et renouveler le token via /api/v2/auth/access_token/get avant l’expiration de l’access token.

Deux de ces lignes sont très souvent mal interprétées. Le renouvellement d’un token ne redirige jamais le vendeur vers Shopee, car il utilise uniquement le refresh token. Par ailleurs, l’autorisation du vendeur suit un calendrier distinct de celui de vos tokens : un vendeur ayant choisi 7 jours sera déconnecté au bout d’une semaine, même si votre tâche de renouvellement fonctionne parfaitement. Enregistrez cette date d’expiration et invitez le vendeur à se reconnecter avant son échéance.

Signer une requête API Shopee (HMAC-SHA256)

La signature correspond au condensat hexadécimal d’un HMAC-SHA256 calculé sur une chaîne de base et signé avec votre partner key. Le contenu de cette chaîne dépend du type d’API :

Le résultat est envoyé comme paramètre de requête sign, avec partner_id et timestamp. Les appels à une boutique contiennent également access_token et shop_id. api_path désigne uniquement le chemin, par exemple /api/v2/shop/get_shop_info, sans l’hôte ni la chaîne de requête. Ce module Python couvre l’ensemble du premier parcours de connexion :

import hashlib
import hmac
import time
from urllib.parse import urlencode

import requests

HOST = 'https://partner.test-stable.shopeemobile.com'  # sandbox; production is https://partner.shopeemobile.com
PARTNER_ID = 1000000          # from the console, must match the environment
PARTNER_KEY = 'your-partner-key'


def sign(path, ts, access_token='', entity_id=''):
    # public API: partner_id + path + timestamp
    # shop API: ... + access_token + shop_id (merchant API: merchant_id)
    base = f'{PARTNER_ID}{path}{ts}{access_token}{entity_id}'
    return hmac.new(PARTNER_KEY.encode(), base.encode(), hashlib.sha256).hexdigest()


def auth_url(redirect):
    path = '/api/v2/shop/auth_partner'
    ts = int(time.time())
    query = urlencode({'partner_id': PARTNER_ID, 'timestamp': ts,
                       'sign': sign(path, ts), 'redirect': redirect})
    return f'{HOST}{path}?{query}'


def public_post(path, body):
    ts = int(time.time())
    params = {'partner_id': PARTNER_ID, 'timestamp': ts, 'sign': sign(path, ts)}
    body = dict(body, partner_id=PARTNER_ID)
    return requests.post(HOST + path, params=params, json=body, timeout=15).json()


def get_token(code, shop_id):
    return public_post('/api/v2/auth/token/get', {'code': code, 'shop_id': shop_id})


def refresh_token(refresh_tok, shop_id):
    return public_post('/api/v2/auth/access_token/get',
                       {'refresh_token': refresh_tok, 'shop_id': shop_id})


def shop_get(path, access_token, shop_id, **extra):
    ts = int(time.time())
    params = {'partner_id': PARTNER_ID, 'timestamp': ts, 'access_token': access_token,
              'shop_id': shop_id, 'sign': sign(path, ts, access_token, shop_id)}
    params.update(extra)
    return requests.get(HOST + path, params=params, timeout=15).json()


# info = shop_get('/api/v2/shop/get_shop_info', access_token, shop_id)

Commencez par l’exécuter avec l’hôte sandbox, puis remplacez l’hôte, le partner ID et la clé par leurs équivalents de production uniquement lorsque tout fonctionne. Trois causes expliquent la plupart des erreurs de signature :

• Un environnement incorrect. La clé, le partner_id et l’hôte doivent tous appartenir au même environnement (sandbox ou production). Une clé de production utilisée avec l’hôte sandbox échoue systématiquement.
• Des horodatages différents. L’horodatage intégré à la chaîne de base doit être exactement celui envoyé dans l’URL. Calculez-le une seule fois par appel.
• L’horloge du serveur qui dérive. Shopee n’accepte un horodatage signé que pendant quelques minutes. Une horloge serveur décalée peut donc donner l’impression d’un problème de signature intermittent. Maintenez NTP actif.

Stocker et renouveler les tokens sans interrompre la synchronisation

Stockez un enregistrement de tokens par shop_id et par merchant_id, jamais par application. Cet enregistrement doit contenir l’access token, le refresh token, les deux dates d’expiration ainsi que la date d’expiration de l’autorisation du vendeur. Renouvelez les tokens de manière proactive, bien avant la limite de quatre heures, plutôt que d’attendre l’échec d’un appel au milieu d’une synchronisation.

Le problème subtil vient de la concurrence. Si deux workers renouvellent simultanément les tokens d’une même boutique, celui qui perd la course peut remplacer une paire valide par une paire obsolète. Considérez le refresh token comme rotatif : utilisez un verrou par boutique, effectuez le renouvellement et enregistrez les deux tokens renvoyés dans la même transaction en remplaçant les valeurs existantes. Tous les autres workers doivent lire les données depuis la base et ne jamais renouveler les tokens de leur propre côté.

Cette couche de gestion des tokens est la partie peu visible dont tout connecteur de marketplace a besoin, et sa complexité augmente à chaque nouveau canal. Les équipes qui synchronisent Shopee avec Amazon, eBay ou TikTok Shop décident souvent qu’il est plus rentable de faire concevoir et maintenir leur intégration marketplace par un prestataire plutôt que de gérer un modèle d’authentification propre à chaque plateforme.

Sandbox et production : ce que test-stable permet ou non de vérifier

L’hôte sandbox est partner.test-stable.shopeemobile.com et l’hôte de production est partner.shopeemobile.com. Shopee présente le sandbox comme fonctionnel, mais pas comme une réplique complète de la production. Il faut donc s’attendre à des différences de comportement, de limites et de stabilité.

• Utilisez-le pour valider la signature, le processus d’autorisation, le renouvellement des tokens et la structure des payloads.
• Ne l’utilisez pas pour évaluer le débit, les états de commande particuliers ou le comportement de la logistique.
• La création de commandes de test peut échouer avec des erreurs telles que error_sandbox_order_checkout_cart_item, invalid product ou Failed to get info. Shopee recommande de créer de nouveaux produits, d’essayer une autre catégorie et de répéter le processus avant de conclure que le problème vient de votre code.
• Si vous ouvrez un ticket auprès du support, effectuez d’abord des tests d’isolation et joignez un enregistrement vidéo complet de l’écran, un fichier HAR ainsi que la requête et la réponse intégrales.

Pourquoi les données des acheteurs sont masquées (liste blanche IP)

Si les réponses de commande contiennent des informations masquées sur les acheteurs, la solution se trouve dans les paramètres de votre application, et non dans une demande au support. L’accès aux données sensibles dépend de la configuration de sécurité de l’application, notamment de la liste blanche IP, et Shopee précise qu’il n’existe aucune levée manuelle du masquage. Vous configurez cette liste dans la console ; le personnel de Shopee ne peut pas le faire à votre place.

Vérifiez deux éléments dans l’ordre. Tout d’abord, assurez-vous que la liste blanche est configurée et activée pour les adresses IP de sortie exactes utilisées par vos serveurs. C’est particulièrement important si vous déployez derrière une passerelle NAT ou sur une infrastructure autoscalée dont les adresses changent. Vérifiez ensuite le statut de la commande : certains statuts ne donnent jamais accès aux données de l’acheteur via l’API. Des champs masqués sur une nouvelle commande impayée ne signalent donc pas nécessairement un problème de liste blanche.

Expiration et rotation sécurisée de la Partner Key

La Partner Key est valide pendant 180 jours à compter de sa génération et ne se renouvelle pas automatiquement. À son expiration, la plateforme la marque comme invalide et bloque les appels API qui l’utilisent. Pour une intégration en production, tous les vendeurs peuvent donc être mis hors service simultanément. Programmez un rappel bien avant le 180e jour et traitez cette rotation comme une mise en production planifiée.

• La réinitialisation prend immédiatement effet pour la nouvelle clé.
• L’ancienne clé peut rester active jusqu’à 72 heures après la réinitialisation, ce qui vous laisse le temps de déployer le nouveau secret sur vos serveurs.
• La réinitialisation n’invalide pas les autorisations des vendeurs : aucun vendeur n’a donc besoin de se reconnecter.
• La clé se gère dans l’application, sous App List dans la console. Shopee ne peut pas générer de clé de remplacement à votre place.

Lisez la clé depuis un gestionnaire de secrets au moment de l’exécution plutôt que de l’intégrer dans vos images, afin que la rotation se fasse par modification de configuration et non par nouveau déploiement.

Push Mechanism ou interrogation périodique pour les commandes et les stocks

Shopee documente un Push Mechanism, c’est-à-dire un webhook qui informe l’URL de callback enregistrée pour votre application lorsque surviennent des événements tels qu’un changement de statut de commande. C’est le bon outil pour réduire la latence, mais il ne doit pas être votre seul mécanisme.

Concevez une architecture combinant push et réconciliation. Vérifiez la signature du push comme l’indique la documentation du Push Mechanism, accusez réception rapidement et placez l’événement dans une file plutôt que de le traiter directement. Exécutez ensuite une tâche planifiée qui interroge les commandes sur une fenêtre de dates de mise à jour et les compare à votre base de données. Les pushs peuvent arriver en retard, en double ou ne jamais arriver ; la réconciliation transforme donc un flux fourni au mieux en un système fiable. Rendez chaque gestionnaire idempotent à partir du numéro de commande afin qu’un push répété ne provoque aucun effet indésirable.

Erreurs courantes de l’API Shopee et premières vérifications

Développer soi-même ou confier l’intégration

Le périmètre Shopee reste gérable pour une boutique et un développeur : signer correctement les requêtes, stocker les tokens par boutique, les renouveler sous verrou, réconcilier les pushs et effectuer la rotation de la clé à temps. Les coûts apparaissent surtout lors de la maintenance, lorsqu’une limitation de catégorie bloque une fonctionnalité, qu’une clé expire pendant un week-end ou que vous ajoutez une deuxième marketplace avec ses propres règles.

Si vous préférez cadrer ce travail plutôt que de l’assumer en interne, demandez un devis gratuit en indiquant les marketplaces et les fonctionnalités dont vous avez besoin. Le prix est établi selon le périmètre, et vous recevez une réponse sans aucun engagement.