Publicar textos no VK e publicar fotos ou vídeos exigem permissões de acesso diferentes. Entenda um erro comum relacionado ao token da comunidade e como configurar tudo corretamente.
Existe um tipo especial de bug que irrita mais do que os outros: tudo parece estar configurado corretamente, nenhum erro aparece, mas o resultado não vem. É exatamente assim que se manifesta um dos problemas mais comuns ao publicar no VK: o texto da postagem é publicado sem problemas, mas a foto ou o vídeo simplesmente não aparece, sem nenhuma mensagem clara sobre o motivo. Não é “erro de acesso” nem “limite excedido” — é apenas silêncio, e a postagem fica sem mídia onde deveria haver uma imagem ou um vídeo.
Nós mesmos tropeçamos nesse problema com o token do VK quando testávamos a publicação de mídia no início do projeto e perdemos um tempo considerável tentando entender por que tudo estava configurado “como na documentação”, mas o vídeo não era publicado. No fim, o problema era justamente o tipo de token — e esse erro é tão comum entre iniciantes que vale a pena explicá-lo à parte, em detalhes.
Na API do VK, existe uma diferença fundamental entre o token da comunidade (community token) e o token de usuário de um administrador da comunidade (user token, obtido por meio de uma autenticação completa no VKontakte). Para publicações somente de texto pela API da comunidade, normalmente basta o token da comunidade — e é justamente por isso que o problema não aparece de imediato: as primeiras postagens de teste, com texto, são publicadas sem problemas e dão a falsa impressão de que está tudo configurado corretamente.
O problema surge assim que uma mídia — foto ou vídeo — é adicionada à publicação. O envio de arquivos de mídia ao VK é um processo que envolve várias etapas: é preciso obter um servidor de upload, enviar o arquivo e, em seguida, confirmar o upload pela API. Em determinadas etapas desse processo, o VK exige especificamente um token OAuth de usuário de um administrador da comunidade, com as permissões correspondentes, e não o token da própria comunidade. Do ponto de vista técnico, o token da comunidade não serve para essa parte do processo, independentemente das permissões que tenham sido formalmente concedidas a ele nas configurações.
O mais desagradável nesse problema é a forma como ele se manifesta na prática. Em alguns casos, a API do VK não retorna um erro de acesso claro quando se tenta usar um token inadequado para fazer upload de mídia. A parte textual da postagem pode ser publicada com sucesso, enquanto o anexo de mídia falha silenciosamente ou é processado com restrições que o sistema de integração talvez nem consiga identificar diretamente. Como resultado, o usuário vê uma postagem publicada sem imagem e não entende o que aconteceu: as configurações parecem corretas, não há erros nos logs e a funcionalidade não funciona.
É justamente um caso em que a “ausência de erro” induz mais ao engano do que uma rejeição explícita: se o sistema simplesmente informasse “tipo de token inválido para upload de mídia”, o problema seria resolvido em um minuto. Em vez disso, é preciso reconstruir a causa a partir de indícios indiretos.
Para que a publicação de mídia no VK funcione de forma estável, é necessário um token de usuário obtido por meio do OAuth 2.1 com PKCE (Proof Key for Code Exchange — uma extensão do protocolo de autenticação que aumenta a segurança da troca de tokens), em nome de uma pessoa que tenha permissões de administrador na comunidade desejada. Na prática, isso significa autenticar-se no VKontakte como um usuário real, confirmar as permissões necessárias e verificar se esse usuário realmente faz parte da administração da comunidade em nome da qual as publicações serão feitas.
Para configurar o aplicativo corretamente, são necessários os parâmetros VK_CLIENT_ID e VK_REDIRECT_URI — o identificador do aplicativo VK e o endereço para o qual o VK redirecionará o usuário após a autenticação bem-sucedida. Sem um URI de redirecionamento configurado corretamente, a autenticação não será concluída e o token não será obtido. Esse é mais um ponto em que vale conferir com atenção se as configurações do aplicativo VK correspondem ao que está configurado no lado da integração.
Se a publicação de texto no VK funciona, mas a mídia não aparece, vale verificar estes pontos, um por um:
Tipo de token. Confirme se está sendo usado um token de usuário de um administrador da comunidade, e não o token da própria comunidade — essa é, de longe, a causa mais comum do problema.
Permissões de autenticação. Verifique se, durante a autenticação, foram solicitadas e concedidas permissões suficientes para fazer upload de fotos e vídeos, e não apenas para publicar postagens de texto.
Status de administrador. Confirme se o usuário cujo token está sendo usado realmente é administrador da comunidade desejada no momento da publicação e se não perdeu esse status após uma mudança na equipe de administradores.
Validade do token. Verifique se o token não expirou — os tokens de usuário do VK têm um prazo de validade próprio, diferente do token da comunidade, e precisam ser renovados periodicamente pelo mesmo mecanismo OAuth.
Toda a complexidade dessa configuração se concentra em uma única ação, feita uma vez: realizar corretamente a autenticação com as permissões necessárias para o usuário administrador certo. Depois disso, a publicação de fotos e vídeos no VK funciona de forma tão transparente quanto a publicação de texto, sem necessidade de repetir a autenticação para cada postagem. Por isso, vale a pena dedicar algum tempo a essa etapa com antecedência, em vez de tentar resolver falhas silenciosas na publicação de mídia depois que o canal do VK já se tornou uma importante fonte de tráfego e o custo de um erro em uma publicação específica aumentou.
Seu próprio bot do Telegram para o canal: quando o bot padrão já não é suficiente
Da anotação no celular ao vídeo pronto: como estruturar uma ideia
