Cómo consultar el estado de una publicación de TikTok por la API
TikTok publica las publicaciones hechas por la API de forma asíncrona: la llamada de publicación devuelve un share_id, y GET /business/publish/status/ con ese ID como publish_id indica en qué punto está la publicación. El estado es PROCESSING_DOWNLOAD mientras TikTok descarga el archivo, PUBLISH_COMPLETE cuando la publicación ha superado la moderación y se ha publicado, o FAILED con un motivo como frame_rate_check_failed.
easyCoexistence publica en TikTok con publish_tiktok_post y hace seguimiento de cada publicación con get_tiktok_publish_status, desde Claude, ChatGPT o tu propio código, para que tu IA vea el estado de TikTok y cualquier motivo de fallo tal como están.
Cuánto tardan los post IDs tras PUBLISH_COMPLETE; TikTok indica reintentar tras tres minutos si faltan.
La estimación general de TikTok para descargar un archivo de publicación de 1 GB; el tiempo real depende del tamaño y de la red.
La espera habitual más larga, una vez completada la subida, para que una publicación sea pública; la moderación manual puede tardar más.
Tiempo límite de descarga tras el cual TikTok falla una publicación con video_pull_failed o photo_pull_failed.
¿Por qué hay que hacer seguimiento de una publicación de TikTok?
Porque TikTok la publica en segundo plano. La llamada de publicación inicia una tarea y devuelve un share_id de inmediato; después TikTok descarga el archivo desde su URL, comprueba el formato, aplica la moderación y hace pública la publicación. Una publicación puede fallar aunque la llamada en sí haya tenido éxito.
¿Qué estados hay?
GET /business/publish/status/ recibe el business_id de la cuenta y el share_id como publish_id, y devuelve uno de cuatro estados:
PROCESSING_DOWNLOAD: TikTok está descargando el contenido desde su URL.PUBLISH_COMPLETE: la publicación ha superado la moderación y se ha publicado;post_idsla incluye en cuanto es visible públicamente.- FAILED: la publicación se ha detenido, y reason indica el motivo.
SEND_TO_USER_INBOX: se subió un borrador y TikTok notificó a la bandeja de entrada del creador; se aplica solo a borradores.
¿Cuánto tarda la publicación?
TikTok no da un tiempo fijo. La descarga depende del tamaño del archivo y de la red, y la estimación general de TikTok es que 30 minutos bastan para un archivo de 1 GB, con una hora como límite. Después, una publicación normalmente pasa a ser pública en 2 minutos, o más tarde si necesita moderación manual, y su post ID puede tardar hasta tres minutos más en aparecer en el estado.
¿Qué significan los motivos de fallo?
reason indica qué detuvo la publicación. Algunos significan que el archivo debe cambiar, otros que reintentar puede funcionar:
file_format_check_failed,duration_check_failed,frame_rate_check_failed,picture_size_check_failed: el archivo incumple una regla de formato, y TikTok marca estos casos como no reintentables.video_pull_failed,photo_pull_failed: TikTok no pudo descargar el archivo, o no lo hizo en la hora; reintentar cuando la URL sea accesible públicamente.- internal: parte del servicio de TikTok no estaba disponible, y reintentar está bien.
spam_risk_too_many_posts,spam_risk,spam_risk_text: TikTok detuvo la publicación por volumen, comportamiento o contenido del texto de la descripción.auth_removed: la cuenta retiró el acceso de la app durante el procesamiento, y TikTok indica no reintentar.spam_risk_user_banned_from_posting: la cuenta tiene prohibido hacer nuevas publicaciones.
¿Para qué sirve el post ID?
Para encontrar la publicación después. La referencia de TikTok pasa los post IDs a /business/video/list/ en filters.video_ids para leer las métricas de las publicaciones. Las llamadas de comentarios, por su parte, toman el item_id de una publicación de la lista de videos de la cuenta como video_id, que es también lo que las herramientas de comentarios de easyCoexistence reciben como post_id.
¿Cómo sigue easyCoexistence una publicación?
publish_tiktok_post devuelve el share_id de TikTok con una nota de que TikTok está procesando la publicación, y get_tiktok_publish_status recibe ese share_id y devuelve el estado de TikTok tal como está, con el motivo cuando lo hay. Pide a tu IA que vuelva a comprobarlo tras unos minutos en lugar de hacerlo de inmediato.
Errores comunes
- Volver a publicar porque aún no aparece nada. La primera llamada solo inició la tarea, así que consulta su estado antes de enviar la publicación por segunda vez.
- Tratar PUBLISH_COMPLETE sin post_ids como un error. Los IDs pueden tardar hasta tres minutos más, así que vuelve a comprobarlo entonces.
- Reintentar un fallo de formato con el mismo archivo. file_format_check_failed y los demás fallos de comprobación necesitan un archivo corregido.
- Retirar la URL durante la descarga. TikTok falla la publicación con video_pull_failed o photo_pull_failed cuando no puede obtener el archivo.
De US$ 9 a US$ 0.75 por conexión al mes, bajando a medida que añades conexiones, con los primeros 3 días gratis.
Preguntas frecuentes
¿Qué es un share_id en TikTok?
El ID de una tarea de publicación, devuelto por los endpoints de publicación de video y de foto. Se pasa a la llamada de estado como publish_id.
¿Existe un webhook para el estado de publicación de TikTok?
Sí. Una app suscrita con event_type VIDEO mediante /business/webhook/update/ recibe los eventos de publicación de TikTok, como post.publish.failed con su motivo y publish_id, en lugar de hacer consultas repetidas de estado.
¿Por qué una publicación ya publicada aún no tiene post ID?
TikTok puede tardar hasta tres minutos después de PUBLISH_COMPLETE en devolver post_ids, y solo los devuelve para publicaciones visibles públicamente.
¿Se puede reintentar una publicación de TikTok fallida?
Depende del motivo. Los fallos de descarga e internos pueden reintentarse; los de formato, duración, frecuencia de fotogramas y tamaño de imagen necesitan un archivo corregido.
Sigue leyendo
Conecta tu primer canal en dos minutos.
Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.
- 3 días gratis
- Cancela cuando quieras
- Solo APIs oficiales
- Monitorizado 24/7
Verificado el