Social Commerce

Guide d’intégration de l’API TikTok Shop : OAuth et webhooks

Découvrez l’intégration de l’API TikTok Shop : tokens OAuth, signature HMAC, vérification des webhooks, limites de débit et erreurs courantes.

Photo de profil de Long Nguyen

Long Nguyen

Développeur fullstack · Ingénieur IA · Chercheur

• • 4 min de lecture •

Comment s’articule une intégration de l’API TikTok Shop

Une intégration de l’API TikTok Shop repose sur quatre éléments répartis entre trois hôtes différents : l’autorisation du vendeur, l’échange de tokens, les appels signés à l’API métier et les webhooks entrants. La plupart des premières intégrations échouent parce que le mauvais hôte est appelé ou que les mauvais octets sont signés, plutôt qu’à cause des endpoints eux-mêmes.

Étape Hôte ou mécanisme Fonction
1. Le vendeur autorise votre application services.tiktokshop.com (reste du monde) ou services.us.tiktokshop.com (États-Unis), chemin /open/authorize?service_id=... Renvoie un auth_code temporaire vers votre URL de redirection
2. Échange du token auth.tiktok-shops.com, /api/v2/token/get et /api/v2/token/refresh Échange le code contre un token d’accès et un token de rafraîchissement
3. Appels à l’API métier open-api.tiktokglobalshop.com, /{category}/{version}/{resource} Produits, commandes, exécution, retours, finances et configuration des webhooks
4. Webhooks Un endpoint HTTPS que vous hébergez Vous transmet les événements liés aux commandes, colis, produits et autorisations

L’hôte des tokens et l’hôte métier sont différents. De plus, l’échange du token s’effectue via une requête GET qui transporte le secret de votre application dans la chaîne de requête. C’est suffisamment inhabituel pour surprendre les développeurs habitués à un POST OAuth 2.0 standard : cette étape mérite donc sa propre section.

Accéder à l’API TikTok Shop : Partner Center, application et scopes

Tout commence dans TikTok Shop Partner Center. Dans App & Service, vous créez l’application. Sa page de détails affiche trois valeurs que vous utiliserez constamment : app_key, app_secret et service_id. Le service_id sert à construire le lien d’autorisation du vendeur ; la clé et le secret identifient votre application, et le secret signe chaque requête. Il doit donc rester exclusivement sur votre serveur.

Les scopes méritent davantage de réflexion qu’on ne leur en accorde habituellement :

  • Vous activez les scopes de l’application dans Partner Center. Le guide d’autorisation de TikTok précise que l’activation de scopes inutiles peut prolonger l’examen de l’application et réduire le taux auquel les vendeurs approuvent votre autorisation.
  • Les scopes réellement approuvés par un vendeur sont renvoyés dans le champ granted_scopes de la réponse de token. L’erreur 105005 (accès refusé) signifie que l’application ou le token ne possède pas le scope requis par l’endpoint. Si le problème vient du token, le vendeur doit réautoriser l’application pour obtenir un token qui l’inclut.
  • Si votre application dispose d’une liste blanche d’adresses IP, les appels provenant d’une adresse qui n’y figure pas échouent avec 36009033.

Notre recommandation : demandez uniquement les scopes correspondant aux fonctionnalités que vous déployez en premier, puis ajoutez les scopes fonctionnalité par fonctionnalité. Un écran d’autorisation allégé convertit mieux. Par ailleurs, toute modification ultérieure des scopes oblige les vendeurs déjà connectés à réautoriser l’application : mieux vaut donc planifier des groupes de scopes que les découvrir progressivement.

Pour les tests, Partner Center propose des boutiques de développement Seller Center ainsi qu’un outil de test de l’API. Dans Development Kits, un Webhook Log montre également ce que TikTok Shop a envoyé et la réponse de votre serveur : c’est le moyen le plus rapide de diagnostiquer un endpoint webhook.

