Presentazione dell'API Graph v22.0 e dell'API Marketing v22.0

Di seguito trovi le modifiche più importanti al GAPI/MAPI per la versione 25. Visita il nostro registro modifiche per un elenco completo delle modifiche e dei dettagli.

Aggiornamenti generali

API Graph: presentazione della metrica sugli account che hanno visualizzato la Pagina

Entro la fine di giugno 2026, intendiamo introdurre la metrica sugli account che hanno visualizzato la Pagina nell'API Graph. La metrica relativa agli account che hanno visualizzato ha lo scopo di sostituire la metrica sulla copertura e di fornire una misurazione coerente su più piattaforme (Facebook e Instagram) del numero di persone che hanno visto un certo contenuto. Gli sviluppatori devono iniziare a pianificare la migrazione degli account che hanno visualizzato per continuare ad avere accesso agli insight sul pubblico.

Cosa cambierà?

Le metriche relative agli account che hanno visualizzato saranno disponibili negli insight della Pagina e delle Storie

Insight di post/Pagina

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

Insight delle Storie

• Verrà aggiunta una nuova metrica
• GET {stories-id}/insights/metric
  • PAGE_STORY_TOTAL_MEDIA_VIEW_UNIQUE

Le API Graph elencate sopra saranno disponibili dopo il lancio della v25. Consigliamo agli sviluppatori di controllare il registro modifiche dell'API Graph per le informazioni più aggiornate.

Aggiornamento del certificato mTLS dei webhook

A partire dal 31 marzo 2026, Meta inizierà a firmare i certificati mTLS dei webhook tramite un'autorità di certificazione (CA) diversa, di proprietà di Meta.

Cosa significa questo per gli sviluppatori?

Se i tuoi server sono configurati per richiedere e verificare un certificato mTLS dei webhook, dovrai basarti sul nuovo certificato CA di Meta. Il mancato aggiornamento dell'archivio dei certificati attendibili entro la scadenza comporterà errori di strette di mano TLS; inoltre, i tuoi server smetteranno di ricevere tutti gli eventi dei webhook.

Azione richiesta: aggiorna il tuo archivio dei certificati attendibili

Per garantire una ricezione ininterrotta dei webhook, devi

1. scaricare il certificato CA radice di Meta: vai a Primi passi con i webhook e scarica il file denominato meta-outbound-api-ca-2025-12.pem.
   Il CA radice firmerà il certificato foglia che sarà presentato nelle richieste dei webhook;
2. aggiungerlo al tuo archivio dei certificati attendibili: aggiungi questo certificato all'archivio dei certificati attendibili di tutti i server che ricevono webhook;
3. mantenere il certificato attuale: devi aggiungere il nuovo certificato al tuo archivio dei certificati attendibili mentre quello attuale è ancora valido.

Importante: non aspettare la scadenza. Dovresti aggiungere immediatamente il nuovo certificato al tuo archivio di certificati attendibili per garantire una transizione fluida il 31 marzo.

Scadenza: prima del 31 marzo 2026.

Perché questa modifica

L'attuale certificato mTLS dei webhook è firmato dall'autorità radice DigiCert. Poiché DigiCert sta eliminando l'uso dell'EKU di autenticazione del client, il certificato non può essere rinnovato con questo CA radice in scadenza il 15 aprile 2025.

Di conseguenza, il nuovo certificato Webhooks mTLS sarà firmato da un'autorità di certificazione (CA) interna a Meta. Manterrà lo stesso nome comune (client.webhooks.fbclientcerts.com) del certificato attuale.

La documentazione pubblica su mTLS dei webhook è stata aggiornata con una notifica relativa a questa modifica. I dettagli tecnici completi riportati nella documentazione saranno aggiornati in modo permanente ad aprile 2026, una volta completata la transizione.

Obsolescenze e modifiche sostanziali

Messaggi di errore migliorati per l'API Ads Insights Async

Lavoriamo costantemente per migliorare l'esperienza degli sviluppatori con le nostre API. Per offrire maggiore trasparenza e consentire agli sviluppatori di creare applicazioni più resilienti, stiamo migliorando la segnalazione degli errori per l'endpoint GET {AD_REPORT_RUN_ID} dell'API Ads Insights Async.

