Introducing Graph API v25.0 and Marketing API v25.0

Abaixo, confira os destaques das novas mudanças da GAPI/MAPI para a versão 25. Acesse nosso registro de alterações para ver uma lista completa de mudanças e detalhes.

Atualizações gerais

Graph API: apresentamos a métrica Visualizadores da Página

Até o final de junho de 2026, planejamos introduzir a métrica Visualizadores da Página na Graph API. A métrica de visualizadores pretende substituir a métrica de alcance legada e fornecer uma mensuração consistente entre plataformas (Facebook e Instagram) de quantas pessoas viram um conteúdo. Os desenvolvedores devem começar a planejar a migração para os visualizadores para garantir acesso contínuo aos insights sobre o público.

O que está mudando?

As métricas de visualizadores estarão disponíveis nos insights da Página e nos insights do story

Insights sobre posts/Páginas

• GET {page-id}/insights/page_total_media_view_unique*
• GET {post-id}/insights/post_total_media_view_unique*

Insights de Stories

• Uma nova métrica será adicionada
• GET {stories-id}/insights/metric
  • PAGE_STORY_TOTAL_MEDIA_VIEW_UNIQUE

As Graph APIs acima estarão disponíveis após o lançamento da versão 25. Recomendamos que os desenvolvedores verifiquem o registro de alterações da Graph API para obter as informações mais atualizadas.

Atualização do certificado mTLS para webhooks

A partir de 31 de março de 2026, a Meta começará a assinar certificados mTLS de Webhooks usando uma autoridade certificadora (CA) diferente de propriedade da Meta.

O que isso representa para os desenvolvedores?

Se os seus servidores estiverem configurados para exigir e verificar o certificado mTLS de Webhooks, será preciso definir a nova CA da Meta como confiável. Se você não atualizar o armazenamento confiável dentro do prazo, isso resultará em falhas de handshake do TLS e seus servidores deixarão de receber todos os eventos de webhooks.

Ação necessária: atualize seu armazenamento confiável

Para garantir o recebimento ininterrupto de Webhooks, você deve

1. Baixar o certificado de CA raiz da Meta: acesse Comece a usar webhooks e baixe o arquivo chamado meta-outbound-api-ca-2025-12.pem.
   A CA raiz assinará o certificado de folha que será apresentado nas solicitações de webhooks.
2. Adicionar ao seu armazenamento confiável: adicione esse certificado ao armazenamento confiável de qualquer servidor que receba Webhooks.
3. Manter o certificado atual: você deve adicionar o novo certificado ao armazenamento confiável enquanto o atual ainda estiver ativo.

Importante: não espere até o prazo final. Adicione o novo certificado ao seu armazenamento de confiança imediatamente para garantir uma transição tranquila em 31 de março.

Prazo: antes de 31 de março de 2026.

Por que essa mudança

O certificado mTLS do Webhooks atual é assinado pela CA raiz DigiCert. Como a DigiCert está descontinuando o uso do EKU de autenticação do cliente, o certificado não pode ser renovado com essa CA raiz e expira em 15 de abril de 2025.

Consequentemente, o novo certificado de Webhooks mTLS será assinado por uma autoridade de certificação (CA) raiz interna da Meta. Ele manterá o mesmo nome comum (client.webhooks.fbclientcerts.com) do certificado atual.

A documentação pública sobre o mTLS do Webhooks foi atualizada com uma notificação sobre essa alteração. Os detalhes técnicos completos na documentação serão atualizados permanentemente em abril de 2026, quando a transição for concluída.

Itens que se tornaram obsoletos e alterações disruptivas

Mensagens de erro aprimoradas para a API de Insights sobre Anúncios assíncrona

Estamos sempre trabalhando para melhorar a experiência do desenvolvedor com nossas APIs. Para oferecer maior transparência e permitir que desenvolvedores criem apps mais resilientes, estamos aprimorando os relatórios de erro para o ponto de extremidade GET {AD_REPORT_RUN_ID} da API de Insights sobre Anúncios assíncrona.

A partir da versão 25 da Graph API, que será lançada em 18 de fevereiro de 2026, os desenvolvedores terão acesso a informações de erro detalhadas quando um relatório assíncrono falhar. Isso possibilitará o diagnóstico mais fácil de falhas e melhorará a eficiência das integrações de API. Para os desenvolvedores que têm acesso ao campo error_code no momento, o tipo será alterado de uint para int.

O que está mudando?

Estamos apresentando os novos campos padrão a seguir para a resposta do ponto de extremidade GET {AD_REPORT_RUN_ID} da API de Insights sobre Anúncios assíncrona para todos os apps:

• error_code: o código de erro. Observação: o campo será alterado de uint para int para qualquer desenvolvedor que tenha acesso a ele no momento
• error_message: uma mensagem correspondente ao error_code.
• error_subcode: o subcódigo específico do erro.
• error_user_title: um título simples para o subcódigo de erro.
• error_user_msg: uma mensagem fácil de entender que detalha o subcódigo de erro.