OAuth TikTok Shop : lien d’autorisation, auth_code et échange du token

  1. Redirigez le vendeur vers votre lien d’autorisation. Ajoutez une valeur state imprévisible, stockée côté serveur, puis vérifiez-la au retour du vendeur (protection contre les attaques CSRF).
  2. TikTok redirige le vendeur vers votre URL de redirection avec ?code=...&state=.... Si le vendeur refuse, il est tout de même redirigé, mais avec code=null&error=auth_denied.
  3. Échangez immédiatement le code (appelé auth_code dans l’API de token). Il expire après 30 minutes et ne peut être utilisé qu’une seule fois. Toute réutilisation ou tout délai entraîne l’erreur 36004004.
  4. Stockez les tokens renvoyés, l’identité de la boutique et les scopes accordés.

Les endpoints de token présentent trois particularités à connaître avant d’écrire votre client :

  • L’échange comme le rafraîchissement utilisent des requêtes GET, avec app_key, app_secret et le code ou token de rafraîchissement dans la chaîne de requête.
  • grant_type doit être exactement authorized_code pour l’échange (et non le standard authorization_code) et refresh_token pour le rafraîchissement.
  • Le succès est indiqué par code: 0 dans le corps JSON : vérifiez donc le corps, et pas uniquement le statut HTTP.
import requests

AUTH_HOST = "https://auth.tiktok-shops.com"

def _token_call(path, params):
    resp = requests.get(f"{AUTH_HOST}{path}", params=params, timeout=15)
    payload = resp.json()
    if payload.get("code") != 0:  # success is code 0 in the body
        raise RuntimeError(f"token call failed: code={payload.get('code')} "
                           f"message={payload.get('message')} "
                           f"request_id={payload.get('request_id')}")
    return payload["data"]

def exchange_auth_code(app_key, app_secret, auth_code):
    return _token_call("/api/v2/token/get", {
        "app_key": app_key,
        "app_secret": app_secret,
        "auth_code": auth_code,
        "grant_type": "authorized_code",  # not "authorization_code"
    })

def refresh_tokens(app_key, app_secret, refresh_token):
    return _token_call("/api/v2/token/refresh", {
        "app_key": app_key,
        "app_secret": app_secret,
        "refresh_token": refresh_token,
        "grant_type": "refresh_token",
    })

La réponse contient access_token, access_token_expire_in et refresh_token_expire_in sous forme d’horodatages Unix, ainsi que open_id, seller_name, seller_base_region, user_type et granted_scopes. Par défaut, le token d’accès est valide pendant 7 jours. Le token de rafraîchissement expire à la fin de la durée d’autorisation accordée par le vendeur : ce n’est donc pas un identifiant permanent.

Conséquences pratiques pour votre conception :

  • Stockez les deux horodatages d’expiration pour chaque boutique et rafraîchissez le token suffisamment tôt, plutôt que d’attendre une réponse 105002 (identifiants expirés) au milieu d’une synchronisation de commandes.
  • Considérez chaque réponse de rafraîchissement comme faisant autorité et remplacez les deux tokens par les valeurs renvoyées.
  • Le secret de l’application transitant dans la chaîne de requête, excluez ces deux URL des journaux d’accès, des traces APM et des rapports d’erreur.
  • Utilisez user_type pour confirmer le type d’utilisateur qui vous a autorisé (vendeur, créateur ou partenaire) avant d’envoyer un token vers des endpoints limités aux vendeurs.

Signer les requêtes de l’API TikTok Shop (HMAC-SHA256)

Chaque appel à l’API métier doit contenir un paramètre de requête sign. Les requêtes dépourvues d’une signature valide sont refusées. Le guide de signature de TikTok définit l’algorithme, qui consiste à construire une chaîne en six étapes :

  1. Prenez tous les paramètres de requête, à l’exception de sign et access_token, puis triez les clés par ordre alphabétique.
  2. Concaténez-les au format {key}{value}, sans séparateur.
  3. Ajoutez au début le chemin de la requête, avec la catégorie, la version et la ressource (par exemple /authorization/202309/shops).
  4. Sauf si le type de contenu est multipart/form-data, ajoutez le corps de la requête.
  5. Entourez la chaîne complète de votre secret : secret + string + secret.
  6. Calculez le HMAC-SHA256 de cette chaîne en utilisant le secret de l’application comme clé, puis encodez le résultat en hexadécimal.
