Escopos da TikTok API for Business: o que cada permissão libera
A API for Business do TikTok concede acesso em duas camadas. O app de desenvolvedor tem permissões em TikTok Accounts, como Video Publish e Manage Account Comment, que abrem endpoints. A autorização do dono da conta dá ao token escopos, como user.insights e video.list, que definem os campos retornados. /tt_user/token_info/get/ lista os escopos que um token carrega.
O easyCoexistence pede ao dono da conta do TikTok as permissões que seu app tem em um único login, para que Claude, ChatGPT ou seu próprio código possam publicar, trabalhar com comentários e ler métricas por meio das suas ferramentas, e get_social_credentials entrega ao seu próprio código o mesmo token para outros endpoints da Accounts API.
ID de escopo de TikTok Accounts, a permissão de primeiro nível acima dos endpoints de perfil, post, comentário e publicação da Accounts API.
Escopo por trás de is_business_account e has_advanced_access nos dados de perfil de uma conta.
Escopo que o dono deve conceder e manter ativo para o app receber eventos de webhook comment.update.
Escopo que um token precisa para enviar um post como rascunho em vez de publicá-lo.
Dias úteis que a análise do TikTok sobre uma alteração nas permissões de um app de desenvolvedor pode levar.
Quais são as duas camadas de permissões do TikTok?
Permissões do app e escopos do token. As permissões do app são escolhidas em My Apps, no app, em Scope of permission, e o TikTok as analisa; existem em três níveis, e uma permissão de primeiro nível cobre todos os endpoints abaixo dela. Os escopos do token são o que o dono da conta aprovou ao autorizar o app, retornados como scope, uma string separada por vírgulas, em cada token. Uma chamada precisa da permissão do app para seu endpoint, e alguns campos de resposta também precisam de um escopo no token.
Qual permissão do app abre cada endpoint?
A referência da API do TikTok lista, para cada endpoint da Accounts API, a permissão em TikTok Accounts que o abre, ou nenhuma. Sua referência de escopos de permissão e seu guia de webhooks chamam os mesmos grupos de Business User, Business Media, Business Comment e Business Content, então espere os dois conjuntos de nomes:
Quais escopos de token liberam quais campos?
As referências do TikTok para /business/get/ e /business/video/list/ indicam uma permissão necessária para cada campo de resposta, e duas outras funcionalidades citam um escopo próprio:
- user.info.basic:
display_nameeprofile_image. - user.info.username: username, que precisou de user.info.basic até junho de 2023.
- user.info.profile:
profile_deep_link,bio_descriptioneis_verified. - user.info.stats:
following_count,followers_count,total_likesevideos_count. - user.account.type:
is_business_accountehas_advanced_access. - user.insights: as métricas diárias da conta e as segmentações de seguidores por idade, gênero, país e cidade.
- video.list: campos de post como
item_id, caption,share_url, likes, comments, shares, reach evideo_views. - video.insights: tempo de exibição, taxa de exibição completa, retenção, fontes de tráfego, segmentações de espectadores e os cliques que um post gera.
- comment.list: o webhook comment.update, descrito pelo TikTok como leitura dos comentários e respostas de conteúdo dentro do app.
- video.upload: envio de um post de vídeo ou foto como rascunho, com
upload_to_draftouis_draft.
Como ver os escopos de um token?
Consulte /tt_user/token_info/get/, que recebe o app_id e o token de acesso e retorna o scope do token e o creator_id da conta. Os exemplos de strings de escopo do TikTok também incluem video.publish e comment.list.manage, cujos nomes correspondem aos endpoints de publicação e de gestão de comentários, embora suas referências não associem nenhum campo a eles.
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/tt_user/token_info/get/' \
-H 'Content-Type: application/json' \
-d '{"app_id": "<APP_ID>", "access_token": "<ACCESS_TOKEN>"}'
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": {
"app_id": "<APP_ID>",
"creator_id": "<OPEN_ID>",
"scope": "video.publish,user.info.basic,video.list,user.insights,comment.list.manage,video.insights,comment.list"
}
}O que a conexão TikTok do easyCoexistence pede?
As permissões que seu app de desenvolvedor tem, todas exibidas na página de consentimento do TikTok. O easyCoexistence envia o dono da conta para a URL de autorização do titular da conta TikTok que o portal do TikTok gera para o seu app, que já nomeia essas permissões, e acrescenta apenas um valor state próprio. O dono aprova o que o TikTok mostra, e a string de escopo que o TikTok devolve é armazenada com a conexão. Os endpoints que o easyCoexistence chama depois para a conta:
- /business/get/ para o perfil, as métricas diárias e as segmentações de seguidores.
- /business/video/list/ para os posts e suas métricas.
- /business/video/publish/, /business/photo/publish/ e /business/publish/status/ para publicação.
- /business/comment/list/, /business/comment/reply/create/, /business/comment/hide/ e /business/comment/delete/ para comentários.
- /business/webhook/update/, no nível do app, para o webhook de comentários.
Como adicionar uma permissão depois?
Em duas etapas, uma para cada camada. Para o app, abra My Apps, o app, Scope of permission, edite, informe um motivo que corresponda aos novos escopos e envie; a análise do TikTok pode levar de dois a três dias úteis, e desde 20 de março de 2026 um pedido que inclua TikTok Accounts precisa primeiro do Accounts API Access Application Form. Para o token, o dono autoriza o app novamente, já que um token mantém os escopos aprovados quando foi emitido.
O que acontece quando uma permissão está faltando?
Em uma chamada, o código de retorno do TikTok é 40001, sem permissão para executar a operação relacionada, e a correção indicada aponta para a referência de escopos de permissão. Em um campo, as referências só o disponibilizam depois que o dono concede seu escopo, e a correção é fazer o dono autorizar o app novamente com esse escopo. Verifique o escopo do token com /tt_user/token_info/get/ antes de pedir.
Erros comuns
- Esperar que contas conectadas ganhem uma nova permissão do app sozinhas. Seus tokens mantêm os escopos aprovados na autorização até que cada dono autorize o app novamente.
- Pedir is_business_account sem user.account.type. O TikTok torna esse campo e has_advanced_access disponíveis apenas para tokens que carregam esse escopo.
- Aguardar comment.update sem comment.list. O TikTok envia eventos de comentário somente enquanto a autorização do dono com esse escopo continua válida.
- Procurar nos tokens os nomes de permissão do app. A string de escopo usa nomes como video.list, enquanto nomes como Get Account Media pertencem às configurações do app.
De US$ 9 a US$ 0.75 por número conectado por mês, caindo conforme você adiciona números, com os 3 primeiros dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Quais escopos a API for Business do TikTok usa?
Escopos de token como user.info.basic, user.info.stats, user.insights, video.list, video.insights, comment.list e video.upload, concedidos pelo dono da conta além das permissões de TikTok Accounts do app.
Quais permissões o webhook de comentários do TikTok precisa?
O app precisa de TikTok Accounts e Business Comment, e o dono deve conceder comment.list. Os eventos param se essa autorização expirar ou for revogada.
Um novo escopo do TikTok vale para tokens já emitidos?
Não. Um token mantém os escopos aprovados quando foi emitido, então o dono da conta autoriza o app novamente para adicionar um novo.
Quanto tempo o TikTok leva para aprovar uma nova permissão?
O TikTok diz que a análise de uma alteração de permissão pode levar de dois a três dias úteis, e pedidos que incluem TikTok Accounts primeiro precisam do Accounts API Access Application Form.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em