Integracja API
API do publikacji na TikTok dla bezpiecznej kolejkowo dystrybucji na wielu kontach
Wdrażaj procesy publikacji na TikTok z jawnym śledzeniem statusów, orkiestracją odporną na retry i obsługą uwzględniającą moderację dla zespołów działających na skalę produkcyjną.
Problem
Przy dużej skali dystrybucja zawodzi tam, gdzie publikacja pozostaje ręczna: operacje uploadu/publikacji stają się kruche na wielu kontach, harmonogramach i stanach moderacji.
Rezultat z Ssemble
Ssemble obsługuje generowanie treści i orkiestrację statusów, podczas gdy Twoja warstwa publikacji na TikTok wykonuje kontrolowane publikacje z idempotency, retry i audytowalnymi stanami zadań.
Podstawy wdrożenia
Base URL: https://aiclipping.ssemble.com/api/v1 (+ TikTok Open API for publish)
Architektura integracji (przyjęcie → przetwarzanie → poll/webhook → publikacja)
1) Przyjęcie
Zapisz source URL/file URL + konto docelowe + scheduleAt + idempotency key w modelu zadania publikatora.
2) Przetwarzanie
Wywołaj POST /shorts/create, utrwal requestId i dołącz go do powiązanych zadań publikacji.
3) Poll / Webhook
Przeprowadzaj zadania przez stany processing/ready/failed za pomocą GET /shorts/:id/status oraz mechanizmów zapasowych opartych na zdarzeniach.
4) Publikacja
Uruchom publikację na TikTok z limitami współbieżności per konto, polityką retry i ostateczną rekoncyliacją statusu.
Przykłady endpointów
POST /shorts/create— Wygeneruj materiał short-form przed publikacjąGET /shorts/:id/status— Śledź cykl życia przetwarzania i failureReasonGET /shorts/:id— Pobierz metadane ukończonego wyniku do publikacji
Wskazówki dotyczące uwierzytelniania
Używaj X-API-Key po stronie serwera dla Ssemble i przechowuj tokeny TikTok OAuth odizolowane w swojej usłudze publikacji. Rotuj każdy zestaw kluczy niezależnie dla każdego środowiska.
Limity zapytań (rate limit) i ponowne próby (retry)
Traktuj generowanie i publikację jako oddzielne budżety. Serializuj wywołania modyfikujące dane per konto docelowe, a przy 429 uwzględniaj reset/retryAfter z wykładniczym backoffem i jitterem.
Przykładowe żądanie
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"
}Przykładowa odpowiedź
200 OK
{
"jobId": "job_01HT...",
"state": "publish_processing",
"publishId": "v_inbox_file~v2.123456789",
"nextCheckAt": "2026-03-10T18:00:30Z"
}Przykład scenariusza błędu
429 Too Many Requests
{
"error": {
"code": "rate_limit_exceeded",
"message": "Per-account posting throttle reached",
"details": { "retryAfter": "2026-03-10T18:01:00Z" }
}
}Wersjonowanie
Przypinaj wersje endpointów i loguj metadane wersji upstream dla każdego żądania, aby regresje integracji były łatwe do prześledzenia.
Wsparcie
Do triażu incydentów utrwalaj requestId + publish_id + account id + error.code + upstream log_id w jednym rekordzie umożliwiającym zapytania.
Szybki start
- Utwórz SSEMBLE_API_KEY i zapisz w sekretach backendu.
- Wywołaj POST /shorts/create i utrwal requestId w tabeli zadań.
- Wykonuj polling GET /shorts/:id/status co 10 sekund aż do stanu końcowego.
- Po completed opublikuj na TikTok przez kolejkę serwerową.
- Obsługuj 429/5xx z ograniczoną liczbą retry i stabilnymi idempotency keys.
Proces w 3 krokach
- Generuj materiały w formacie short-form i zapisuj requestId oraz kontekst publikacji w tabeli zadań.
- Śledź przetwarzanie poprzez polling statusu lub webhooki i deterministycznie przenoś zadania do stanów ready/failed.
- Publikuj na TikTok z kontrolą throttlingu per konto, idempotency keys i logami rekoncyliacji.
Dlaczego zespoły wybierają Ssemble
- Zbudowane dla zespołów dystrybucji wielokontowej, w których niezawodność kolejki jest ważniejsza niż jednorazowy sukces.
- Rozdziela kwestie renderowania i publikacji, dzięki czemu awarie są izolowane i możliwe do naprawienia.
- Obsługuje zarządzanie stanami uwzględniające moderację: zakończenie uploadu nie zawsze oznacza ostateczną publiczną dostępność.
Następny krok
FAQ
Czy możemy traktować udany upload jako publikację?
Nie zawsze. Utrzymuj oddzielne stany dla uploaded, submitted, publish_complete i publicly_available, aby uniknąć fałszywych pozytywów.
Który krok musi być idempotentny?
Co najmniej inicjacja publikacji. Używaj jednego stabilnego idempotency key na zadanie, aby retry nie tworzyły duplikatów.
Polling czy webhooki: co powinniśmy stosować?
Używaj webhooków jako podstawowego mechanizmu, gdy są dostępne, i zachowaj polling jako mechanizm zapasowy do rekoncyliacji i przechwytywania pominiętych zdarzeń.
Jak unikać nagłych skoków 429 na wielu kontach?
Dziel kolejki według konta docelowego i wymuszaj limity współbieżności per konto zamiast jednej globalnej kolejki obciążeniowej.
Jakie logi są obowiązkowe przy reagowaniu na incydenty?
Rejestruj requestId, publish_id, account id, przejścia statusów oraz kod błędu, aby wspierać deterministyczne debugowanie.
Czy to gwarantuje czas zakończenia moderacji?
Nie. Okna moderacji różnią się, więc systemy produkcyjne powinny traktować czas ostatecznej dostępności jako asynchroniczny i zmienny.