import hashlib, hmac
from urllib.parse import urlsplit, parse_qsl

def sign_request(url, body, app_secret, content_type="application/json"):
    parts = urlsplit(url)
    params = {k: v for k, v in parse_qsl(parts.query, keep_blank_values=True)
              if k not in ("sign", "access_token")}
    base = parts.path + "".join(f"{k}{params[k]}" for k in sorted(params))
    if not content_type.startswith("multipart/form-data"):
        base += body.decode("utf-8")   # the exact bytes you will send
    wrapped = app_secret + base + app_secret
    return hmac.new(app_secret.encode(), wrapped.encode(),
                    hashlib.sha256).hexdigest()

Pour vérifier votre implémentation, utilisez l’exemple détaillé du guide : secret d’application e59af819cc, chemin /authorization/202309/shops, app_key=29a39d et timestamp=1623812664. La chaîne signée finale est e59af819cc/authorization/202309/shopsapp_key29a39dtimestamp1623812664e59af819cce et la signature est b596b73e0cc6de07ac26f036364178ab16b0a907af13d43f0a0cd2345f582dc8. La fonction ci-dessus la reproduit exactement.

Lorsqu’une erreur de signature est renvoyée par TikTok, l’une de ces causes est presque toujours en jeu :

Erreur Pourquoi la signature échoue
Resérialiser le corps JSON après la signature Le guide demande de signer exactement les octets envoyés. Un changement dans l’ordre des clés, les espaces ou l’échappement produit un hash différent. Sérialisez une fois, signez ces octets et envoyez-les.
Inclure le token d’accès dans la signature Pour l’API version 202309 et les versions suivantes, le token est placé dans l’en-tête x-tts-access-token et ne fait pas partie de la chaîne signée. Les anciens paramètres de requête access_token sont également exclus.
Utiliser SHA-256 seul Il faut utiliser HMAC-SHA256 avec le secret de l’application comme clé.
Oublier le chemin ou le segment de version Signez le chemin exactement tel qu’il apparaît après l’hôte.
Horodatage incorrect Il doit s’agir d’un horodatage Unix à 10 chiffres, en secondes, compris entre 5 minutes avant et 30 secondes après l’horloge de la plateforme. Les millisecondes échouent.
Clé ou secret d’application incorrect C’est la cause la plus fréquente : une clé provenant d’une application et le secret d’une autre.

Notez que shop_cipher, lorsqu’un endpoint l’utilise, est un paramètre de requête normal et doit être inclus dans la chaîne signée.

Votre premier appel : Get Authorized Shops et shop_cipher

Le premier appel recommandé est Get Authorized Shops, GET /authorization/202309/shops. Il vous indique quelles boutiques le vendeur a autorisées pour votre application et renvoie les identifiants nécessaires à la suite, notamment le shop_cipher chiffré.

import json, time, requests
from urllib.parse import urlencode

API_HOST = "https://open-api.tiktokglobalshop.com"

def call_api(method, path, app_key, app_secret, access_token,
             query=None, body=None):
    query = {"app_key": app_key, "timestamp": str(int(time.time())),
             **(query or {})}
    raw = b"" if body is None else json.dumps(body, separators=(",", ":")).encode()
    url = f"{API_HOST}{path}?{urlencode(query)}"
    query["sign"] = sign_request(url, raw, app_secret)
    resp = requests.request(
        method, f"{API_HOST}{path}", params=query, data=raw, timeout=20,
        headers={"x-tts-access-token": access_token,
                 "content-type": "application/json"})
    return resp.status_code, resp.json()

# First call: which shops did this seller authorize?
status, data = call_api("GET", "/authorization/202309/shops",
                        APP_KEY, APP_SECRET, access_token)

