Integración de API

API de publicación en TikTok para distribución multicuenta segura ante colas

Implementa flujos de publicación en TikTok con seguimiento explícito de estados, orquestación segura ante reintentos y manejo consciente de la moderación para equipos a escala de producción.

Problema

A escala, la distribución falla donde la publicación sigue siendo manual: las acciones de upload/publish se vuelven frágiles entre muchas cuentas, calendarios y estados de moderación.

Resultado con Ssemble

Ssemble da soporte a la generación de contenido y a la orquestación de estados mientras tu capa de publicación en TikTok ejecuta publicaciones controladas con idempotency, reintentos y estados de job auditables.

Aspectos esenciales de la implementación

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

Arquitectura de integración (ingesta → procesamiento → poll/webhook → publicación)

1) Ingesta

Almacena source URL/file URL + cuenta de destino + scheduleAt + idempotency key en el modelo de job de tu publicador.

2) Procesamiento

Llama a POST /shorts/create, persiste el requestId y adjúntalo a los jobs de publicación posteriores.

3) Poll / Webhook

Mueve los jobs entre los estados processing/ready/failed usando GET /shorts/:id/status y fallbacks de eventos.

4) Publicación

Dispara la publicación en TikTok con límites de concurrencia por cuenta, retry policy y reconciliación de estado final.

Ejemplos de endpoints

POST /shorts/create— Generar el asset de formato corto antes de publicar
GET /shorts/:id/status— Seguir el ciclo de vida del procesamiento y failureReason
GET /shorts/:id— Recuperar los metadatos de la salida completada para publicar

Guía de autenticación

Usa X-API-Key del lado del servidor para Ssemble y mantén los tokens de OAuth de TikTok aislados en tu servicio de publicación. Rota cada conjunto de claves de forma independiente por entorno.

Rate limits y reintentos

Trata la generación y la publicación como presupuestos separados. Serializa las llamadas que mutan estado por cuenta de destino y, ante un 429, respeta reset/retryAfter con exponential backoff + jitter.

Ejemplo de request

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

Ejemplo de response

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

Ejemplo de escenario de error

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

Versionado

Fija las versiones de los endpoints y registra los metadatos de versión upstream por request para que las regresiones de integración sean rastreables.

Soporte

Para la clasificación de incidencias, persiste requestId + publish_id + account id + error.code + log_id upstream en un único registro consultable.

Quickstart

Crea SSEMBLE_API_KEY y guárdalo en los secrets del backend.
Llama a POST /shorts/create y persiste el requestId en tu tabla de jobs.
Haz poll de GET /shorts/:id/status cada 10 segundos hasta el estado terminal.
En completed, publica en TikTok a través de tu cola del servidor.
Maneja 429/5xx con reintentos acotados e idempotency keys estables.

Abrir la documentación de publicación en TikTok

Iniciar integración

1) Autenticación

Formato de API key y manejo de errores de auth

2) Referencia de endpoints

Contratos de create/status/list/delete

3) Manejo de errores

Patrones de errores reintentable vs. terminal

4) Ejemplos de código

Snippets de integración listos para implementar

Flujo de trabajo en 3 pasos

Genera assets de formato corto y almacena el requestId más el contexto de publicación en tu tabla de jobs.
Haz seguimiento del procesamiento mediante status polling o webhooks y mueve los jobs a estados ready/failed de forma determinista.
Publica en TikTok con control de throttle por cuenta, idempotency keys y logs de reconciliación.

Por qué los equipos eligen Ssemble

Pensado para equipos de distribución multicuenta donde la fiabilidad de la cola importa más que el éxito puntual.
Separa las responsabilidades de renderizado y publicación para que los fallos queden aislados y sean recuperables.
Da soporte a un manejo de estados consciente de la moderación: completar un upload no siempre equivale a la disponibilidad pública final.

Siguiente paso

Abrir el quickstart de publicación en TikTok Ver precios Documentación para desarrolladores

FAQ

¿Podemos tratar el éxito del upload como publicado?

No siempre. Mantén estados separados para uploaded, submitted, publish_complete y publicly_available para evitar falsos positivos.

¿Qué paso debe ser idempotente?

Como mínimo, el inicio de la publicación. Usa una idempotency key estable por job para que los reintentos no creen duplicados.

Polling o webhooks: ¿cuál deberíamos usar?

Usa webhooks como método principal cuando estén disponibles y conserva el polling como fallback para la reconciliación y los eventos perdidos.

¿Cómo evitamos ráfagas de 429 entre muchas cuentas?

Fragmenta las colas por cuenta de destino y aplica límites de concurrencia por cuenta en lugar de una única cola global de ráfagas.

¿Qué logs son obligatorios para la respuesta a incidencias?

Registra requestId, publish_id, account id, transiciones de estado y error code para permitir un debugging determinista.

¿Esto garantiza el tiempo de finalización de la moderación?

No. Las ventanas de moderación varían, por lo que los sistemas de producción deben tratar el tiempo de disponibilidad final como asíncrono y variable.