Como verificar o estado de publicação de uma publicação do TikTok pela API
O TikTok publica as publicações da API de forma assíncrona: a chamada de publicação devolve um share_id, e GET /business/publish/status/ com esse ID como publish_id indica em que ponto está a publicação. O estado é PROCESSING_DOWNLOAD enquanto o TikTok transfere o ficheiro, PUBLISH_COMPLETE quando a publicação passa a moderação e é publicada, ou FAILED com um motivo, como frame_rate_check_failed.
A easyCoexistence publica no TikTok com publish_tiktok_post e acompanha cada publicação com get_tiktok_publish_status, através do Claude, do ChatGPT ou do seu próprio código, para que a sua IA veja o estado do TikTok e qualquer motivo de falha tal como estão.
Quanto tempo os IDs das publicações podem demorar após PUBLISH_COMPLETE; o TikTok indica voltar a tentar ao fim de três minutos se estiverem em falta.
Estimativa geral do TikTok para a transferência de um ficheiro de publicação de 1 GB; o tempo real depende do tamanho e da rede.
Espera habitual mais longa, depois de o carregamento concluir, para uma publicação ficar pública; a moderação manual pode demorar mais.
Tempo limite de transferência após o qual o TikTok falha uma publicação com video_pull_failed ou photo_pull_failed.
Porque é que uma publicação do TikTok precisa de ser acompanhada?
Porque o TikTok a publica em segundo plano. A chamada de publicação inicia uma tarefa e devolve de imediato um share_id; depois, o TikTok transfere o ficheiro a partir do seu URL, verifica o formato, faz a moderação e torna a publicação pública. Uma publicação pode ainda falhar depois de a própria chamada ter tido êxito.
Que estados existem?
GET /business/publish/status/ recebe o business_id da conta e o share_id como publish_id, e devolve um de quatro estados:
PROCESSING_DOWNLOAD: o TikTok está a transferir o conteúdo a partir do seu URL.PUBLISH_COMPLETE: a publicação passou a moderação e foi publicada;post_idsindica-a assim que for visível ao público.- FAILED: a publicação parou, e reason indica o motivo.
SEND_TO_USER_INBOX: um rascunho foi carregado e o TikTok notificou a caixa de entrada do criador; aplica-se apenas a rascunhos.
Quanto tempo demora a publicação?
O TikTok não indica um tempo fixo. A transferência depende do tamanho do ficheiro e da rede, e a estimativa geral do TikTok é de 30 minutos para um ficheiro de 1 GB, com uma hora como limite. Depois disso, a publicação costuma ficar pública em 2 minutos, ou mais tarde quando precisa de moderação manual, e o seu ID pode demorar até mais três minutos a aparecer no estado.
O que significam os motivos de falha?
reason indica o que parou a publicação. Alguns exigem alterar o ficheiro, outros indicam que voltar a tentar pode resultar:
file_format_check_failed,duration_check_failed,frame_rate_check_failed,picture_size_check_failed: o ficheiro viola uma regra de formato, e o TikTok marca estes casos como sem possibilidade de nova tentativa.video_pull_failed,photo_pull_failed: o TikTok não conseguiu transferir o ficheiro, ou não o fez dentro da hora; volte a tentar quando o URL estiver publicamente acessível.- internal: parte do serviço do TikTok esteve indisponível, e voltar a tentar é adequado.
spam_risk_too_many_posts,spam_risk,spam_risk_text: o TikTok parou a publicação por volume, comportamento ou conteúdo da legenda.auth_removed: a conta retirou o acesso da aplicação durante o processamento, e o TikTok indica que não se deve voltar a tentar.spam_risk_user_banned_from_posting: a conta está impedida de fazer novas publicações.
Para que serve o ID da publicação?
Para encontrar a publicação mais tarde. A referência do TikTok passa os IDs das publicações para /business/video/list/ em filters.video_ids, para ler as métricas das publicações. As chamadas de comentários, por seu lado, recebem o item_id de uma publicação da lista de vídeos da conta como video_id, que é também o que as ferramentas de comentários do easyCoexistence recebem como post_id.
Como o easyCoexistence acompanha uma publicação?
publish_tiktok_post devolve o share_id do TikTok com uma nota de que o TikTok está a processar a publicação, e get_tiktok_publish_status recebe esse share_id e devolve o estado do TikTok tal como está, com o motivo quando existe. Peça à sua IA que verifique de novo ao fim de alguns minutos, em vez de o fazer de imediato.
Erros comuns
- Publicar de novo porque ainda nada apareceu. A primeira chamada apenas iniciou a tarefa, por isso verifique o estado antes de voltar a enviar a publicação.
- Tratar PUBLISH_COMPLETE sem post_ids como um erro. Os IDs podem demorar até mais três minutos, por isso verifique de novo nessa altura.
- Voltar a tentar com o mesmo ficheiro após uma falha de formato. file_format_check_failed e as restantes falhas de verificação exigem um ficheiro corrigido.
- Tirar o URL do ar durante a transferência. O TikTok falha a publicação com video_pull_failed ou photo_pull_failed quando não consegue obter o ficheiro.
De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que adiciona ligações, com os primeiros 3 dias grátis.
Perguntas frequentes
O que é um share_id no TikTok?
O ID de uma tarefa de publicação, devolvido pelos endpoints de publicação de vídeo e de foto. Entra na chamada de estado como publish_id.
Existe um webhook para o estado de publicação no TikTok?
Sim. Uma aplicação subscrita com event_type VIDEO através de /business/webhook/update/ recebe os eventos de publicação de vídeos do TikTok, como post.publish.failed com o seu motivo e publish_id, em vez de verificações repetidas do estado.
Porque é que uma publicação já publicada ainda não tem ID?
O TikTok pode demorar até três minutos após PUBLISH_COMPLETE para devolver post_ids, e só os devolve para publicações visíveis ao público.
Uma publicação falhada no TikTok pode ser repetida?
Depende do motivo. Falhas de transferência e internas podem ser repetidas; falhas de formato, duração, taxa de fotogramas e tamanho da imagem exigem um ficheiro corrigido.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em