Esses campos serão preenchidos quando houver uma falha na execução de um relatório. Incentivamos você a analisar sua integração da API para garantir a compatibilidade com os novos campos padrão na resposta.

Essa atualização está planejada para ser lançada com a próxima versão da Graph API. Recomendamos que os desenvolvedores confiram o registro de alterações da Graph API para ver as informações mais atualizadas. A documentação para desenvolvedores também foi atualizada para refletir essas mudanças.

Graph API: parâmetro de consulta de metadados descontinuado

Começando com a versão 25 da Graph API, o parâmetro de consulta metadata=1 será descontinuado. Anteriormente, esse parâmetro era usado para retornar metadados sobre campos e conexões de nó em respostas da API. Esse recurso tem pouco uso e será descontinuado para simplificar a plataforma. Após a descontinuação, o parâmetro metadata será ignorado nas solicitações à API.

Os desenvolvedores que atualmente usam metadata=1 devem fazer a transição para usar a nossa documentação oficial da API a fim de descobrir campos e conexões disponíveis para cada tipo de nó.

O que está mudando?

Antes (v24 e anterior):

A adição de ?metadata=1 a uma solicitação da Graph API retornou metadados adicionais sobre o nó, incluindo campos e conexões disponíveis.

Depois (v25+):

O parâmetro metadata=1 será ignorado. As solicitações que incluem esse parâmetro continuarão retornando respostas padrão sem metadados. Não ocorrerão falhas nem alterações disruptivas. Os pedidos não falharão nem serão interrompidos se incluírem metadata=1; o parâmetro simplesmente não terá efeito.

Graph API: descontinuação de métricas de impressões/alcance da Página

Em junho de 2026, planejamos descontinuar as métricas de Alcance do post/Página, Impressões do vídeo e Impressões do story na Graph API. Essas métricas legadas não são mais exibidas nas nossas ferramentas de Insights, mas permaneceram disponíveis via APIs até o momento.

Para alinhar nossos produtos e APIs em uma única estrutura de métricas consistente e para aumentar a confiabilidade geral do sistema, estamos descontinuando essas métricas legadas. Após a descontinuação, os desenvolvedores devem migrar para as novas métricas Media Views e Media Viewers, que substituem os conceitos legados de impressão, alcance e visualizadores do vídeo.

O que está mudando?

As métricas a seguir serão descontinuadas em junho de 2026 para todas as versões da API. Recomendamos que os desenvolvedores consultem o registro de alterações da Graph API para ver as informações mais atualizadas:

Alcance do post/Página

• GET {page-id}/insights/page_impressions_unique*
• GET {page-id}/insights/page_impressions_paid_unique*
• GET {page-id}/insights/page_impressions_viral_unique*
• GET {page-id}/insights/page_impressions_nonviral_unique*
• GET {page-id}/insights/page_posts_impressions*
• GET {page-id}/insights/page_posts_impressions_unique*
• GET {page-id}/insights/page_posts_impressions_paid*
• GET {page-id}/insights/page_posts_impressions_paid_unique*
• GET {page-id}/insights/page_posts_impressions_organic_unique*
• GET {page-id}/insights/page_posts_served_impressions_organic_unique*
• GET {page-id}/insights/page_posts_impressions_viral*
• GET {page-id}/insights/page_posts_impressions_viral_unique*
• GET {page-id}/insights/page_posts_impressions_nonviral*
• GET {page-id}/insights/page_posts_impressions_nonviral_unique*
• GET {post-id}/insights/post_impressions_unique*
• GET {post-id}/insights/post_impressions_paid_unique*
• GET {post-id}/insights/post_impressions_fan_unique*
• GET {post-id}/insights/post_impressions_organic_unique*
• GET {post-id}/insights/post_impressions_viral_unique*
• GET {post-id}/insights/post_impressions_nonviral_unique*
• GET {post-id}/insights/post_impressions_nonviral_unique*

Impressões do vídeo

• GET {video-id}/video_insights/post_impressions_unique
• GET {video-id}/video_insights/total_video_impressions
• GET {video-id}/video_insights/total_video_impressions_unique
• GET {video-id}/video_insights/total_video_impressions_paid_unique
• GET {video-id}/video_insights/total_video_impressions_paid
• GET {video-id}/video_insights/total_video_impressions_organic_unique
• GET {video-id}/video_insights/total_video_impressions_organic
• GET {video-id}/video_insights/total_video_impressions_viral_unique
• GET {video-id}/video_insights/total_video_impressions_viral
• GET {video-id}/video_insights/total_video_impressions_fan_unique
• GET {video-id}/video_insights/total_video_impressions_fan
• GET {video-id}/video_insights/total_video_impressions_fan_paid_unique
• GET {video-id}/video_insights/total_video_impressions_fan_paid

Impressões do story

• Duas métricas serão substituídas
• GET {stories-id}/insights/metric
  • PAGE_STORY_IMPRESSIONS_BY_STORY_ID
  • PAGE_STORY_IMPRESSIONS_BY_STORY_ID_UNIQUE

