Integrare API

API de publicare TikTok pentru distribuție multi-cont sigură la nivel de coadă

Livrează fluxuri de publicare TikTok cu urmărire explicită a stării, orchestrare sigură la retry și gestionare conștientă de moderare, pentru echipe la scară de producție.

Problemă

La scară, distribuția eșuează acolo unde publicarea rămâne manuală: acțiunile de upload/publicare devin fragile pe multe conturi, programări și stări de moderare.

Rezultat cu Ssemble

Ssemble susține generarea de conținut și orchestrarea stărilor, în timp ce stratul tău de publicare TikTok execută publicări controlate cu idempotency, retry și stări de job auditabile.

Elemente esențiale de implementare

Base URL: https://aiclipping.ssemble.com/api/v1 (+ TikTok Open API for publish)

Arhitectură de integrare (ingerare → procesare → poll/webhook → publicare)

1) Ingerare

Stochează source URL/file URL + contul de destinație + scheduleAt + cheia de idempotency în modelul jobului tău de publicare.

2) Procesare

Apelează POST /shorts/create, persistă requestId și atașează-l la joburile de publicare din aval.

3) Poll / Webhook

Mută joburile prin stările processing/ready/failed folosind GET /shorts/:id/status și mecanisme de rezervă bazate pe evenimente.

4) Publicare

Declanșează publicarea TikTok cu limite de concurență per cont, politică de retry și reconcilierea stării finale.

Exemple de endpoint

POST /shorts/create— Generează materialul short-form înainte de publicare
GET /shorts/:id/status— Urmărește ciclul de viață al procesării și failureReason
GET /shorts/:id— Obține metadatele materialului finalizat pentru publicare

Îndrumări de autentificare

Folosește X-API-Key pe partea de server pentru Ssemble și păstrează tokenurile TikTok OAuth izolate în serviciul tău de publicare. Rotește fiecare set de chei independent, per mediu.

Rate limit și retry

Tratează generarea și publicarea ca bugete separate. Serializează apelurile care modifică date per cont de destinație și, la 429, respectă reset/retryAfter cu backoff exponențial + jitter.

Exemplu de cerere

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"
}

Exemplu de răspuns

200 OK
{
  "jobId": "job_01HT...",
  "state": "publish_processing",
  "publishId": "v_inbox_file~v2.123456789",
  "nextCheckAt": "2026-03-10T18:00:30Z"
}

Exemplu de scenariu de eroare

429 Too Many Requests
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-account posting throttle reached",
    "details": { "retryAfter": "2026-03-10T18:01:00Z" }
  }
}

Versionare

Fixează versiunile de endpoint și înregistrează metadatele de versiune upstream per cerere, astfel încât regresiile de integrare să fie trasabile.

Asistență

Pentru triajul incidentelor, persistă requestId + publish_id + account id + error.code + upstream log_id într-o singură înregistrare interogabilă.

Ghid de pornire rapidă

Creează SSEMBLE_API_KEY și stochează-o în secretele backend.
Apelează POST /shorts/create și persistă requestId în tabelul tău de joburi.
Interoghează GET /shorts/:id/status la fiecare 10 secunde până la starea terminală.
La completed, publică pe TikTok prin coada ta de pe server.
Gestionează 429/5xx cu retry-uri limitate și chei de idempotency stabile.

Deschide documentația de publicare TikTok

Începe integrarea

1) Autentificare

Formatul cheii API și gestionarea erorilor de autentificare

2) Referință endpoint

Contracte pentru create/status/list/delete

3) Gestionarea erorilor

Tipare de erori retryable vs terminale

4) Exemple de cod

Fragmente de integrare gata de implementat

Flux de lucru în 3 pași

Generează materiale short-form și stochează requestId împreună cu contextul de publicare în tabelul tău de joburi.
Urmărește procesarea prin polling de status sau webhooks și mută joburile în stări ready/failed în mod determinist.
Publică pe TikTok cu control de throttle per cont, chei de idempotency și jurnale de reconciliere.

De ce echipele aleg Ssemble

Construit pentru echipe de distribuție multi-cont, unde fiabilitatea cozii contează mai mult decât un succes izolat.
Separă preocupările de randare și de publicare, astfel încât eșecurile să fie izolate și recuperabile.
Susține gestionarea stării conștientă de moderare: finalizarea uploadului nu înseamnă întotdeauna disponibilitate publică finală.

Pasul următor

Deschide ghidul de pornire rapidă pentru publicarea TikTok Vezi prețurile Documentație pentru dezvoltatori

Întrebări frecvente

Putem trata succesul uploadului ca fiind publicat?

Nu întotdeauna. Păstrează stări separate pentru uploaded, submitted, publish_complete și publicly_available, ca să eviți falsele pozitive.

Ce pas trebuie să fie idempotent?

Cel puțin inițierea publicării. Folosește o singură cheie de idempotency stabilă per job, astfel încât retry-urile să nu creeze duplicate.

Polling sau webhooks: pe care ar trebui să le folosim?

Folosește webhooks ca metodă principală, atunci când sunt disponibile, și păstrează polling-ul ca rezervă pentru reconciliere și evenimente pierdute.

Cum evităm rafalele de 429 pe multe conturi?

Împarte cozile pe cont de destinație și impune limite de concurență per cont, în loc de o singură coadă globală cu rafale.

Ce jurnale sunt obligatorii pentru răspunsul la incidente?

Înregistrează requestId, publish_id, account id, tranzițiile de stare și codul de eroare pentru a susține un debugging determinist.

Garantează acest lucru timpul de finalizare a moderării?

Nu. Ferestrele de moderare variază, așa că sistemele de producție ar trebui să trateze momentul disponibilității finale ca fiind asincron și variabil.