A partire dalla versione 25.0 dell'API Graph, che sarà rilasciata il 18 febbraio 2026, gli sviluppatori avranno accesso a informazioni dettagliate sull'errore quando un report asincrono non va a buon fine. In questo modo, sarà possibile identificare più facilmente i problemi e migliorare l'efficienza delle integrazioni API. Per gli sviluppatori che al momento hanno accesso al campo error_code, il tipo cambierà da uint a int.

Cosa cambierà?

Stiamo introducendo i seguenti nuovi campi predefiniti nella risposta dell'endpoint GET {AD_REPORT_RUN_ID} dell'API Ads Insights Async per tutte le applicazioni:

• error_code: il codice di errore. Nota: il campo sarà modificato da uint a int per gli sviluppatori che vi hanno attualmente accesso
• error_message: un messaggio corrispondente al error_code.
• error_subcode: il sottocodice specifico per l'errore.
• error_user_title: un titolo leggibile per il sottocodice di errore.
• error_user_msg: un messaggio in linguaggio naturale che indica il sottocodice di errore.

Questi campi vengono popolati quando non va a buon fine l'esecuzione di un report. Ti invitiamo a controllare l'integrazione della tua API per garantire la compatibilità con i nuovi campi predefiniti nella risposta.

Questo aggiornamento è programmato per essere rilasciato con la prossima versione dell'API Graph. Consigliamo agli sviluppatori di controllare il registro modifiche dell'API Graph per le informazioni più aggiornate. La documentazione per gli sviluppatori è stata aggiornata per riflettere queste modifiche.

API Graph: parametro della query di metadati obsoleto

A partire dall'API Graph v25, il parametro della query metadata=1 sarà reso obsoleto. Questo parametro è stato utilizzato in precedenza per restituire metadati relativi ai campi e alle connessioni di un nodo all'interno delle risposte API. Questa funzione ha un uso limitato ed è in fase di eliminazione per semplificare la piattaforma. Dopo il termine, il parametro metadata verrà ignorato nelle richieste all'API.

Gli sviluppatori che attualmente usano metadata=1 dovrebbero passare a usare la nostra documentazione API ufficiale per scoprire i campi e le connessioni disponibili per ogni tipo di nodo.

Cosa cambierà?

Prima (versione 24 e precedenti):

L'aggiunta di ?metadata=1 a una richiesta API Graph restituiva metadati aggiuntivi sul nodo, compresi i campi e i collegamenti disponibili.

Dopo (versione 25 e successive):

Il parametro metadata=1 verrà ignorato. Le richieste che includono questo parametro continueranno a restituire le risposte standard senza metadati. Non ci saranno errori o interruzioni: le richieste non genereranno errori o interruzioni se includono metadata=1; il parametro semplicemente non avrà effetto.

API Graph: obsolescenza delle metriche relative a copertura/impression della Pagina

A giugno 2026, intendiamo rimuovere le metriche Copertura del post/della Pagina, Impression dei video e Impression delle Storie dall'API Graph. Queste metriche obsolete non vengono più visualizzate nei nostri strumenti per gli insight, ma sono rimaste comunque disponibili attraverso le API fino ad ora.

Per allineare i nostri prodotti e le API a un framework di metriche unico e coerente e per migliorare l'affidabilità complessiva del sistema, abbiamo deciso di eliminare queste metriche obsolete. Dopo il termine, gli sviluppatori dovranno eseguire la migrazione alle nuove metriche Visualizzazioni di contenuti multimediali e Persone che hanno visualizzato i contenuti multimediali, che sostituiscono i concetti obsoleti di impression, copertura e visualizzazione del video.

Cosa cambia:

Le metriche seguenti saranno dichiarate obsolete a giugno 2026 per tutte le versioni API. Consigliamo agli sviluppatori di controllare il registro modifiche dell'API Graph per le informazioni più aggiornate.

Copertura del post/della Pagina

• 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*

Impression dei video

• 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

Impression delle Storie

• Due metriche saranno sostituite
• GET {stories-id}/insights/metric
  • PAGE_STORY_IMPRESSIONS_BY_STORY_ID
  • PAGE_STORY_IMPRESSIONS_BY_STORY_ID_UNIQUE

Consigliamo invece l'uso delle seguenti metriche:

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

Per quanto riguarda specificamente i dettagli sulla copertura organica e a pagamento, consigliamo di usare le metriche seguenti, che forniscono informazioni sostanzialmente simili:

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

API Graph: obsolescenza delle metriche degli account che hanno visualizzato per 3 secondi