Recomendamos usar as seguintes métricas:

• GET {page-id}/insights/page_total_media_view_unique
• GET {post-id}/insights/post_total_media_view_unique

Especificamente para detalhamentos entre alcance pago e orgânico, recomendamos usar as métricas a seguir, que fornecem insights substancialmente semelhantes:

• GET {page-id}/insights/page_media_view
• GET {post-id}/insights/post_media_view

Graph API: descontinuação de métricas de visualizadores de 3 segundos

Em junho de 2026, planejamos descontinuar as métricas de visualizadores de 3 segundos. Essas métricas legadas não são mais exibidas nas nossas ferramentas de insights, mas permaneceram disponíveis via Graph API até o momento.

Para alinhar nossos produtos e APIs em uma única estrutura de métricas consistente e para aumentar a confiabilidade geral do sistema, estamos descontinuando essas métricas legadas. Após a descontinuação, os desenvolvedores devem migrar para as novas métricas Media Views e Media Viewers, que substituem os conceitos legados de impressão, alcance e visualizadores do vídeo.

O que está mudando?

As métricas a seguir serão descontinuadas em junho de 2026 para todas as versões da API. Recomendamos que os desenvolvedores consultem o registro de alterações da Graph API para ver as informações mais atualizadas:

• GET {page-id}/insights/page_video_views_unique
• GET {post-id}/insights/post_video_views_organic_unique
• GET {post-id}/insights/post_video_views_paid_unique
• GET {post-id}/insights/post_video_views_unique
• GET {video-id}/video_insights/total_video_views_organic_unique
• GET {video-id}/video_insights/total_video_views_paid_unique
• GET {video-id}/video_insights/total_video_views_unique

Recomendamos usar as seguintes métricas:

• GET {page-id}/insights/page_total_media_view_unique
• GET {post-id}/insights/post_total_media_view_unique

Especificamente para detalhamentos entre visualizadores de 3 segundos pagos e orgânicos, recomendamos usar as métricas a seguir, que fornecem insights substancialmente semelhantes:

• GET {page-id}/insights/page_media_view
• GET {post-id}/insights/post_media_view

API de Marketing: descontinuação de ASC e AAC

A unificação de automação direciona campanhas de app, vendas e leads para a configuração padrão ideal e com automação do Advantage+. Além disso, permite que anunciantes e parceiros tenham acesso simplificado aos produtos de automação mais recentes e de melhor desempenho da Meta. Estamos executando uma descontinuação gradual das APIs legadas e uma migração para a nova configuração de unificação de automação, Advantage+ para desenvolvedores da API de Marketing.

A partir da versão 25 (18 de fevereiro de 2026), as campanhas de ASC e AAC não poderão mais ser criadas ou atualizadas usando a API de Marketing. Isso se estenderá a todas as versões da API de Marketing após 90 dias (até 19 de maio de 2026).

Na versão 26 (estimada para setembro de 2026), todas as campanhas de ASC e AAC serão pausadas.

As campanhas de ASC ou AAC que usam os limites de orçamento para clientes existentes (ECBC) permanecerão editáveis até a versão 26. Esse recurso não está disponível para as campanhas Advantage+. Os desenvolvedores com uma campanha de ECBC devem realizar ações usando um dos métodos abaixo para replicar campanhas de ECBC antes da versão 26:

• Duplicação manual: abra uma campanha de ASC/AAC existente com ECBC no Gerenciador de Anúncios e escolha "Duplicar a campanha". Essa etapa de um clique criará uma nova campanha que replica a configuração da campanha existente.
• Replique as campanhas de ECBC usando a API, use a orientação fornecida na documentação do desenvolvedor para replicar as campanhas usando a API, neste link.
• Solicite a migração em massa no nível da conta de anúncios, para parceiros gerenciados, podemos fornecer uma ação única para replicar todas as campanhas de ECBC em uma data acordada. Entre em contato com seu ponto de contato da Meta e forneça as identificações de conta e a data preferida para a migração.

Observação: todas as duplicações de campanha de ECBC resultarão em uma nova identificação da campanha.

Essa alteração afeta os pontos de extremidade a seguir:

• POST /{campaign-id}
• POST /{campaign-id}/copies

Leia a documentação para desenvolvedores e as perguntas frequentes atualizadas para ver todos os detalhes dessa mudança.

Link da documentação para desenvolvedores

• Documentação para desenvolvedores - Experiência de campanha Advantage+ para vendas, apps e leads

Link do artigo de ajuda sobre o recurso

• Central de Ajuda - Campanhas Advantage+
• Central de Ajuda - Categorias de anúncio especial

Descontinuações de versões de API:

Observe a programação para as próximas descontinuações de versões da Graph API e da API de Marketing:

Graph API

• 21 de maio de 2026: a versão 19 da Graph API será descontinuada e removida da plataforma.
• 24 de setembro de 2026: a versão 20 da Graph API será descontinuada e removida da plataforma.

Para evitar inconvenientes à empresa, recomendamos que você migre todas as chamadas para a versão mais recente da API lançada hoje.