Les appels métier utilisent les paramètres communs app_key, sign et timestamp dans la requête, ainsi que les en-têtes x-tts-access-token et content-type. Le segment de catégorie du chemin regroupe l’API par domaine métier :

Domaine Segment de catégorie Exemples de ressources
Autorisation authorization shops
Produit product products, categories, inventory
Commande order orders
Exécution fulfillment packages, shipping_documents
Retour et remboursement return_refund returns, refunds, cancellations
Logistique logistics warehouses, delivery_options, shipping_providers
Finance finance payments, settlements
Événements (webhooks) event webhooks

Le piège vient du fait que shop_cipher dépend de l’endpoint. Certains endpoints l’exigent (son absence renvoie 106013), tandis que d’autres le refusent comme inutile (réponse 36009004 indiquant qu’il n’est pas requis). Ne devinez pas : vérifiez les exigences dans la documentation de chaque endpoint et conservez un indicateur par endpoint dans votre wrapper client.

Webhooks TikTok Shop : configuration, vérification et nouvelles tentatives

Les webhooks transmettent les événements vers une URL HTTPS que vous enregistrez. Vous pouvez les configurer dans Partner Center (App & Service, puis votre application, Basic Information, Developing) ou par boutique via l’API Events avec PUT /event/202309/webhooks et un corps contenant address et event_type. Les deux méthodes écrivent dans la même configuration sous-jacente : choisissez donc une seule source de vérité. Le guide de configuration des webhooks de TikTok définit les règles de livraison :

Exigence Règle
URL HTTPS, TLS 1.2 ou version ultérieure, nom de domaine (pas d’adresse IP), aucun port personnalisé
Accusé de réception Renvoyer HTTP 200 avec un corps vide sous 3 secondes
Rejet d’une signature incorrecte Renvoyer 401. Cela compte comme un échec de livraison, et non comme un accusé de réception
Garantie de livraison Au moins une fois : les doublons sont donc possibles
Nouvelles tentatives 2 minutes après le premier échec, puis 30 minutes, 3 heures et 12 heures après l’échec précédent. Les tentatives s’arrêtent après le quatrième échec

Vérifier la signature

La signature d’un webhook n’est pas celle d’une requête API. TikTok la place dans l’en-tête Authorization (sans préfixe Bearer) sous la forme d’un condensat HMAC-SHA256 hexadécimal en minuscules, calculé à partir de app_key suivi du corps brut de la requête, avec votre secret d’application comme clé. Vérifiez-la sur les octets bruts avant l’analyse du contenu et utilisez une comparaison en temps constant.

import hashlib, hmac

def verify_webhook(app_key, app_secret, raw_body, authorization):
    expected = hmac.new(app_secret.encode(), app_key.encode() + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, (authorization or "").strip().lower())

L’exemple officiel est reproductible : une clé d’application abcdef, un secret 123 et l’exemple de payload de commande du guide des webhooks produisent 5dec0f11ec2f6783b8deee53c9ffbf8d024302f7c7e7fa55a35d17629031ac05. La fonction ci-dessus obtient le même résultat et échoue si un seul octet du corps est modifié.

Événements auxquels s’abonner

La liste des événements est longue : adaptez-la aux fonctions de votre application :

event_type Utilisation
ORDER_STATUS_CHANGE Synchroniser les nouvelles commandes et les changements de statut
RECIPIENT_ADDRESS_UPDATE, PACKAGE_UPDATE Maintenir à jour les données d’expédition et d’exécution
CANCELLATION_STATUS_CHANGE, RETURN_STATUS_CHANGE, REVERSE_STATUS_UPDATE Gérer les annulations, les retours et les demandes de remboursement des acheteurs
PRODUCT_STATUS_CHANGE, PRODUCT_AUDIT_STATUS_CHANGE, PRODUCT_CREATION, PRODUCT_INFORMATION_CHANGE, PRODUCT_CATEGORY_CHANGE Suivre l’état des fiches produit et les résultats des contrôles
SELLER_DEAUTHORIZATION Cesser les appels API pour cette boutique et désactiver la connexion
UPCOMING_AUTHORIZATION_EXPIRATION Prévenir le vendeur et l’inviter à réautoriser l’application. Envoyé 30 jours avant l’expiration, puis chaque jour jusqu’à la réautorisation

