Plages horaires

Différentes parties de l'API utilisent différents filtres de date. Ce guide vous sert d'aide-mémoire : choisissez celui qui convient au point de terminaison que vous appelez, et ne les mélangez pas.

En bref#

L'erreur la plus courante : envoyer date_de_début / date_de_fin aux côtés de période sur les points de terminaison de TikTok Shop. À éviter : ces champs entrent en conflit avec le mappage des revenus sensible aux points de séparation en amont et filtrent silencieusement la plupart des données. Passer seulement période sauf indication contraire dans la documentation relative à un point de terminaison spécifique.

TikTok Shop période#

Utilisé par découvrir, compter, agrégats détaillés, histoire, ainsi que la plupart des points d'extrémité comportant des valeurs métriques sous /api/v1/tiktok-shop/.

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/products/explore?country=US&period=30d&limit=20"

• Gâter période en tant que ficelle opaque qui reprend l'interface utilisateur du filtre intégré à l'application (7d, 30d, 90d, …). Le backend l'associe à des champs spécifiques à la période, tels que chiffre d'affaires_30j, taux_de_croissance_du_chiffre_d'affaires_sur_7_jours, etc.
• Faire pas envoyer également date_de_début / date_de_fin. L'API TikTok Shop ne les intègre pas dans le flux d'exploration : leur envoi peut déclencher en amont un comportement restreint de type « vu pour la première fois au cours des N derniers jours » et ne renvoyer qu'une infime partie du catalogue.
• Clés de tri (tri=) suivent la même période — en passant tri=chiffre d'affaires avec durée = 7 jours devient chiffre d'affaires_7j en amont.
• Pour les chiffres d'affaires globaux (par exemple, le total des ventes d'un magasin), la période détermine chiffre d'affaires.{key} champ que vous devez lire dans la réponse.

Points de terminaison des événements de visite (produit-autres-visites, catégorie-visite-événements, détails-visite-événements)#

Celles-ci acceptent un ensemble plus restreint :

La réponse comprend étiquette_période (par exemple « Au cours des 30 derniers jours ») afin que vous puissiez l'afficher sans avoir à l'analyser.

Suivi des marques date_range#

Utilisé par les itinéraires du tableau de bord tels que /api/marques/publicités, /api/marques/textes-publicitaires, /api/brands/titres-publicitaires, /api/brands/ad-hooks, /api/marques/personnages, /api/marques/thèmes, ainsi que les autres onglets consacrés aux marques (session).

GET /api/brands/ads?id={page_id}&date_range=30d
GET /api/brands/ad-copies?id={page_id}&date_range=custom&date_from=2026-01-01&date_to=2026-03-31

Valeurs acceptées (même logique que le sélecteur de date du Brand Tracker dans l'application) :

Quelques conseils :

• Les trois mêmes paramètres (date_range, date_de_début, date_to) à tous les onglets détaillés de la marque. Une fois que vous avez défini un filtre de date pour l'utilisateur, réutilisez-le à chaque requête que vous effectuez pour cette session de marque.
• en direct est le seulement valeur basée sur « dernière consultation », et non sur « date de création ». Ne la confondez pas avec 7d.
• personnalisé sans les deux date_de_début et date_to revient alors au « filtre sans date ».

La surface détaillée de la marque est uniquement en session (navigateur connecté), cette section s'applique donc lorsque vous dupliquez le tableau de bord, et non lorsque vous utilisez GET /api/v1/brands seul. Référence complète : Marques et suivi des marques.

GET /api/v1/tiktok-shop/products#

Cette route est une route de liste plate qui accepte un petit ensemble de paramètres GET, notamment des dates explicites :

GET /api/v1/tiktok-shop/products
  ?country=US
  &date_from=2026-03-01
  &date_to=2026-03-31
  &search=mascara
  &min_price=10&max_price=50
  &min_sales=100
  &min_rating=4

• Les deux date_de_début et date_to sont J-m-a chaînes.
• L'un ou l'autre peut être omis ; dans ce cas, le module en amont applique une valeur par défaut appropriée.
• Voici le seulement Chemin d'accès aux fiches produits simples sur TikTok Shop date_de_début / date_to sont des paramètres de premier ordre. Dans tous les autres cas, privilégiez période.

Pourquoi le mélange des paramètres de temps ne fonctionne pas#

Une erreur courante : copier une requête « products explore » et ajouter date_de_début=01/01/2026 en pensant que cela réduira la fenêtre. Ce qui se passe en réalité :

1. Le gestionnaire « explore » conserve période = 30 jours (par défaut).
2. Il transmet également votre date_de_début / date_de_fin.
3. Upstream interprète cela comme signifiant « observé pour la première fois entre ces dates ».
4. Vous récupérez environ 5 % du catalogue — uniquement les articles indexés pour la première fois pendant cette période précise.

Solution : sélectionnez un mécanisme par requête. Si période Si cela répond à vos besoins, utilisez-le tel quel. Si vous avez réellement besoin d'une plage personnalisée, suivez les instructions fournies dans la documentation date_de_début / date_to (le suivi des marques, l'appartement produits (liste, bibliothèque d'annonces).

Arbre de décision rapide#

• Appel /api/v1/tiktok-shop/... explorer / compter / détailler / historique ? → durée=7j|30j|90j.
• Appel /api/v1/tiktok-shop/products (annonce immobilière) ? → date_de_début, date_to.
• Appel /api/v1/tiktok-shop/...visit-events* ou produit-autres-visites? → période=7j|30j|tout.
• Appel /api/brands/* (session du tableau de bord) ? → date_range, ainsi que date_de_début + date_to si date_range=personnalisé. (Liste suivie avec une clé API : GET /api/v1/brands — non date_range (sur cet itinéraire.)
• Appel /api/v1/adlibrary ou /api/adlibrary (Publicités Meta) ? → voir Bibliothèque publicitaire Meta.