EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Como verificar o status de publicação de um post do TikTok pela API

O TikTok publica posts da API de forma assíncrona: a chamada de publicação retorna um share_id, e GET /business/publish/status/ com esse ID como publish_id informa em que ponto o post está. O status mostra PROCESSING_DOWNLOAD enquanto o TikTok baixa o arquivo, PUBLISH_COMPLETE quando o post passou pela moderação e foi publicado, ou FAILED com um motivo, como frame_rate_check_failed.

O easyCoexistence publica no TikTok com publish_tiktok_post e acompanha cada post com get_tiktok_publish_status, a partir do Claude, do ChatGPT ou do seu próprio código, para que sua IA veja o status do TikTok e qualquer motivo de falha como estão no momento.

3 min

Quanto tempo os IDs de post podem demorar após PUBLISH_COMPLETE; o TikTok recomenda repetir a consulta após três minutos se eles estiverem ausentes.

30 min

A estimativa geral do TikTok para baixar um arquivo de post de 1 GB; o tempo real depende do tamanho e da rede.

2 min

A espera mais comum, após o envio ser concluído, para um post ficar público; a moderação manual pode demorar mais.

1 hour

Tempo limite de download após o qual o TikTok falha um post com video_pull_failed ou photo_pull_failed.

Por que um post do TikTok precisa ser acompanhado?

Porque o TikTok o publica em segundo plano. A chamada de publicação inicia uma tarefa e retorna um share_id imediatamente; depois o TikTok baixa o arquivo pela URL, verifica o formato, faz a moderação e torna o post público. Um post ainda pode falhar depois que a própria chamada foi bem-sucedida.

Quais são os status?

GET /business/publish/status/ recebe o business_id da conta e o share_id como publish_id, e retorna um de quatro status:

  • PROCESSING_DOWNLOAD: o TikTok está baixando o conteúdo da URL.
  • PUBLISH_COMPLETE: o post passou pela moderação e foi publicado; post_ids lista o post quando ele já pode ser visto publicamente.
  • FAILED: a publicação parou, e reason indica o motivo.
  • SEND_TO_USER_INBOX: um rascunho foi enviado e o TikTok notificou a caixa de entrada do criador; vale apenas para rascunhos.

Quanto tempo leva a publicação?

O TikTok não informa um tempo fixo. O download depende do tamanho do arquivo e da rede, e a estimativa geral do TikTok é que 30 minutos bastam para um arquivo de 1 GB, com uma hora como limite. Depois disso, um post normalmente fica público em até 2 minutos, ou mais tarde quando precisa de moderação manual, e seu ID pode levar até três minutos a mais para aparecer no status.

O que significam os motivos de falha?

reason indica o que interrompeu o post. Alguns significam que o arquivo precisa mudar, outros que repetir a publicação pode funcionar:

  • file_format_check_failed, duration_check_failed, frame_rate_check_failed, picture_size_check_failed: o arquivo quebra uma regra de formato, e o TikTok marca esses casos como não repetíveis.
  • video_pull_failed, photo_pull_failed: o TikTok não conseguiu baixar o arquivo, ou não o fez dentro da hora; repita quando a URL estiver acessível publicamente.
  • internal: parte do serviço do TikTok estava indisponível, e repetir a publicação é seguro.
  • spam_risk_too_many_posts, spam_risk, spam_risk_text: o TikTok interrompeu o post por volume, comportamento ou conteúdo da legenda.
  • auth_removed: a conta retirou o acesso do app durante o processamento, e o TikTok recomenda não repetir.
  • spam_risk_user_banned_from_posting: a conta está banida de fazer novos posts.

Para que serve o ID do post?

Para encontrar o post depois. A referência do TikTok passa os IDs de post para /business/video/list/ em filters.video_ids para ler as métricas dos posts. As chamadas de comentários, por sua vez, recebem o item_id de um post 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 um post?

publish_tiktok_post retorna o share_id do TikTok com uma observação de que o TikTok está processando o post, e get_tiktok_publish_status recebe esse share_id e retorna o status do TikTok como está no momento, com o motivo quando houver um. Peça à sua IA que verifique de novo após alguns minutos, em vez de consultar logo em seguida.

Erros comuns

  • Publicar de novo porque nada apareceu ainda. A primeira chamada apenas iniciou a tarefa, então verifique o status antes de enviar o post uma segunda vez.
  • Tratar PUBLISH_COMPLETE sem post_ids como erro. Os IDs podem levar até três minutos a mais, então verifique novamente nesse momento.
  • Repetir uma falha de formato com o mesmo arquivo. file_format_check_failed e as demais falhas de verificação exigem um arquivo corrigido.
  • Tirar a URL do ar durante o download. O TikTok falha o post com video_pull_failed ou photo_pull_failed quando não consegue baixar o arquivo.
Fazendo isso com o EasyCoexistence

De US$ 9 a US$ 0.75 por conexão por mês, com redução conforme você adiciona conexões, e os primeiros 3 dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

O que é um share_id no TikTok?

O ID de uma tarefa de publicação, retornado pelos endpoints de publicação de vídeo e de foto. Ele entra na chamada de status como publish_id.

Existe um webhook para o status de publicação no TikTok?

Sim. Um app inscrito com event_type VIDEO por meio de /business/webhook/update/ recebe os eventos de publicação de posts do TikTok, como post.publish.failed com seu motivo e publish_id, no lugar de consultas repetidas de status.

Por que um post publicado ainda não tem ID de post?

O TikTok pode levar até três minutos após PUBLISH_COMPLETE para retornar post_ids, e só os retorna para posts visíveis publicamente.

Um post do TikTok que falhou pode ser repetido?

Depende do motivo. Falhas de download e internas podem ser repetidas; falhas de formato, duração, taxa de quadros e tamanho de imagem exigem um arquivo corrigido.

Continue lendo

Conecte seu primeiro canal em dois minutos.

Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorado 24/7

Verificado em