Integração de API

API de publicação no TikTok para distribuição multiconta segura em filas

Implemente fluxos de publicação no TikTok com rastreamento de status explícito, orquestração segura para retries e tratamento consciente da moderação para equipes em escala de produção.

Problema

Em escala, a distribuição falha onde a publicação ainda é manual: as ações de upload/publicação tornam-se frágeis em muitas contas, agendamentos e estados de moderação.

Resultado com a Ssemble

A Ssemble oferece suporte à geração de conteúdo e à orquestração de status enquanto sua camada de publicação no TikTok executa publicações controladas com idempotency, retries e estados de job auditáveis.

Fundamentos de implementação

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

Arquitetura de integração (ingestão → processamento → polling/webhook → publicação)

1) Ingestão

Armazene a source URL/file URL + conta de destino + scheduleAt + idempotency key no modelo de job do seu publicador.

2) Processamento

Chame POST /shorts/create, persista o requestId e vincule-o aos jobs de publicação subsequentes.

3) Poll / Webhook

Mova os jobs pelos estados processing/ready/failed usando GET /shorts/:id/status e fallbacks de eventos.

4) Publicação

Acione a publicação no TikTok com limites de concorrência por conta, política de retry e reconciliação de status final.

Exemplos de endpoint

POST /shorts/create— Gerar o ativo em formato curto antes de publicar
GET /shorts/:id/status— Acompanhar o ciclo de vida do processamento e o failureReason
GET /shorts/:id— Recuperar os metadados da saída concluída para publicação

Orientações de autenticação

Use a X-API-Key no lado do servidor para a Ssemble e mantenha os tokens OAuth do TikTok isolados no seu serviço de publicação. Faça a rotação de cada conjunto de chaves de forma independente por ambiente.

Rate limits e retries

Trate geração e publicação como orçamentos separados. Serialize as chamadas de mutação por conta de destino e, em caso de 429, respeite reset/retryAfter com backoff exponencial + jitter.

Exemplo de requisição

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

Exemplo de resposta

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

Exemplo de cenário de erro

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

Versionamento

Fixe as versões de endpoint e registre os metadados de versão upstream por requisição, para que as regressões de integração sejam rastreáveis.

Suporte

Para triagem de incidentes, persista requestId + publish_id + account id + error.code + upstream log_id em um único registro consultável.

Início rápido

Crie a SSEMBLE_API_KEY e armazene-a nos segredos do backend.
Chame POST /shorts/create e persista o requestId na sua tabela de jobs.
Faça polling em GET /shorts/:id/status a cada 10 segundos até o estado terminal.
Ao chegar em completed, publique no TikTok pela fila do seu servidor.
Trate 429/5xx com retries limitados e idempotency keys estáveis.

Abrir a documentação de publicação no TikTok

Iniciar integração

1) Autenticação

Formato da API key e tratamento de erros de autenticação

2) Referência de endpoints

Contratos de create/status/list/delete

3) Tratamento de erros

Padrões de erro retryable vs. terminal

4) Exemplos de código

Trechos de integração prontos para implementação

Fluxo de trabalho em 3 etapas

Gere ativos em formato curto e armazene o requestId junto com o contexto de publicação na sua tabela de jobs.
Acompanhe o processamento por polling de status ou webhooks e mova os jobs para estados ready/failed de forma determinística.
Publique no TikTok com controle de throttle por conta, idempotency keys e logs de reconciliação.

Por que as equipes escolhem a Ssemble

Feito para equipes de distribuição multiconta em que a confiabilidade da fila é mais importante do que o sucesso pontual.
Separa as responsabilidades de renderização e publicação, de modo que as falhas fiquem isoladas e recuperáveis.
Oferece suporte ao tratamento de estados consciente da moderação: a conclusão do upload nem sempre significa disponibilidade pública final.

Próximo passo

Abrir o início rápido de publicação no TikTok Ver preços Documentação para desenvolvedores

FAQ

Podemos tratar o sucesso do upload como publicado?

Nem sempre. Mantenha estados separados para uploaded, submitted, publish_complete e publicly_available para evitar falsos positivos.

Qual etapa precisa ser idempotente?

No mínimo, o início da publicação. Use uma idempotency key estável por job para que os retries não criem duplicatas.

Polling ou webhooks: qual devemos usar?

Use webhooks como opção principal quando disponíveis e mantenha o polling como fallback para reconciliação e eventos perdidos.

Como evitamos picos de 429 em muitas contas?

Faça o sharding das filas por conta de destino e imponha limites de concorrência por conta, em vez de uma única fila global de picos.

Quais logs são obrigatórios para a resposta a incidentes?

Registre requestId, publish_id, account id, transições de status e error code para dar suporte a uma depuração determinística.

Isso garante o tempo de conclusão da moderação?

Não. As janelas de moderação variam, então os sistemas de produção devem tratar o tempo de disponibilidade final como assíncrono e variável.