AccediInizia la prova gratuita
easyCoexistence API ufficiali

Come controllare lo stato di pubblicazione di un post TikTok tramite l'API

TikTok pubblica i post via API in modo asincrono: la chiamata di pubblicazione restituisce uno share_id, e GET /business/publish/status/ con quell'ID come publish_id indica a che punto si trova il post. Lo stato è PROCESSING_DOWNLOAD mentre TikTok scarica il file, PUBLISH_COMPLETE quando il post ha superato la moderazione ed è stato pubblicato, oppure FAILED con un motivo come frame_rate_check_failed.

easyCoexistence pubblica su TikTok con publish_tiktok_post e segue ogni post con get_tiktok_publish_status, da Claude, ChatGPT o dal tuo codice, così la tua AI vede lo stato di TikTok e l'eventuale motivo di errore così come sono.

3 min

Quanto possono volerci gli ID dei post dopo PUBLISH_COMPLETE; TikTok consiglia di riprovare dopo tre minuti se mancano.

30 min

La stima generale di TikTok per scaricare il file di un post da 1 GB; il tempo reale dipende dalle dimensioni e dalla rete.

2 min

L'attesa più lunga abituale, una volta completato il caricamento, perché un post diventi pubblico; la moderazione manuale può richiedere più tempo.

1 hour

Timeout di download, oltre il quale TikTok fa fallire un post con video_pull_failed o photo_pull_failed.

Perché bisogna seguire un post TikTok?

Perché TikTok lo pubblica in background. La chiamata di pubblicazione avvia un'attività e restituisce subito uno share_id; poi TikTok scarica il file dal suo URL, controlla il formato, esegue la moderazione e rende pubblico il post. Un post può comunque fallire anche se la chiamata stessa è andata a buon fine.

Quali stati esistono?

GET /business/publish/status/ richiede il business_id dell'account e lo share_id come publish_id, e restituisce uno di quattro stati:

  • PROCESSING_DOWNLOAD: TikTok sta scaricando il contenuto dal suo URL.
  • PUBLISH_COMPLETE: il post ha superato la moderazione ed è stato pubblicato; post_ids lo elenca non appena è visibile pubblicamente.
  • FAILED: la pubblicazione si è interrotta, e reason ne spiega il motivo.
  • SEND_TO_USER_INBOX: una bozza è stata caricata e TikTok ha notificato l'inbox del creator; vale solo per le bozze.

Quanto dura la pubblicazione?

TikTok non indica un tempo fisso. Il download dipende dalle dimensioni del file e dalla rete; la stima generale di TikTok è che 30 minuti bastino per un file da 1 GB, con un'ora come limite. Dopo, un post di norma diventa pubblico entro 2 minuti, oppure più tardi se richiede la moderazione manuale, e il suo ID può impiegare fino a tre minuti in più per comparire nello stato.

Cosa significano i motivi di errore?

reason indica che cosa ha bloccato il post. Alcuni richiedono di modificare il file, altri indicano che un nuovo tentativo può funzionare:

  • file_format_check_failed, duration_check_failed, frame_rate_check_failed, picture_size_check_failed: il file viola una regola sul formato, e TikTok li segna come non recuperabili con un nuovo tentativo.
  • video_pull_failed, photo_pull_failed: TikTok non è riuscito a scaricare il file, o non lo ha fatto entro l'ora; riprova quando l'URL è raggiungibile pubblicamente.
  • internal: una parte del servizio di TikTok non era disponibile, e un nuovo tentativo va bene.
  • spam_risk_too_many_posts, spam_risk, spam_risk_text: TikTok ha bloccato il post per volume, comportamento o contenuto della didascalia.
  • auth_removed: l'account ha revocato l'accesso dell'app durante l'elaborazione, e TikTok dice di non riprovare.
  • spam_risk_user_banned_from_posting: l'account è escluso dalla pubblicazione di nuovi post.

A cosa serve l'ID del post?

A ritrovare il post in seguito. Il riferimento di TikTok passa gli ID dei post a /business/video/list/ in filters.video_ids per leggerne le metriche. Le chiamate sui commenti, invece, prendono l'item_id di un post dalla lista video dell'account come video_id, che è anche ciò che gli strumenti di commento di easyCoexistence ricevono come post_id.

Come segue easyCoexistence un post?

publish_tiktok_post restituisce lo share_id di TikTok con una nota che TikTok sta elaborando il post, e get_tiktok_publish_status prende quello share_id e restituisce lo stato di TikTok così com'è in quel momento, con il motivo quando c'è. Chiedi alla tua AI di ricontrollare dopo qualche minuto, invece che subito.

Errori comuni

  • Pubblicare di nuovo perché non è ancora comparso nulla. La prima chiamata ha solo avviato l'attività, quindi controlla lo stato prima di inviare di nuovo il post.
  • Considerare PUBLISH_COMPLETE senza post_ids come un errore. Gli ID possono richiedere fino a tre minuti in più, quindi ricontrolla allora.
  • Riprovare un errore di formato con lo stesso file. file_format_check_failed e gli altri controlli falliti richiedono un file corretto.
  • Rendere irraggiungibile l'URL durante il download. TikTok fa fallire il post con video_pull_failed o photo_pull_failed quando non riesce a recuperare il file.
Farlo con EasyCoexistence

Da US$ 9 a US$ 0,75 per connessione al mese, con prezzo che scende man mano che aggiungi connessioni, e i primi 3 giorni di prova gratuita.

Domande frequenti

Cos'è uno share_id su TikTok?

L'ID di un'attività di pubblicazione, restituito dagli endpoint di pubblicazione di video e foto. Va nella chiamata di stato come publish_id.

C'è un webhook per lo stato di pubblicazione su TikTok?

Sì. Un'app iscritta con event_type VIDEO tramite /business/webhook/update/ riceve gli eventi di pubblicazione dei post di TikTok, come post.publish.failed con il suo reason e publish_id, al posto dei controlli di stato ripetuti.

Perché un post pubblicato non ha ancora un ID?

TikTok può impiegare fino a tre minuti dopo PUBLISH_COMPLETE per restituire post_ids, e li restituisce solo per i post visibili pubblicamente.

Un post TikTok fallito si può riprovare?

Dipende dal motivo. Gli errori di download e interni possono essere ritentati; gli errori su formato, durata, frequenza dei fotogrammi e dimensione dell'immagine richiedono un file corretto.

Continua a leggere

Collega il tuo primo canale in due minuti.

Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.

  • 3 giorni gratis
  • Disdici quando vuoi
  • Solo API ufficiali
  • Monitorato 24/7

Verificato il