A giugno 2026, intendiamo eliminare le metriche relative agli account che hanno visualizzato per 3 secondi. Queste metriche obsolete non vengono più visualizzate nei nostri strumenti per gli insight, ma sono rimaste comunque disponibili attraverso le API Graph fino ad ora.

Per allineare i nostri prodotti e le API a un framework di metriche unico e coerente e per migliorare l'affidabilità complessiva del sistema, abbiamo deciso di eliminare queste metriche obsolete. Dopo il termine, gli sviluppatori dovranno eseguire la migrazione alle nuove metriche Visualizzazioni di contenuti multimediali e Persone che hanno visualizzato i contenuti multimediali, che sostituiscono i concetti obsoleti di impression, copertura e visualizzazione del video.

Cosa cambia:

Le metriche seguenti saranno dichiarate obsolete a giugno 2026 per tutte le versioni API. Consigliamo agli sviluppatori di controllare il registro modifiche dell'API Graph per le informazioni più aggiornate.

• 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

Consigliamo invece l'uso delle seguenti metriche:

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

Per quanto riguarda specificamente i dettagli sulle persone che hanno visualizzato per 3 secondi in modo organico e a pagamento, consigliamo di utilizzare le seguenti metriche, che forniscono informazioni sostanzialmente simili:

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

API Marketing: obsolescenza di ASC e AAC

L'unificazione dell'automazione porta le campagne per le app, le vendite e l'acquisizione di contatti a usare per impostazione predefinita la configurazione Advantage+ ottimale e basata sull'automazione e permette agli inserzionisti e ai partner di accedere più facilmente ai prodotti di automazione più recenti e più efficaci di Meta. Stiamo procedendo alla terminazione graduale delle API legacy e alla migrazione verso la nuova configurazione Unificazione dell'automazione, Advantage+ per gli sviluppatori di API Marketing.

Dalla versione 25.0 (18 febbraio 2026) non potranno più essere create o aggiornate campagne ASC e AAC usando l'API Marketing. Questo avviso si estenderà a tutte le versioni dell'API Marketing dopo 90 giorni (entro il 19 maggio 2026).

Nella versione 26.0 (data stimata settembre 2026) tutte le campagne ASC e AAC rimanenti saranno messe in pausa.

Le campagne ASC o ACC che usano i limiti di budget per i clienti esistenti (ECBC) continueranno a essere modificabili fino alla v26.0. Questa funzione non è disponibile con le campagne Advantage+. Gli sviluppatori con una campagna ECBC dovrebbero eseguire le azioni usando uno dei metodi indicati di seguito per replicare le campagne ECBC prima della v26.0:

• Duplicazione manuale: apri una campagna ASC/AAC esistente con ECBC in Gestione inserzioni. Ti sarà proposto di "duplicare la campagna". Questo passaggio con 1 clic crea una nuova campagna che replica la configurazione di quella esistente.
• Replica delle campagne ECBC usando l'API: segui le indicazioni fornite nella documentazione per gli sviluppatori per replicare le campagne usando l'API, qui.
• Richiesta di migrazione in gruppo a livello di account pubblicitario: per i partner gestiti siamo in grado di eseguire un'azione una tantum per replicare tutte le campagne ECBC in una data concordata. Contatta il tuo referente di Meta e fornisci gli ID degli account e la data preferita per la migrazione.

Nota: tutte le duplicazioni della campagna ECBC genereranno un nuovo ID della campagna.

Questa modifica riguarda i seguenti endpoint:

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

Consulta la documentazione e le FAQ per gli sviluppatori aggiornate per scoprire tutti i dettagli di questa modifica.

Link alla documentazione per gli sviluppatori

• Documentazione per gli sviluppatori - Esperienza con le campagne Advantage+ vendite, app e contatti

Link all'articolo del centro assistenza sulla funzione

• Centro assistenza - Campagne Advantage+
• Centro assistenza - Categorie speciali di inserzioni

Obsolescenze delle versioni dell'API:

Nell'ambito del programma di gestione delle versioni per l'API Graph e l'API Marketing, tieni conto delle obsolescenze programmate:

API Graph

• 21 maggio 2026: l'API Graph v19 verrà dichiarata obsoleta e rimossa dalla piattaforma.
• 24 settembre 2026: l'API Graph v20 verrà dichiarata obsoleta e rimossa dalla piattaforma.

Per evitare disservizi, consigliamo di effettuare la migrazione di tutte le chiamate all'ultima versione dell'API lanciata oggi.