Docs
Ctrl+K Rechercher Alt+[Alt+] Guides
Obtenir une clé API

Guides

Authentification

Chaque point de terminaison programmatique avec facturation au trafic accepte une seule clé API, qui peut être transmise de trois manières différentes. Cette page explique où obtenir cette clé, comment la transmettre et comment le serveur l'associe à votre compte.

Envoi de votre

Le serveur vérifie trois emplacements, dans cet ordre. La première valeur non vide l'emporte.

Où Exemple Remarques
Clé X-API en-tête Clé X-API : wh_… Recommandé. Nom d'en-tête insensible à la casse.
Autorisation en-tête Autorisation : au porteur wh_… Programme « Standard Bearer ». Tout autre élément (par exemple, De base) est ignoré.
clé_API paramètre de requête ?api_key=wh_… À n'utiliser qu'en dernier recours. Évitez-le pour tout contenu sensible : il se retrouve dans les URL, les journaux du serveur et l'historique du navigateur. 
curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/credits"

curl -sS \
  -H "Authorization: Bearer $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/credits"

curl -sS "{origin}/api/v1/tiktok-shop/credits?api_key=$WH_API_KEY"

Ces trois méthodes sont équivalentes pour le routage ; choisissez celle qui vous semble la plus simple dans votre client HTTP.

D'où vient la clé

Les clés sont gérées exclusivement depuis la page API de l'application :

  • GET /api — afficher votre clé actuelle, la copier, la régénérer.
  • POST /api/regenerate — régénération programmatique (connexion à la session requise).

Une clé ressemble à wh_ suivi de 48 caractères hexadécimaux. Considérez-le comme un mot de passe : il vous donne accès à l'intégralité de votre quota mensuel de l'API.

La régénération, c'est immédiat et destructeur. La clé précédente cesse de fonctionner dès que vous effectuez une régénération, et tous les clients qui l'utilisent encore recevront 401 Accès non autorisé. Faire pivoter lorsque :

  • Vous soupçonnez une fuite.
  • Un collègue ou un sous-traitant ayant accès aux locaux quitte l'entreprise.
  • Vous avez enregistré une modification dans le système de contrôle de version par inadvertance.

Sinon, les clés n'ont pas de date d'expiration : elles restent valides jusqu'à ce que vous les régénériez ou que votre forfait soit rétrogradé.

du plan n°

Une fois qu'une clé est associée à un compte, le serveur vérifie que l'accès à l'API est activé pour ce compte. Si ce n'est pas le cas, vous recevez une erreur HTTP 403, même si le format de la clé est valide. Une baisse de niveau ou une résiliation peut entraîner la suppression immédiate de l'accès.

d'équipe et d'organisation#

Les clés sont attribuées à chaque utilisateur. Dans le cadre d'une configuration d'équipe, l'utilisation et l'accès sont régis par les règles de facturation de votre organisation au sein du produit ; consultez la page de l'API et le tableau de bord de l'application pour obtenir des informations fiables concernant votre licence.

par session vs authentification par clé API#

Les parcours WinningHunter se déclinent en trois versions. Assurez-vous de vous adresser à la bonne.

Préfixe de route Auteur Quand l'utiliser
/api/v1/tiktok-shop/* Clé API (Clé X-API) Toutes les intégrations programmatiques / externes. Passe par les crédits et la limite de requêtes.
/api/tiktok-shop/*, /api/product-detail/*, etc. Session de navigation connectée (cookies) Utilisés uniquement par l'application web. Il s'agit de pas la page des clés API — utilisation /api/v1/tiktok-shop/* pour les intégrations.
/api/v1/adlibrary, /api/v1/magic-ai, /api/v1/store-tracker, /api/v1/store-explorer, /api/v1/marques Clé API L'espace programmatique hors TikTok. Mêmes modalités de facturation que /api/v1/tiktok-shop/*. Le fichier sans version /api/<x> les formulaires sont conservés en tant qu'alias rétrocompatibles pour bibliothèque de publicités, suivi des magasins, et explorateur de magasins uniquement — les nouvelles intégrations doivent utiliser les chemins d'accès de la version 1. /api/magic-ai et /api/marques (non v1) sont tableau de bord, session, itinéraires, et non l'interface de la clé API, car les pages du tableau de bord continuent d'envoyer des requêtes POST/GET à ces URL ; les clients de la clé doivent utiliser /api/v1/magic-ai et /api/v1/marques.

Si vous écrivez un script ou une intégration backend, vous souhaitez presque toujours /api/v1/tiktok-shop/... ainsi que les quelques itinéraires non TikTok mentionnés ci-dessus. L'ensemble du parcours est documenté dans le Référence API ainsi que les guides thématiques (TikTok Shop, bibliothèque publicitaire Meta, marques, etc.).

Vérification du de la clé#

La façon la moins coûteuse de réaliser un test de fumée est GET /api/v1/tiktok-shop/credits — elle renvoie le solde de crédits actuel et coûte 1 crédit :

curl -i \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/credits"

A 200 « with JSON » signifie : clé valide, forfait correct, limite de débit et crédits en ordre. Pour tout autre statut, voir Erreurs.

contrôle de sécurité#

  • Conservez les clés dans des variables d'environnement ou dans un magasin d'identifiants sécurisé — jamais dans le code côté client, les applications mobiles ou les paquets de navigateur.
  • Utilisation Clé X-API ou Autorisation : au porteur, et non le paramètre de requête, dans la mesure du possible.
  • Procéder à une rotation après tout incident, à chaque changement dans la composition de l'équipe et au moins une fois par an.
  • Ne partagez pas les clés entre les environnements : générez-en une par compte de service et renouvelez-les indépendamment.