Expert Digital Base para IAs A escola Lucas Cruz Agenda FAQ Blog Ler no site → Site principal →
Artigo do blog

Como Usar a Graph API do Meta para Automações

Por Lucas Cruz · Publicado em 7 de maio de 2026 · Categoria: Redes Sociais

Como Usar a Graph API do Meta para Automações: Guia Completo 2026

Como Usar a Graph API
do Meta para Automações

A Graph API é a chave que conecta qualquer sistema externo ao ecossistema Meta — Facebook, Instagram e Messenger. Neste guia você vai do conceito básico às chamadas reais de API, com exemplos práticos para publicar posts, buscar leads, acessar insights de anúncios e integrar com n8n e Make.com.

🎯 Resposta direta

A Graph API do Meta é a interface que permite automatizar ações no Facebook e Instagram — publicar posts, buscar leads de formulários, acessar métricas de anúncios, gerenciar comentários e muito mais. A versão atual é a v25.0 (fevereiro de 2026). A URL base é https://graph.facebook.com/v25.0/. Para usar, você precisa de um App ID + Token de acesso. Para automações em produção, o System User Token (não expira, gerado no Business Manager) é o mais indicado.

v25
versão atual da Graph API do Meta, lançada em fevereiro de 2026
200
chamadas por hora por token de usuário — limite padrão da Graph API
50
requisições por batch — máximo permitido em uma única chamada em lote
30d
prazo de expiração dos leads nos formulários sem Webhook — configure a integração
📋 Neste artigo
  1. O que é a Graph API do Meta
  2. Como funciona: nós, arestas e campos
  3. Versão atual e versionamento
  4. Autenticação: tokens e permissões
  5. Explorador da Graph API: seu laboratório
  6. Endpoint 1 — Publicar post em Página
  7. Endpoint 2 — Buscar leads de formulários
  8. Endpoint 3 — Insights de anúncios
  9. Endpoint 4 — Publicar no Instagram
  10. Endpoint 5 — Webhooks em tempo real
  11. Integrar com n8n e Make.com
  12. Limites de taxa e boas práticas
  13. Erros comuns e como resolver
  14. Recursos da Expert Digital
  15. FAQ — perguntas frequentes

O que é a Graph API do Meta

A Graph API é a principal interface de programação (API) do Meta para ler e escrever dados no ecossistema Facebook e Instagram de forma programática. É chamada de "Graph" porque os dados são organizados como um grafo — uma estrutura de nós (pessoas, páginas, posts, anúncios, comentários) conectados por arestas (relacionamentos: a Página tem posts, o post tem comentários).

Em termos práticos: tudo que você faz manualmente no Facebook e no Instagram — publicar, ler comentários, verificar métricas, buscar leads — pode ser feito via Graph API de forma automática, integrada a qualquer sistema externo.


Como funciona: nós, arestas e campos

Toda chamada à Graph API segue a mesma lógica de URL:

Estrutura base de uma chamadaURL Pattern
https://graph.facebook.com/v25.0/{nó}/{aresta}?fields=campo1,campo2&access_token=SEU_TOKEN

# Exemplos:
# Buscar info de uma Página:
GET https://graph.facebook.com/v25.0/me?fields=id,name,fan_count

# Buscar posts da Página:
GET https://graph.facebook.com/v25.0/{page-id}/feed?fields=id,message,created_time

# Publicar um post:
POST https://graph.facebook.com/v25.0/{page-id}/feed
  message="Novo post publicado via API!"
📐 Seleção de campos é obrigatória: a Graph API v25 não retorna campos por padrão — você precisa especificar quais quer com ?fields=campo1,campo2. Requisições sem fields retornam apenas id e name. Selecionar apenas os campos necessários reduz o tamanho da resposta e aumenta a velocidade.

Versão atual e versionamento

A Graph API é versionada — a Meta lança novas versões aproximadamente a cada 6 meses e mantém cada versão disponível por 2 anos. Usar versões antigas é arriscado porque elas são descontinuadas sem aviso.

