Facebook Graph API: o que é e como implementar

A Facebook Graph API é a interface HTTP oficial da Meta para ler e gravar dados do Facebook de forma programática, usada para login social, publicação de conteúdo e análise de métricas. Com um app registrado e um token de acesso, qualquer aplicação consulta o grafo social do Facebook em poucas linhas de código.

• O que é a Facebook Graph API?
• Quando usar a Facebook Graph API?
• Como implementar a Facebook Graph API?
• Quais são os limites e a validade dos tokens?
• Como recuperar dados do usuário com JavaScript?

O que é a Facebook Graph API?

A Facebook Graph API é uma API (Interface de Programação de Aplicações) baseada em HTTP que representa os dados do Facebook como um grafo: nós (usuários, páginas, fotos, eventos), arestas (conexões entre nós, como os comentários de um post) e campos (atributos, como o nome de um perfil). Toda leitura e escrita de dados na plataforma passa por ela, no endpoint graph.facebook.com, seguindo o estilo REST sobre HTTPS.

A Graph API dá acesso a informações públicas e privadas — perfis de usuário, postagens, fotos, eventos e métricas — sempre condicionado às permissões que o usuário concede ao seu aplicativo durante o login.

A API é versionada: a versão atual é a v25.0, lançada em 18 de fevereiro de 2026, segundo o changelog oficial da Graph API. O guia de versionamento da Meta garante que cada versão permanece ativa por pelo menos dois anos após o lançamento — a v19.0, por exemplo, lançada no início de 2024, expirou em maio de 2026. Fixar a versão nas suas URLs de requisição evita quebras silenciosas quando a Meta descontinua versões antigas.

Quando usar a Facebook Graph API?

A Facebook Graph API é a escolha certa sempre que seu aplicativo ou site precisa interagir com a plataforma do Facebook — e ela também é a porta de entrada para o restante do ecossistema da Meta, que inclui o Instagram e a rede social Threads. Os casos de uso mais comuns são:

• Autenticação de usuário via Login do Facebook (login social).
• Exibição de conteúdo: postagens, fotos de perfil e eventos dentro do seu app.
• Publicação programática de conteúdo em páginas a partir do seu sistema.
• Análise de métricas de engajamento de páginas e postagens.

Um alerta prático: como a Graph API expõe dados pessoais de usuários brasileiros, o seu app precisa respeitar as regras de tratamento de dados da LGPD, coletando apenas as permissões estritamente necessárias — a própria Meta revisa apps que pedem permissões avançadas antes de liberá-las em produção.

Como implementar a Facebook Graph API?

A implementação da Facebook Graph API segue quatro passos: registrar o aplicativo, configurar o login, obter um token de acesso e fazer as requisições HTTP. Em detalhe:

1. Registre o aplicativo no Meta for Developers. Após o registro, você recebe um App ID e uma chave secreta — as credenciais que identificam seu app em todas as chamadas.
2. Configure o Login do Facebook no painel do app, definindo as URLs de redirecionamento OAuth e as permissões (scopes) que serão solicitadas ao usuário.
3. Obtenha o token de acesso: ao concluir o login, o usuário autoriza seu app e a plataforma devolve um token que representa essa autorização. Todas as requisições em nome do usuário levam esse token.
4. Faça a primeira requisição ao endpoint graph.facebook.com, informando o nó desejado (por exemplo, /me), os campos e o token. Use o Graph API Explorer para testar chamadas no navegador antes de codificar.

O fluxo é o mesmo padrão OAuth de outras plataformas — se você já integrou a Google Maps API em um projeto web, vai reconhecer a estrutura de credenciais, chaves e requisições parametrizadas.

Quais são os limites e a validade dos tokens?

A Facebook Graph API impõe limites de taxa por aplicativo: no nível de acesso padrão, o teto é de 200 chamadas por hora multiplicadas pelo número de usuários ativos diários do app, calculado em janela móvel, conforme a documentação de Rate Limits da Meta. As respostas incluem o cabeçalho X-Business-Use-Case-Usage, que informa o consumo atual — monitore esse valor para não ser bloqueado em horários de pico.

Os tokens de acesso também têm prazo de validade, documentado no guia de Access Tokens:

A conversão de um token curto em um token longo é feita com uma chamada de servidor usando a chave secreta do app. A Meta recomenda não depender desses prazos: eles podem mudar sem aviso, e tokens podem ser invalidados antes do vencimento (troca de senha, revogação de permissão). Trate sempre o erro de token expirado no seu código.

Como recuperar dados do usuário com JavaScript?

Recuperar dados do usuário com a Facebook Graph API em JavaScript exige apenas uma requisição fetch() ao endpoint /me com um token de acesso válido. No exemplo abaixo, uma página HTML simples tem um botão Get User Data e uma div para exibir as informações; ao clicar, a função getUserData() é chamada:

<!DOCTYPE html>
<html lang="pt-br">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Facebook Graph API Example</title>
  </head>
  <body>
    <h1>Facebook Graph API Example</h1>
    <button onclick="getUserData()">Get User Data</button>
    <div id="userData"></div>

    <script>
      // Função para fazer solicitação à API e recuperar informações do usuário
      function getUserData() {
        // Token de acesso obtido após autenticação do usuário
        var accessToken = 'COLOQUE_SEU_TOKEN_DE_ACESSO_AQUI'

        // URL da API para recuperar informações do usuário logado
        var apiUrl = 'https://graph.facebook.com/me?fields=id,name,email&access_token=' + accessToken

        // Fazendo solicitação GET para a API
        fetch(apiUrl)
          .then((response) => response.json())
          .then((data) => {
            // Exibindo as informações do usuário na página
            document.getElementById('userData').innerHTML = `
              <p>ID: ${data.id}</p>
              <p>Nome: ${data.name}</p>
              <p>Email: ${data.email}</p>
            `
          })
          .catch((error) => {
            console.error('Erro ao recuperar dados do usuário:', error)
          })
      }
    </script>
  </body>
</html>

Dentro da função getUserData(), a URL da Graph API pede os campos básicos do usuário (id, name e email) via parâmetro fields. O método fetch() faz a solicitação GET, e a resposta JSON é exibida na página com innerHTML.

Substitua COLOQUE_SEU_TOKEN_DE_ACESSO_AQUI pelo token real obtido no login do Facebook. Em produção, nunca exponha tokens de longa duração ou a chave secreta no front-end — mantenha-os no servidor e repasse ao navegador apenas tokens curtos com o mínimo de permissões.

Conclusão

A Facebook Graph API continua sendo a forma mais confiável de integrar um produto ao maior grafo social do mundo — desde que você jogue pelas regras da Meta: fixe a versão da API, peça só as permissões necessárias, monitore os limites de taxa e trate a expiração de tokens desde o primeiro commit. O custo de ignorar esses detalhes é um app bloqueado na revisão ou quebrado numa depreciação de versão. Comece pequeno no Graph API Explorer, valide o fluxo de login e só então leve as chamadas para o código — aqui no CodeCrush, essa é a ordem que recomendamos para qualquer integração com APIs de terceiros.