Você precisa buscar programaticamente os detalhes do usuário do TikTok para potencializar os fluxos de gerenciamento de usuários—verificando contas durante a integração, enriquecendo perfis ou reconciliando registros armazenados com dados ao vivo. Ao final deste guia, você será capaz de chamar um verdadeiro endpoint “Obter Informações do Usuário”, lidar com sua resposta e integrá-lo em um fluxo de trabalho de produção, com exemplos funcionais de curl e Python que você pode colar em sua base de código hoje.
O que esta API faz e como ajuda o Gerenciamento de Usuários
A API de Dados do TikTok no Zyla API Hub expõe dois endpoints somente leitura que você pode chamar com uma única chave de API:
- Obter Informações do Usuário: retorna informações sobre um usuário do TikTok pelo
user_id. Este é o bloco de construção central para tarefas de verificação e sincronização de usuários. - Obter Informações do Vídeo: retorna metadados em nível de vídeo pelo
url. Isso é útil quando seu fluxo de gerenciamento de usuários precisa associar usuários ao seu conteúdo compartilhado ou validar se um URL de vídeo enviado é válido e pertence à conta pretendida.
Casos de uso típicos de gerenciamento de usuários incluem:
- Validar um
user_iddo TikTok fornecido durante o cadastro ou vincular um perfil existente a uma conta de cliente. - Enriquecer sua tabela de usuários com IDs canônicos que você pode usar de forma confiável em sistemas posteriores.
- Revisar um URL de vídeo fornecido por um usuário e correlacioná-lo com sua conta antes de conceder acesso a recursos restritos.
Você acessa ambos os endpoints de uma única conta de marketplace e chave de API, com cobrança baseada em assinatura e cota. A primeira API aqui oferece um teste de 7 dias (ou 50 solicitações). Não há plano gratuito; verifique a página da API para opções de acesso e preços atuais.
Começando no Zyla API Hub
Abra a listagem da API de Dados do TikTok no Zyla API Hub, clique em Inscrever-se ou Começar Teste Gratuito quando disponível, e copie sua chave de API. Todas as solicitações incluem um único cabeçalho para autenticação:
- Cabeçalho:
Authorization: Bearer YOUR_API_KEY
Comece seu teste aqui: Comece o teste de 7 dias na API de Dados do TikTok. Você estará chamando endpoints de produção em minutos.
Referência de endpoint
Obter Informações do Usuário
Use este endpoint quando você tiver um user_id do TikTok e precisar buscar as informações desse usuário. Este é o centro para verificação e sincronização de usuários.
- Método: GET
- URL: https://zylalabs.com/api/2516/tiktok-data-api/2503/get-user-info
- Parâmetro necessário:
user_id(string): ID do usuário do TikTok. Exemplo:107955
Exemplo oficial de curl:
curl -s -X GET "https://zylalabs.com/api/2516/tiktok-data-api/2503/get-user-info?user_id=107955" \
-H "Authorization: Bearer YOUR_API_KEY"
Exemplo de resposta oficial:
{
"code": -1,
"msg": "userinfo is failed! Please check unique_id or user_id.",
"processed_time": 0.1441
}
Notas de campo que você realmente usará:
code: indicador de resultado inteiro. Um valor negativo aqui sinaliza que a solicitação não retornou dados do usuário para o identificador fornecido.msg: mensagem de diagnóstico para ajudar no tratamento de erros (por exemplo, ID inválido ou inexistente).processed_time: tempo de processamento em segundos (float). Útil para observabilidade e orçamentação de tentativas.
Dica de produção: Armazene o msg junto com sua tentativa de validação para que sua equipe de suporte possa distinguir um ID malformado de uma condição não encontrada ao revisar problemas de integração de usuários.
Obter Informações do Vídeo
Use este endpoint quando precisar validar ou enriquecer uma submissão de usuário que contém um URL de vídeo do TikTok. Isso é comum quando os usuários vinculam conteúdo para provar propriedade ou elegibilidade.
- Método: GET
- URL: https://zylalabs.com/api/2516/tiktok-data-api/2504/get-video-info
- Parâmetro necessário:
url(string): Um URL de vídeo do TikTok no formato específico mostrado abaixo.
Nota: O URL do vídeo deve estar no seguinte formato https://www.tiktok.com/@khaby.lame/video/7411964588809342241. Exemplo oficial de curl:
Use os campos retornados para confirmar que o vídeo existe e para extrair identificadores que ajudam a correlacionar o conteúdo com um perfil de usuário em seu sistema. Se você coletar o identificador do TikTok de um usuário junto com este URL, poderá verificar ambos antes de permitir uma ação como ingressar em um programa de criadores ou desbloquear recursos avançados.
Exemplo funcional em Python
O trecho abaixo chama Obter Informações do Usuário com os parâmetros documentados e esquema de autenticação, depois ramifica no code para determinar se deve anexar a conta do TikTok ao seu registro interno de usuário ou sinalizá-la para revisão.
import requests
API_KEY = "YOUR_API_KEY"
USER_ID = "107955" # forneça o user_id que você coletou durante seu fluxo de usuário
url = "https://zylalabs.com/api/2516/tiktok-data-api/2503/get-user-info"
params = {"user_id": USER_ID}
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get(url, params=params, headers=headers, timeout=20)
resp.raise_for_status()
data = resp.json()
# Lógica mínima de ramificação para fluxos de gerenciamento de usuários
if isinstance(data, dict) and data.get("code") == 0:
# Exemplo: persista a vinculação verificada do TikTok em sua tabela de usuários
# save_user_tiktok_link(internal_user_id, USER_ID, data)
print("Informações do usuário recuperadas e armazenadas.")
else:
# Registre diagnósticos e alerte seu suporte ou sistema de risco
print(f"Verificação de usuário falhou para {USER_ID}.)
print(f"code={data.get("code")} msg={data.get("msg")} processed_time={data.get("processed_time")}")
Notas:
- Timeouts: defina um apropriado para seu ambiente; 20 segundos acima é um exemplo.
- Tentativas: apenas tente novamente GETs idempotentes em timeouts de nível de rede ou 5xx, não em códigos de erro de nível de aplicativo no JSON.
- Observabilidade: armazene
processed_timecom seu contexto de log para rastrear lentidões ao longo do tempo.
Projetando fluxos de gerenciamento de usuários em torno desses endpoints
Abaixo estão padrões mínimos, mas eficazes, que você pode adaptar diretamente em sua camada de serviço e filas.
- Cadastro com ID do TikTok:
- Coletar
user_idem seu formulário e armazená-lo em um estado pendente. - Chamar Obter Informações do Usuário imediatamente; se
codeindicar sucesso, marque a vinculação como verificada e continue seu fluxo. - Se a resposta indicar uma falha, retorne um erro inline preciso para o usuário com base no
msg, e coloque uma auditoria de suporte na fila, se necessário.
- Coletar
- Vincular um vídeo do TikTok a um perfil de usuário:
- Coletar um
urlde vídeo do usuário no formato documentado. - Chamar Obter Informações do Vídeo e confirmar que o vídeo é resolvido. Se você também tiver o
user_iddo TikTok do usuário, correlacione identificadores dos metadados do vídeo para maior segurança antes de persistir.
- Coletar um
- Re-sincronização periódica:
- Agende um trabalho para revalidar os valores de
user_idarmazenados, usando Obter Informações do Usuário para um conjunto de amostra ou completo de contas, dependendo de sua cota. - Registre alterações e avise as operações de produto se uma vinculação anteriormente válida começar a falhar.
- Agende um trabalho para revalidar os valores de
Dicas operacionais que economizam tempo
- Autenticação: sempre envie
Authorization: Bearer YOUR_API_KEY. Não adicione cabeçalhos extras ou tente chave-em-consulta, a menos que documentado explicitamente (não é para esta API). - Formato da solicitação: ambos os endpoints são GET com parâmetros de consulta apenas; não há corpo de solicitação.
- Tempo processado: o float
processed_timeestá em segundos; é útil para painéis de desempenho e SLOs. - Cache: se você armazenar em cache as buscas de usuários, respeite o fato de que identidades voltadas para o usuário podem mudar. Use TTLs curtos para fluxos de verificação críticos, mais longos para enriquecimento não crítico.
- Tratamento de erros: ramifique no
codedo JSON e inspecionemsgpara orientação voltada para o usuário ou registro interno; trate erros de rede e erros de nível JSON de forma diferente. - Planejamento de cota: o marketplace usa assinatura + cota (não pagamento por chamada). A primeira API aqui suporta um teste de 7 dias ou 50 solicitações para ajudá-lo a integrar. Monitore o uso em seu painel Zyla e dimensione os trabalhos em lote de acordo.
Referência rápida: parâmetros e URLs exatos
- Obter Informações do Usuário
- GET https://zylalabs.com/api/2516/tiktok-data-api/2503/get-user-info
- Parâmetros:
user_id(string, obrigatório)
- Obter Informações do Vídeo
- GET https://zylalabs.com/api/2516/tiktok-data-api/2504/get-video-info
- Parâmetros:
url(string, obrigatório), formato comohttps://www.tiktok.com/@khaby.lame/video/7411964588809342241
Casos de uso mapeados para endpoints
- Vinculação de conta: use Obter Informações do Usuário para confirmar que a conta do TikTok existe antes de salvá-la no perfil do usuário.
- Verificações de elegibilidade para recursos de criadores: valide um URL de vídeo enviado com Obter Informações do Vídeo, e prossiga apenas se a busca for bem-sucedida.
- Ferramentas de suporte: adicione um botão “Re-verificar TikTok” em seu admin que chama Obter Informações do Usuário e exibe
msgpara sua equipe.
Chame esta API de agentes de IA via MCP
Você também pode invocar esses endpoints HTTP de ferramentas e agentes de desenvolvedor compatíveis com MCP (por exemplo, Claude Code, Cursor, Windsurf) usando o gateway MCP da Zyla. Aponte seu cliente para o endpoint MCP e passe sua chave de API:
- URL do MCP:
https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
De seu agente, emita as mesmas solicitações HTTPS GET mostradas acima (incluindo o cabeçalho de Autorização). Isso permite que você script verificações de um clique durante revisões de código ou operações guiadas por runbook sem codificar segredos em scripts locais. Para mais, veja a documentação: MCP.
Solução de problemas
- Obtendo
code: -1em Obter Informações do Usuário: confirme se ouser_idfornecido está correto. Exiba omsgpara os usuários de uma forma amigável (por exemplo, “Por favor, verifique seu ID de usuário do TikTok”). - Desajustes de URL de vídeo: certifique-se de que o URL siga o formato documentado, incluindo a estrutura do caminho. Se você capturar parâmetros de consulta de idioma (por exemplo,
?lang=en), mantenha-os codificados em URL como no exemplo de curl. - HTTP 401: verifique se seu cabeçalho de Autorização usa o esquema Bearer e se a chave não expirou ou foi rotacionada.
- Observabilidade: registre
processed_timepara cada solicitação para identificar respostas lentas intermitentes e ajustar tentativas.
FAQ
Qual cabeçalho de autenticação a API de Dados do TikTok espera?
Envie Authorization: Bearer YOUR_API_KEY em cada solicitação.
Posso enviar um corpo POST para esses endpoints?
Não. Ambos os endpoints documentados são GET e aceitam parâmetros apenas via string de consulta.
O que processed_time representa?
É o tempo de processamento do lado do servidor em segundos para sua solicitação. Use-o para monitoramento de desempenho e alertas.
Há um plano gratuito?
Não. O marketplace usa assinatura + cota, não pagamento por chamada. A primeira API aqui oferece um teste de 7 dias ou 50 solicitações para que você possa integrar antes de se comprometer. Para opções de acesso e preços atuais, verifique a página da API.
Quão rigoroso é o formato do URL do vídeo?
Você deve fornecer um URL no formato mostrado na descrição do endpoint (por exemplo, https://www.tiktok.com/@khaby.lame/video/7411964588809342241). Mantenha os parâmetros de consulta codificados em URL, se presentes.
Implemente sua integração
Agora você tem os URLs exatos, parâmetros e exemplos funcionais para verificar usuários do TikTok e validar seu conteúdo enviado dentro de seus fluxos de gerenciamento de usuários. Crie sua conta, obtenha uma chave de API e comece seu teste de 7 dias aqui: Comece o teste de 7 dias na API de Dados do TikTok. Uma conta cobre milhares de APIs prontas para produção no Zyla API Hub com uma única chave e modelo de assinatura.