Versão Status Lançamento Descontinuação
v25.0Atual — use estaFev 2026~Fev 2028
v24.0SuportadaOut 2025~Out 2027
v23.0SuportadaMai 2025~Mai 2027
v20.0Fim set/2026Mai 2024Set 2026
v19.0Fim mai/2026Jan 2024Mai 2026
⚠️ Migre agora se você usa v19 ou v20: a v19 é descontinuada em maio de 2026 e a v20 em setembro de 2026. Substitua todas as chamadas /v19.0/ e /v20.0/ por /v25.0/ nos seus workflows do n8n e Make.com para evitar quebras.

Autenticação: tokens de acesso e permissões

A Graph API usa tokens OAuth 2.0. Para automações em produção, existem 3 tipos principais:

Tipo de Token Validade Como obter Melhor para
User Token (curto) ~1 hora Explorador da Graph API ou OAuth flow Testes rápidos apenas
User Token (longo) 60 dias Endpoint /oauth/access_token Integrações simples
Page Access Token Não expira* Endpoint /{user-id}/accounts Automações de Página
System User Token Não expira Business Manager → Usuários do Sistema Produção — recomendado
App Token Até Secret mudar app-id|app-secret Validação de webhooks

*Page Access Token não expira quando gerado a partir de um User Token de longa duração.

Fluxo completo para obter um Page Token permanente

Passo 1 — Converter token curto em token de 60 diasGET
GET https://graph.facebook.com/v25.0/oauth/access_token?
  grant_type=fb_exchange_token&
  client_id=SEU_APP_ID&
  client_secret=SEU_APP_SECRET&
  fb_exchange_token=TOKEN_CURTO_DO_EXPLORADOR

# Resposta:
{
  "access_token": "EAABs...",  // token de 60 dias
  "token_type": "bearer",
  "expires_in": 5183944       // ~60 dias em segundos
}
Passo 2 — Obter o Page Access Token permanenteGET
GET https://graph.facebook.com/v25.0/me/accounts?
  access_token=TOKEN_60_DIAS

# Resposta (array de Páginas que você administra):
{
  "data": [{
    "id": "123456789",
    "name": "Nome da Sua Página",
    "access_token": "EAACs..."  // Page Token — NÃO expira
  }]
}
🎯 Recomendação para produção: use sempre o System User Token gerado pelo Business Manager em business.facebook.com → Configurações → Usuários do Sistema. Ele nunca expira, não depende de nenhum usuário humano logar e sobrevive mesmo se você sair da empresa.

Explorador da Graph API: seu laboratório

Antes de colocar qualquer chamada em produção, teste no Explorador da Graph API — a ferramenta oficial de testes da Meta:


📢
Publicar Post em uma Página
Automatize publicações de conteúdo no Facebook
pages_manage_posts

Uma das automações mais usadas em marketing digital: publicar posts em Páginas do Facebook via Graph API, integrado ao n8n ou Make.com para agendamento e criação em escala.

POST /{page-id}/feed
Publicar um post de texto simplesPOST
POST https://graph.facebook.com/v25.0/{page-id}/feed

# Body (form-data ou JSON):
{
  "message": "Novo conteúdo publicado via API! 🚀 #marketing #automação",
  "access_token": PAGE_ACCESS_TOKEN
}

# Resposta:
{ "id": "123456789_987654321" }  // ID do post criado
Publicar post com link e imagem de previewPOST
POST https://graph.facebook.com/v25.0/{page-id}/feed

{
  "message": "Veja nosso novo artigo 👇",
  "link":    "https://expertdigitaloficial.com.br/blog/o-que-e-llm",
  "access_token": PAGE_ACCESS_TOKEN
}
# O Facebook faz scraping do Open Graph do link automaticamente
Agendar post para data futuraPOST
POST https://graph.facebook.com/v25.0/{page-id}/feed

