Integrazione API
API di pubblicazione TikTok per una distribuzione multi-account affidabile in coda
Distribuisci workflow di pubblicazione TikTok con tracciamento esplicito dello stato, orchestrazione compatibile con i retry e gestione consapevole della moderazione per team su scala di produzione.
Problema
Su larga scala, la distribuzione fallisce dove la pubblicazione è ancora manuale: le azioni di upload/pubblicazione diventano fragili tra molti account, pianificazioni e stati di moderazione.
Risultato con Ssemble
Ssemble supporta la generazione di contenuti e l'orchestrazione degli stati mentre il tuo livello di pubblicazione TikTok esegue pubblicazioni controllate con idempotenza, retry e stati dei job verificabili.
Elementi essenziali dell'implementazione
URL di base: https://aiclipping.ssemble.com/api/v1 (+ TikTok Open API for publish)
Architettura di integrazione (ingestione → elaborazione → polling/webhook → pubblicazione)
1) Ingestione
Memorizza l'URL sorgente/URL del file + l'account di destinazione + scheduleAt + l'idempotency key nel tuo modello di job di pubblicazione.
2) Elaborazione
Chiama POST /shorts/create, persisti il requestId e collegalo ai job di pubblicazione a valle.
3) Polling / Webhook
Sposta i job attraverso gli stati processing/ready/failed usando GET /shorts/:id/status e fallback su eventi.
4) Pubblicazione
Attiva la pubblicazione TikTok con limiti di concorrenza per account, policy di retry e riconciliazione dello stato finale.
Esempi di endpoint
POST /shorts/create— Generare un asset in formato breve prima della pubblicazioneGET /shorts/:id/status— Tracciare il ciclo di vita dell'elaborazione e failureReasonGET /shorts/:id— Recuperare i metadati dell'output completato per la pubblicazione
Indicazioni sull'autenticazione
Usa X-API-Key lato server per Ssemble e mantieni i token OAuth di TikTok isolati nel tuo servizio di pubblicazione. Ruota ogni set di chiavi in modo indipendente per ambiente.
Rate limit e retry
Tratta la generazione e la pubblicazione come budget separati. Serializza le chiamate mutanti per account di destinazione e, in caso di 429, rispetta reset/retryAfter con backoff esponenziale + jitter.
Esempio di richiesta
POST /api/publish/tiktok
{
"jobId": "job_01HT...",
"requestId": "665a1b2c3d4e5f6a7b8c9d0e",
"tiktokAccountId": "acct_kor_store_03",
"scheduleAt": "2026-03-10T18:00:00Z",
"idempotencyKey": "2f182b63-312f-4290-9222-7cf6f7f8f12d"
}Esempio di risposta
200 OK
{
"jobId": "job_01HT...",
"state": "publish_processing",
"publishId": "v_inbox_file~v2.123456789",
"nextCheckAt": "2026-03-10T18:00:30Z"
}Esempio di scenario di errore
429 Too Many Requests
{
"error": {
"code": "rate_limit_exceeded",
"message": "Per-account posting throttle reached",
"details": { "retryAfter": "2026-03-10T18:01:00Z" }
}
}Gestione delle versioni
Fissa le versioni degli endpoint e registra i metadati della versione upstream per ogni richiesta in modo che le regressioni di integrazione siano tracciabili.
Supporto
Per il triage degli incidenti, persisti requestId + publish_id + account id + error.code + upstream log_id in un unico record interrogabile.
Avvio rapido
- Crea SSEMBLE_API_KEY e memorizzala nei secret del backend.
- Chiama POST /shorts/create e persisti il requestId nella tua tabella dei job.
- Esegui il polling di GET /shorts/:id/status ogni 10 secondi fino allo stato terminale.
- Una volta completed, pubblica su TikTok tramite la coda del tuo server.
- Gestisci i 429/5xx con retry limitati e idempotency key stabili.
Workflow in 3 passaggi
- Genera asset in formato breve e memorizza il requestId più il contesto di pubblicazione nella tua tabella dei job.
- Traccia l'elaborazione tramite polling dello stato o webhook e sposta i job negli stati ready/failed in modo deterministico.
- Pubblica su TikTok con controllo del throttle per account, idempotency key e log di riconciliazione.
Perché i team scelgono Ssemble
- Progettato per team di distribuzione multi-account dove l'affidabilità della coda è più importante di un singolo successo occasionale.
- Separa le responsabilità di rendering e pubblicazione in modo che i fallimenti siano isolati e recuperabili.
- Supporta una gestione dello stato consapevole della moderazione: il completamento dell'upload non è sempre la disponibilità pubblica definitiva.
Passaggio successivo
FAQ
Possiamo considerare il successo dell'upload come pubblicazione?
Non sempre. Mantieni stati separati per uploaded, submitted, publish_complete e publicly_available per evitare falsi positivi.
Quale passaggio deve essere idempotente?
Come minimo, l'avvio della pubblicazione. Usa un'unica idempotency key stabile per job in modo che i retry non creino duplicati.
Polling o webhook: cosa usare?
Usa i webhook come metodo principale quando disponibili e mantieni il polling come fallback per la riconciliazione e gli eventi mancati.
Come evitiamo raffiche di 429 su molti account?
Suddividi le code per account di destinazione e applica limiti di concorrenza per account anziché un'unica coda globale a raffica.
Quali log sono obbligatori per la risposta agli incidenti?
Registra requestId, publish_id, account id, le transizioni di stato e il codice di errore per supportare un debug deterministico.
Questo garantisce il tempo di completamento della moderazione?
No. Le finestre di moderazione variano, quindi i sistemi di produzione dovrebbero considerare i tempi di disponibilità finale come asincroni e variabili.