Concevez votre listener selon le processus suivant : authentifier, enregistrer, accuser réception, puis traiter de manière asynchrone. Dédupliquez avec tts_notification_id et ne vous basez pas uniquement sur le champ numérique type, car la documentation ne publie pas de correspondance numérique complète pour chaque sujet. Utilisez plutôt le event_type auquel vous êtes abonné et le schéma de payload correspondant. Surtout, TikTok précise qu’il ne faut pas considérer les webhooks comme l’unique source de vérité : programmez une synchronisation périodique des commandes, colis, produits, retours et annulations. Ainsi, une livraison manquée après la séquence de nouvelles tentatives de 12 heures ne se transformera pas en commande perdue.

Limites de débit de l’API TikTok Shop : documentation et gestion du 429

Les articles de sites tiers donnent parfois des chiffres fixes concernant les limites de TikTok Shop. Ignorez-les. La page consacrée aux limites précise que la plateforme utilise une allocation dynamique de QPS, fondée notamment sur le nombre de boutiques autorisées, le type d’endpoint et la charge réelle de la plateforme. Elle ne fournit pas un chiffre QPS fixe unique. Si la documentation d’un endpoint publie sa propre limite, c’est cette valeur qui prévaut.

La documentation fournit toutefois un modèle d’isolation et un point de départ :

  • La plus petite unité d’isolation est le couple ID d’application × boutique autorisée. Une même application dispose d’une capacité distincte pour chaque boutique, et une même boutique d’une capacité distincte pour chaque application : une boutique très sollicitée ne devrait donc pas bloquer la file d’une autre. Certains endpoints sont toutefois limités au niveau de l’application.
  • Un nombre plus élevé de boutiques autorisées augmente généralement la capacité totale, mais pas de façon linéaire ni instantanée.
  • Un 429 n’est pas toujours de votre fait : une limitation de protection au niveau de l’endpoint ou de la plateforme peut se déclencher même avec un faible volume.
Type d’endpoint Débit de départ conseillé par application et boutique
Écriture lourde ou analyse complexe 0,2 à 1 requête/seconde
Écriture standard 1 à 3 requêtes/seconde (utilisez l’idempotence avant d’activer les nouvelles tentatives)
Lecture standard ou synchronisation 3 à 10 requêtes/seconde
Lecture légère ou traitement par lots 5 à 20 requêtes/seconde

TikTok présente ces valeurs comme des points de départ prudents pour la limitation côté client, et non comme des quotas garantis. Augmentez progressivement le débit de 20 à 30 % toutes les 10 à 15 minutes et arrêtez-vous dès que la limitation apparaît.

Traitez aussi bien HTTP 429 que le code métier 36009002 comme une limitation de débit et journalisez les deux. Un 503 correspond à une autre situation (service indisponible) : appliquez-lui une courte attente plutôt qu’une pénalité de limitation. Le modèle de nouvelle tentative documenté repose sur un backoff exponentiel avec jitter, sans jamais réessayer avant le délai indiqué par l’en-tête Retry-After. La documentation donne comme exemples un délai initial de 1 seconde, un plafond local de 60 secondes et environ 5 tentatives : adaptez ces valeurs à votre charge.

import random

def backoff_seconds(retry, retry_after=None, base=1.0, cap=60.0):
    wait = min(base * (2 ** retry) + random.uniform(0, 0.5), cap)
    return max(wait, retry_after) if retry_after is not None else wait