{
  "message":       "Post agendado para amanhã às 9h!",
  "scheduled_publish_time": 1748512800,  // timestamp Unix da data
  "published":     false,
  "access_token":  PAGE_ACCESS_TOKEN
}
📋
Buscar Leads de Formulários
Acesse os leads de Lead Ads diretamente via API ou em tempo real com Webhook
leads_retrieval

A Graph API permite acessar todos os leads coletados nos formulários de Lead Ads — sem precisar fazer download manual do CSV no painel. Com Webhook, você recebe cada lead assim que ele preenche o formulário.

GET /{form-id}/leads
Listar todos os leads de um formulárioGET
GET https://graph.facebook.com/v25.0/{form-id}/leads?
  fields=id,created_time,field_data&
  access_token=PAGE_ACCESS_TOKEN

# Resposta:
{
  "data": [{
    "id": "1234567890",
    "created_time": "2026-05-05T14:22:00+0000",
    "field_data": [
      { "name": "full_name",   "values": ["João Silva"] },
      { "name": "email",       "values": ["joao@email.com"] },
      { "name": "phone_number","values": ["11999999999"] }
    ]
  }]
}
Filtrar leads por data (após timestamp)GET
GET https://graph.facebook.com/v25.0/{form-id}/leads?
  fields=id,created_time,field_data&
  filtering=[{"field":"time_created","operator":"GREATER_THAN","value":1748476800}]&
  access_token=PAGE_ACCESS_TOKEN
Prefira Webhook ao polling: em vez de fazer GET periódico nos leads, configure um Webhook para o objeto leadgen no painel do seu app (Meta Developers → Webhooks). Cada novo lead é enviado ao seu endpoint em segundos — sem polling, sem custo de chamadas desnecessárias.
📊
Insights de Anúncios (Marketing API)
Extraia métricas de campanhas, conjuntos e anúncios para relatórios automatizados
ads_read

A Marketing API (parte da Graph API) permite extrair métricas de performance de anúncios programaticamente — sem abrir o Gerenciador de Anúncios. Isso possibilita criar dashboards automáticos no Google Sheets, Looker Studio ou Power BI.

GET /{ad-account-id}/insights
Buscar métricas de todas as campanhas ativas (últimos 7 dias)GET
GET https://graph.facebook.com/v25.0/act_{ad-account-id}/insights?
  fields=campaign_name,impressions,clicks,spend,ctr,cpc,cpm,reach,
         actions,cost_per_action_type&
  date_preset=last_7d&
  level=campaign&
  access_token=SYSTEM_USER_TOKEN

# Nota: ad-account-id começa com "act_" — ex: act_123456789
Breakdown por dia — para séries temporaisGET
GET https://graph.facebook.com/v25.0/act_{ad-account-id}/insights?
  fields=campaign_name,spend,impressions,reach,actions&
  time_range={"since":"2026-04-01","until":"2026-04-30"}&
  time_increment=1&   // 1 = por dia; 7 = por semana
  level=campaign&
  access_token=SYSTEM_USER_TOKEN
⚠️ v25 — métricas de alcance descontinuadas em junho/2026: a partir de junho de 2026, os campos reach e impressions no nível de post e página são descontinuados e substituídos por media_views e media_viewers. Atualize seus workflows que dependem dessas métricas antes do prazo.
📸
Publicar no Instagram via Graph API
Automatize posts, Reels e carrosséis no Instagram Business
instagram_content_publish

A publicação no Instagram via Graph API segue um processo de dois passos: primeiro cria-se um container de mídia (envia a imagem/vídeo), depois publica-se o container. Funciona apenas para contas Business e Creator.

POST /{ig-user-id}/media → depois → POST /{ig-user-id}/media_publish
Passo 1 — Criar container da imagemPOST
POST https://graph.facebook.com/v25.0/{ig-user-id}/media

{
  "image_url":    "https://sua-cdn.com/imagem.jpg",   // URL pública acessível
  "caption":      "Nova publicação via API! 🚀 #marketing",
  "access_token": PAGE_ACCESS_TOKEN
}

