Intervalos de tiempo

Las distintas partes de la API utilizan diferentes filtros de fecha. Esta guía es una referencia rápida: elige el filtro adecuado para el punto final al que estás accediendo y no los mezcles.

De un vistazo#

El error más común: enviar fecha_de_inicio / fecha de finalización junto a período en los puntos finales de TikTok Shop. No lo hagas: esos campos entran en conflicto con la asignación de ingresos sensible a los puntos que se realiza en las etapas anteriores y filtran de forma silenciosa la mayor parte de los datos. Pasa solo período a menos que la documentación de un punto final concreto indique lo contrario.

TikTok Shop período#

Utilizado por explorar, recuento, detalles de los agregados, historia, y la mayoría de los puntos finales que incluyen métricas en /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"

• Dale un capricho período como un cordón opaco que reproduce la interfaz de usuario del filtro de la aplicación (7d, 30d, 90d, …). El backend lo asigna a campos específicos de cada período, como ingresos_30d, tasa_de_crecimiento_de_los_ingresos_7d, etc.
• Haz no enviar también fecha_de_inicio / fecha de finalización. La API de TikTok Shop no las incluye en el flujo de exploración; enviarlas puede activar un comportamiento limitado del tipo «visto por primera vez en los últimos N días» en las etapas anteriores y devolver solo una pequeña parte del catálogo.
• Claves de ordenación (ordenar por=) siguen el mismo periodo — pasando ordenar=ingresos con periodo=7 días se convierte en ingresos_7d aguas arriba.
• En el caso de las cifras de ingresos totales (por ejemplo, los totales de la tienda), el periodo determina qué ingresos.{key} campo que debes leer en la respuesta.

Puntos finales de eventos de visita (producto-otras-visitas, categoría-visita-eventos, detalles-visita-eventos)#

Estos admiten un conjunto más limitado:

La respuesta incluye etiqueta de período (p. ej., «Últimos 30 días») para que puedas mostrarlo sin necesidad de analizarlo.

Rastreador de marcas fecha_rango#

Se utiliza en rutas del panel de control como /api/marcas/anuncios, /api/marcas/textos-publicitarios, /api/marcas/titulares-publicitarios, /api/marcas/ad-hooks, /api/marcas/personajes, /api/marcas/temas, y las demás pestañas de detalles de la marca (sesión).

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

Valores admitidos (con la misma semántica que el selector de fechas del Brand Tracker en la aplicación):

Algunos consejos:

• Los mismos tres parámetros (fecha_rango, fecha_de_inicio, fecha_hasta) aplícalo a todas las pestañas de detalles de la marca. Una vez que tengas un filtro de fecha para el usuario, reutilízalo en cada solicitud que realices para esa sesión de marca.
• en directo es el solo valor basado en «visto por última vez», no en «iniciado». No lo confundas con 7d.
• personalizado sin ambos fecha_de_inicio y fecha_hasta vuelve al «filtro sin fecha».

La superficie con los detalles de la marca es solo para la sesión (navegador con sesión iniciada), por lo que esta sección se aplica cuando se duplica el panel de control, no cuando se utiliza GET /api/v1/marcas solo. Referencia completa: Marcas y seguimiento de marcas.

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

Esta ruta es un punto final de listado plano que admite un pequeño conjunto de parámetros GET, incluidas fechas explícitas:

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

• Ambos fecha_de_inicio y fecha_hasta son A-M-D cadenas.
• Cualquiera de los dos puede omitirse; en tal caso, el componente anterior aplica un valor predeterminado adecuado.
• Esto es el solo Ruta de la lista plana de TikTok Shop donde fecha_de_inicio / fecha_hasta son parámetros de primera clase. En cualquier otra ruta, es preferible período.

¿Por qué sale mal mezclar parámetros de tiempo?#

Un error muy común: copiar una solicitud de «exploración de productos» y añadir fecha_inicio=2026-01-01 pensando que así se reducirá el margen. Lo que ocurre en realidad:

1. El controlador «explore» mantiene período=30 días (predeterminado).
2. Además, reenvía tu fecha_de_inicio / fecha de finalización.
3. Upstream lo interpreta como «visto por primera vez entre esas fechas».
4. Obtienes aproximadamente el 5 % del catálogo: solo los artículos que se rastrearon por primera vez en ese intervalo de tiempo concreto.

Solución: selecciona uno mecanismo por solicitud. Si período Si esto cubre tus necesidades, úsalo tal cual. Si realmente necesitas un rango personalizado, sigue las instrucciones que se indican en la documentación. fecha_de_inicio / fecha_hasta (el rastreador de marcas, el piso productos anuncio, la biblioteca de anuncios).

Árbol de decisión rápido#

• Llamada /api/v1/tiktok-shop/... ¿Explorar / Contar / Detalles / Historia? → período=7 días|30 días|90 días.
• Llamada /api/v1/tiktok-shop/products (anuncio de piso)? → fecha_de_inicio, fecha_hasta.
• Llamada /api/v1/tiktok-shop/...visit-events* o producto-otras-visitas? → período=7 días|30 días|todos.
• Llamada /api/marcas/* (¿sesión del panel de control)? → fecha_rango, además de fecha_de_inicio + fecha_hasta si date_range=personalizado. (Lista de seguimiento con una clave API: GET /api/v1/marcas — no fecha_rango (en esa ruta.)
• Llamada /api/v1/adlibrary o /api/adlibrary (¿Anuncios de Meta)? → ver Biblioteca de anuncios de Meta.