API de Marketing

Autenticação

Tanto as chamadas da Graph API quanto as da API de Marketing exigem que um token de acesso seja transmitido como um parâmetro em cada chamada de API. Neste guia, mostraremos como você pode obter tokens de acesso para fins de teste.

Para saber mais sobre autenticação, consulte nossa documentação principal: Tokens de acesso para tecnologias da Meta

Esta documentação abrangerá:

Explorador da Graph API

Você pode obter um token de acesso do usuário de teste com o Explorador da Graph API. Para aprender a usar a ferramenta, consulte o Guia do Explorador da Graph API.

Obter um token de acesso do usuário

  1. Acesse o Explorador da Graph API.
  2. Em App da Meta, selecione um app usado para obter o token de acesso.
  3. Em Usuário ou Página, selecione Token do usuário.
  4. Em Permissões, selecione ads_read.
  5. Clique em Gerar token de acesso. A caixa exibida acima do botão será preenchida com o token de acesso.
  6. Guarde esse token para usar mais tarde.

Depurar

Para ver mais informações sobre o token que você acabou de gerar, clique no ícone i exibido na caixa. Após o clique, uma tela pop-up será aberta e mostrará algumas informações básicas sobre o token. Clique em Abrir na ferramenta Token de Acesso para acessar o Depurador de Token de Acesso.

Também é possível abrir diretamente o Depurador de Token de Acesso e colar o token que você gerou na caixa de texto.

Durante a depuração, verifique estes campos:

  • ID do Aplicativo: o ID do app mencionado na seção de pré-requisitos.
  • Expira: um carimbo de tempo. Um token de curta duração expira dentro de uma hora ou duas.
  • Escopos: contém as permissões adicionadas no Explorador da Graph API.

Estender token de acesso

  1. Conclua todas as etapas para obter o token de acesso usando o Explorador da Graph API.
  2. Copie o token. Cole-o na caixa de texto do Depurador de Token de Acesso.
  3. No Depurador de Token de Acesso, role a página até o final.
  4. Clique em Estender token de acesso para obter um token de longa duração. Copie-o para usar mais tarde.

Verifique as propriedades do seu novo token usando o Depurador de Token de Acesso. Ele deve ter um tempo de validade mais longo, como 60 dias, ou exibir Nunca no campo Expira. Consulte Tokens de longa duração de acesso.

Usar o token de acesso do usuário do sistema

Um token de acesso do usuário do sistema é um tipo de token de acesso associado a uma conta de usuário do sistema, que é uma conta criada no Gerenciador de Negócios com o objetivo de gerenciar ativos e fazer chamadas à API de marketing. Os tokens de acesso do usuário do sistema são úteis para interações entre servidores onde não houver um usuário presente para autenticar. Eles podem ser usados para realizar ações em nome da empresa, como ler e escrever dados do negócio, gerenciar campanhas de anúncios e outros objetos do anúncio.

Uma vantagem de usar um token de acesso de usuário do sistema é que ele não expira, o que significa que ele pode ser usado em scripts ou serviços de longa duração que precisam acessar a Graph API. Além disso, como as contas de usuário do sistema não estão vinculadas a um indivíduo específico, elas podem ser usadas para fornecer um nível de separação entre atividades pessoais e comerciais no Facebook.

Os tokens de usuário do sistema também são menos susceptíveis a ser invalidados por outras razões em comparação com os tokens de acesso do usuário de longa duração.

Obter um token manualmente

Se o usuário clicar no botão Permitir quando solicitar as permissões estendidas, ele será redirecionado para uma URL que contém o valor do parâmetro redirect_uri e um código de autorização:

http://YOUR_URL?code=<AUTHORIZATION_CODE>

Crie uma URL que inclua o ponto de extremidade para obter um token, o ID do app, a URL do site, a chave secreta do app e o código de autorização que você acabou de receber. A URL será semelhante a isto:

https://graph.facebook.com/<API_VERSION>/oauth/access_token?
  client_id=<YOUR_APP_ID>
  &redirect_uri=<YOUR_URL>
  &client_secret=<YOUR_APP_SECRET>
  &code=<AUTHORIZATION_CODE>

A resposta deve conter o token de acesso do usuário:

  • Ao seguir o fluxo de autenticação do servidor, você receberá um token persistente.
  • Caso opte pelo fluxo de autenticação do lado do cliente, você receberá um token com um prazo de validade limitado, de uma a duas horas. Ele poderá ser substituído por um token persistente. Basta fazer uma chamada ao ponto de extremidade da Graph API para tokens estendidos.

Se a API for invocada por um usuário do sistema de uma empresa, você poderá usar um token de acesso de usuário do sistema.

É possível depurar o token, verificar a data de expiração e validar as permissões concedidas no Depurador de Token de Acesso ou usando a API de Validação Programática.

Armazenar um token

O token deve ser armazenado com segurança no seu banco de dados para chamadas de API subsequentes. Mover tokens entre seu cliente e o servidor deve ser feito de forma segura, via HTTPS, para garantir a segurança das contas das pessoas. Leia mais sobre as implicações de mover tokens entre os clientes e seu servidor.

Verifique regularmente a validade do token e, se necessário, solicite permissão ao usuário. Os tokens persistentes também podem se tornar inválidos em alguns casos, incluindo os seguintes:

  • O usuário alterou a senha
  • O usuário revogou as permissões

Como os tokens de acesso do usuário podem ser invalidados ou revogados a qualquer momento por razões diversas, é esperado que o app tenha um fluxo para poder solicitar novamente as permissões do usuário. Quando um usuário iniciar seu app da web, verifique a validade do token utilizado. Se for necessário, guie o usuário pelo fluxo de autenticação para que ele possa obter um token atualizado.

Se não for possível fazer isso no seu app, talvez você precise de um método diferente para solicitar a atualização ao usuário. Isso pode ocorrer em casos em que as chamadas de API não são disparadas diretamente por uma interface do usuário ou são feitas periodicamente por meio da execução de scripts. Para solucionar essa questão, você pode enviar aos usuários um email com instruções.