# Resposta:
{ "id": "17896129349500001" }  // creation_id para o próximo passo
Passo 2 — Publicar o containerPOST
POST https://graph.facebook.com/v25.0/{ig-user-id}/media_publish

{
  "creation_id":  "17896129349500001",  // ID do Passo 1
  "access_token": PAGE_ACCESS_TOKEN
}

# Resposta:
{ "id": "17841405822304914" }  // ID do post publicado no Instagram
⏱️ Vídeos e Reels exigem aguardar o processamento entre os dois passos. Faça um GET em /{creation-id}?fields=status_code e aguarde o retorno FINISHED antes de chamar /media_publish. Tentar publicar enquanto o vídeo ainda processa retorna erro.
🔔
Webhooks: Receber Eventos em Tempo Real
Sem polling — o Meta notifica você quando algo acontece
Tempo Real

Webhooks invertem o fluxo: em vez de você consultar a API periodicamente (polling), o Meta empurra os dados para o seu sistema assim que algo acontece — um novo lead, um novo comentário, uma mudança na Página. É mais eficiente e mais rápido.

Configurar Webhook no Meta Developers

  • 1 No painel do app, acesse Webhooks no menu lateral
  • 2 Clique em "Adicionar assinatura de produto" e selecione o objeto: page, leadgen, instagram
  • 3 Configure Callback URL — o endpoint do seu sistema (n8n Webhook URL, Make.com URL)
  • 4 Configure o Verify Token — uma string secreta para confirmar que você é o destinatário legítimo
  • 5 Selecione os campos de assinatura: para leads, marque leadgen; para posts, marque feed
  • 6 Clique em Verificar e Salvar — o Meta faz um GET no seu endpoint com hub.challenge para verificar
Payload típico de um Webhook de novo leadINCOMING POST
{
  "object": "page",
  "entry": [{
    "id": "123456789",                // ID da Página
    "time": 1748476800,
    "changes": [{
      "value": {
        "leadgen_id": "987654321",   // ID do lead
        "form_id":    "111222333",   // ID do formulário
        "page_id":    "123456789",
        "adgroup_id": "444555666",
        "ad_id":      "777888999"
      },
      "field": "leadgen"
    }]
  }]
}

Após receber o Webhook, use o leadgen_id para buscar os dados completos do lead via GET na Graph API:

Buscar dados do lead pelo IDGET
GET https://graph.facebook.com/v25.0/{leadgen_id}?
  fields=id,created_time,field_data&
  access_token=PAGE_ACCESS_TOKEN

Integrar com n8n e Make.com

⚙️

n8n — nó Facebook Graph API

Adicione o nó "Facebook Graph API" e configure com suas credenciais. Use Method, URL e Body para montar qualquer chamada. Para leads, use o nó "Facebook Lead Ads Trigger" que configura o Webhook automaticamente.

Nó nativo disponível
🔄

Make.com — módulo Graph API

Use o módulo "Facebook → Make an API Call" para chamadas personalizadas. O Make tem módulos nativos para Facebook Pages e Instagram, reduzindo a necessidade de configurar chamadas manuais na maioria dos casos.

Módulos nativos disponíveis
📨

HTTP Request genérico

Para endpoints não cobertos pelos nós nativos, use o nó "HTTP Request" (n8n) ou o módulo "HTTP → Make a Request" (Make.com) com a URL da Graph API e o token no header ou como parâmetro.

Universal — qualquer endpoint
🧩

Batch Requests — múltiplas chamadas

A Graph API suporta até 50 chamadas em um único request via POST / com array de batch. Isso reduz latência e uso de limites de taxa quando você precisa buscar dados de várias Páginas ou campanhas simultaneamente.

Otimização avançada
n8n — Configuração do nó HTTP Request para publicar postn8n
// Nó: HTTP Request
Method:  POST
URL:     https://graph.facebook.com/v25.0/{{ $json.page_id }}/feed

// Body (JSON):
{
  "message":      "{{ $json.mensagem }}",
  "access_token": "{{ $credentials.pageToken }}"
}