Deux habitudes réduisent davantage la limitation que n’importe quel code de backoff : privilégiez les endpoints par lots (généralement comptabilisés une fois par requête HTTP, et non par élément, sauf indication contraire de l’endpoint) et préférez une synchronisation incrémentielle avec filtres de date de modification aux extractions complètes. Si votre produit connecte de nombreux vendeurs, créez un limiteur par couple application-boutique et placez les requêtes de chaque boutique dans sa propre file. C’est ainsi que la plupart des intégrations TikTok Shop passent d’un script réalisé en un week-end à un véritable système. C’est également le type de projet couvert par l’intégration de l’API TikTok Shop pour les vendeurs du social commerce.

Versions de l’API : pourquoi 202309 est important

TikTok versionne chaque API séparément, et le nom d’une version correspond à l’année et au mois de son lancement. Les nouvelles versions sortent généralement chaque mois, mais toutes les API ne changent pas chaque mois : plusieurs endpoints d’une même intégration peuvent donc légitimement utiliser des versions différentes.

  • Depuis le format 202309, la version est un segment du chemin : https://open-api.tiktokglobalshop.com/{category}/{version}/{resource}. Les anciennes API transmettaient version comme paramètre de requête.
  • À partir de 202309, le token d’accès a été déplacé de la chaîne de requête vers l’en-tête x-tts-access-token.
  • Après la sortie d’une nouvelle version, la précédente reste disponible pendant au moins 2 mois. Toute suppression définitive est annoncée dans le changelog au moins 2 mois à l’avance.
  • Une version incorrecte ou retirée renvoie 36009014, même si certaines réponses de passerelle affichent encore 36009004 avec un message indiquant une version invalide. Vérifiez le texte du message en plus du code.

Le versionnage a aussi des conséquences métier. TikTok Shop a ajouté le statut de commande On Hold : pendant l’heure qui suit le paiement, les acheteurs peuvent annuler sans l’accord du vendeur, les vendeurs ne peuvent pas intervenir sur la commande et les champs d’adresse sont renvoyés vides. Seules les réponses de commande v202309 contiennent le champ is_on_hold_order ; les applications utilisant des versions anciennes ne peuvent pas identifier ces commandes de manière fiable. Si votre synchronisation des commandes repose encore sur une ancienne version, c’est la première migration à effectuer.

Fixez explicitement les versions dans votre client, consultez régulièrement le changelog et lisez la documentation de la version cible (chemin, en-têtes, champs et scopes) avant de mettre à niveau un endpoint.

Erreurs courantes de l’API TikTok Shop et leur signification

Code Signification Première vérification
106001 sign invalide Chemin signé, octets exacts du corps, horodatage et secret de l’application
105002 Token d’accès expiré Exécuter le flux de rafraîchissement, puis réessayer une fois
105005 Accès refusé pour scope manquant Scopes de l’application dans Manage API, puis granted_scopes du token
101000 Requête ou en-tête invalide (token ou cipher) user_type du token pour l’endpoint et appartenance du token à la boutique indiquée par shop_cipher
106013 shop_cipher manquant Le récupérer avec Get Authorized Shops
36009004 Réutilisé pour de nombreuses erreurs de validation Lire le message : signature absente, en-tête de token incorrect, clé d’application invalide, fenêtre d’horodatage ou shop_cipher superflu
36009002 Limitation de débit Ralentir les appels et respecter Retry-After
36009010 Méthode HTTP invalide Utiliser exactement la méthode indiquée dans la documentation de l’endpoint
36009014 Version d’API invalide Vérifier le segment de version dans le chemin
36009033 IP absente de la liste blanche Paramètres App and Service dans Partner Center
36004004 Code d’autorisation invalide Code déjà utilisé, datant de plus de 30 minutes ou incorrect

Deux règles permettent de raccourcir le diagnostic. Ne basez jamais votre logique uniquement sur 36009004 : associez-le au mot-clé du message. Et journalisez systématiquement la réponse complète avec son request_id, car c’est l’identifiant dont le support TikTok a besoin.

Checklist de mise en production d’une intégration TikTok Shop

  • Stockez app_secret, les tokens d’accès et les tokens de rafraîchissement sous forme chiffrée, et masquez les URL des endpoints de token dans les journaux.
  • Rafraîchissez les tokens selon un calendrier fondé sur les horodatages d’expiration enregistrés ; suivez séparément la date de fin d’autorisation de chaque boutique.
  • Sérialisez les corps de requête une seule fois et signez exactement les octets envoyés.
  • Conservez une configuration par endpoint pour shop_cipher, la méthode HTTP et la version de l’API.
  • Utilisez un limiteur et une file par couple application-boutique, privilégiez les endpoints par lots et appliquez un backoff pour les 429 comme pour 36009002.
  • Vérifiez les signatures des webhooks sur le corps brut, répondez rapidement avec 200, enregistrez d’abord, traitez ensuite et dédupliquez avec tts_notification_id.
  • Abonnez-vous à SELLER_DEAUTHORIZATION et UPCOMING_AUTHORIZATION_EXPIRATION afin que l’accès à une boutique ne cesse jamais sans avertissement.
  • Réconciliez les commandes, colis, produits et retours via une synchronisation planifiée : aucun webhook ne doit être l’unique source de vérité.
  • Surveillez le changelog pour repérer les retraits de versions et les nouveaux champs obligatoires.

Si vous préférez confier la création et la maintenance de cette intégration à une équipe plutôt que de la développer vous-même, vous pouvez demander un devis gratuit en décrivant le workflow TikTok Shop dont vous avez besoin.

FAQ

Questions fréquentes

Comment obtenir l’accès à l’API TikTok Shop ?

Inscrivez-vous dans TikTok Shop Partner Center, créez une application dans App & Service et activez les scopes API nécessaires à vos fonctionnalités. La page de détails de l’application vous fournit les valeurs app_key, app_secret et service_id. Chaque vendeur autorise ensuite votre application via un lien d’autorisation, puis vous échangez l’auth_code obtenu contre un token d’accès et un token de rafraîchissement.

Combien de temps un token d’accès TikTok Shop reste-t-il valide ?

Par défaut, un token d’accès est valide pendant 7 jours. La réponse contient access_token_expire_in sous forme d’horodatage Unix. Le token de rafraîchissement expire à la fin de la durée d’autorisation accordée par le vendeur. Rafraîchissez-le selon un calendrier avant son expiration via l’endpoint de rafraîchissement sur auth.tiktok-shops.com.

Pourquoi l’API TikTok Shop indique-t-elle que ma signature est invalide ?

Les causes habituelles sont une clé ou un secret d’application incorrect, l’inclusion du token d’accès dans la chaîne signée, la resérialisation du corps JSON après la signature, l’oubli du chemin de la requête, l’utilisation de SHA-256 seul au lieu de HMAC-SHA256 ou un horodatage situé en dehors de la fenêtre comprise entre 5 minutes avant et 30 secondes après l’horloge de la plateforme. Signez exactement les octets que vous envoyez.

Quelles sont les limites de débit de l’API TikTok Shop ?

Il n’existe pas de limite fixe unique. TikTok utilise une allocation dynamique de QPS fondée notamment sur le nombre de boutiques autorisées, le type d’endpoint et la charge de la plateforme. Les pages de référence des endpoints prévalent lorsqu’elles indiquent une limite. La limitation apparaît sous forme de HTTP 429 ou du code métier 36009002. Utilisez des files par couple application-boutique, des endpoints par lots et un backoff exponentiel avec jitter respectant Retry-After.

Dois-je utiliser les webhooks TikTok Shop ou le polling ?

Utilisez les deux. Les webhooks fournissent des événements presque en temps réel, mais la livraison s’effectue au moins une fois, doit être confirmée par une réponse 200 vide sous 3 secondes et s’arrête après le quatrième échec de nouvelle tentative. TikTok recommande de réconcilier les données critiques, comme les commandes, colis, produits et retours, avec une interrogation planifiée de l’API.

Restez informé avec Netalith

Recevez des ressources de développement, des mises à jour produit et des offres spéciales directement dans votre boîte mail.