// Credenciais: Header Autenticação
// ou adicione access_token diretamente no Body

Limites de taxa e boas práticas


Erros comuns da Graph API e como resolver

Código Significado Como resolver
Error 190 Token inválido ou expirado Regenere o token. Para produção, use System User Token (não expira)
Error 200 Sem permissão para este endpoint Verifique as permissões do token no Debug Token — adicione o escopo necessário
Error 4 Limite de taxa atingido Aguarde e implemente backoff exponencial. Verifique header X-App-Usage
Error 17 Limite de usuário atingido Mesmo que erro 4 — backoff ou reduza frequência das chamadas
Error 100 Parâmetro inválido Verifique os campos obrigatórios. Consulte a documentação do endpoint específico
Error 10 Permissão de desenvolvedor ausente Para endpoints protegidos fora do modo dev, é necessária a App Review
Error 368 Conta de anúncios desabilitada A conta de anúncios foi suspensa. Contate o suporte do Meta Ads

Perguntas frequentes (FAQ)

O que é a Graph API do Meta?

É a principal interface programática do Meta para ler e escrever dados no ecossistema Facebook e Instagram. Com ela é possível automatizar publicações de posts, buscar leads de formulários, acessar métricas de anúncios, responder comentários e configurar Webhooks de eventos em tempo real. A versão atual é v25.0, lançada em fevereiro de 2026.

Como autenticar na Graph API do Meta?

Use tokens OAuth 2.0. Para automações em produção, o mais indicado é o System User Token — gerado no Business Manager em Configurações → Usuários do Sistema, nunca expira e não depende de nenhum usuário humano. Para Páginas, o Page Access Token gerado a partir de um token de longa duração também não expira. Nunca use o token de usuário de 1 hora em automações.

Qual a versão atual da Graph API do Meta?

A versão atual é a v25.0, lançada em 18 de fevereiro de 2026. A URL base é https://graph.facebook.com/v25.0/. As versões v19 e v20 serão descontinuadas em maio e setembro de 2026 respectivamente. Sempre use a versão mais recente para evitar quebras.

Como usar a Graph API do Meta com n8n?

O n8n tem o nó nativo "Facebook Graph API" — configure as credenciais com seu token de acesso e use Method, URL e Body para montar qualquer chamada. Para leads em tempo real, use o nó "Facebook Lead Ads Trigger" que configura o Webhook automaticamente. Para publicações no Instagram, use o nó "HTTP Request" com os dois passos: criar container e publicar.

Como buscar leads do Facebook Lead Ads via Graph API?

Faça um GET para https://graph.facebook.com/v25.0/{form-id}/leads?fields=id,created_time,field_data&access_token={page-token}. O form-id é encontrado no Gerenciador de Formulários do Facebook. Para receber leads em tempo real sem polling, configure um Webhook para o objeto leadgen no painel do app — o Meta enviará cada novo lead ao seu endpoint em segundos.

Qual o limite de chamadas da Graph API?

O limite padrão é 200 chamadas por hora por token de usuário. Ao atingir o limite, a API retorna erro 4 ou 17. Para minimizar o uso: agrupe em Batch Requests (até 50 por chamada), use Webhooks em vez de polling e monitore o header X-App-Usage na resposta para saber o percentual do limite consumido.

A Graph API: a cola que conecta o Meta ao seu stack

Dominar a Graph API do Meta transforma o que antes era trabalho manual — publicar posts, exportar leads, verificar métricas — em fluxos automatizados que rodam 24h por dia sem intervenção humana.

Comece pequeno: configure o Webhook de leads e conecte ao n8n para disparar WhatsApp automaticamente. Depois automatize publicações de posts. Com o tempo, construa um dashboard de métricas de anúncios que atualiza sozinho. Cada peça que você automatiza é tempo liberado para estratégia.

Gostou do conteúdo? Compartilhe com quem está começando com automações no Meta! 🔗

Ler no siteTodos os artigos