Meta Marketing API · accesso programmatico alle campagne

La Meta Marketing API è l’interfaccia ufficiale via cui Meta permette di interagire programmaticamente (via codice) con il proprio sistema pubblicitario. Espone le stesse operazioni che si fanno manualmente su Ads Manager (creare campagne, audience, creative, leggere insights), ma in modo accessibile a script, applicazioni custom, integrazioni MCP/AI.

L’API è un prodotto separato da Ads Manager: ogni grande agenzia, ogni dashboard pubblicitaria di terze parti, ogni Ads Manager alternativa (es. Smartly.io, Madgicx, AdEspresso) appoggia in ultima analisi sulla Marketing API per fare ciò che fa.

Cosa fa l’API

Le operazioni esposte coprono l’intero ciclo di vita di una campagna:

• Account management: leggere account pubblicitari, business manager, permessi, billing.
• Campagne: creare, modificare, mettere in pausa, archiviare campagne, ad set, ad.
• Audience: creare e gestire Custom Audience, Lookalike, uploadare Customer List hashate.
• Creative: caricare immagini, video, generare ad creative, gestire varianti Advantage+ Creative.
• Insights: leggere metriche aggregate per ogni livello (account, campagna, ad set, ad), filtri per data, posizionamento, demografica.
• Eventi: ricevere notifiche di eventi via webhook (es. status change di una campagna, completion learning phase).

Autenticazione

L’API usa OAuth 2.0 + access token. Esistono tre tipi di token:

1. User access token: emesso a nome di un utente Facebook autenticato. Scade tipicamente in 60 giorni. Usato in workflow interattivi (l’utente clicca "autorizza").
2. App access token: emesso a nome di un’app Facebook registrata. Usato per operazioni server-to-server.
3. System User access token: emesso da un System User dentro Business Manager. Non scade (se configurato come permanente). È lo standard di fatto per agenzie e dashboard interne.

Il System User è una figura "robot" dentro Business Manager con permessi su uno o più account pubblicitari. Per ogni progetto serio di automazione si crea un System User dedicato, gli si attribuiscono i permessi minimi necessari (principio di least privilege), si emette un token long-lived.

Rate limit

L’API ha rate limit dinamici basati su:

• App-level rate limit: numero massimo di chiamate per app per ora, dipende dall’access tier.
• Account-level rate limit: numero massimo di chiamate per account pubblicitario per ora.
• User-level rate limit: per token user-based.

I limiti sono calcolati su una sliding window di 1 ora. Se sforati, Meta restituisce status code 17 (User request limit reached) o 80004 (Application request limit reached) e fa back-off. Implementazioni serie includono retry con exponential backoff.

Volume tipico ammesso: 200-1.000 chiamate l’ora per ogni access tier. Account grandi con Standard Access ottengono limiti più elevati su richiesta.

Marketing API vs Graph API

La Graph API è l’API generale di Meta (pagine, post, foto, gruppi, ecc.). La Marketing API è un sotto-insieme specializzato che gestisce pubblicità a pagamento. La distinzione conta a livello di permessi: per accedere alla Marketing API serve uno specifico set di scope (ads_management, ads_read, business_management).

In pratica, una stessa app Facebook può usare entrambe le API: Marketing per gestire campagne, Graph per pubblicare contenuti organici.

Use case tipici

1. Dashboard custom interna

Un’agenzia mid-size con 30 clienti costruisce un dashboard interno che aggrega metriche di tutti i 30 account in un’unica vista. La Marketing API è il backend: pull notturno di insights, aggregazione in DB interno, visualizzazione tramite frontend (es. Metabase, Tableau, custom React app).

Vantaggio rispetto a Ads Manager: vista cross-cliente, KPI custom non disponibili nativamente, alert automatici su soglie.

2. Automation rules

Script che esegue ogni ora: per ogni campagna attiva con CPA > soglia configurata, mette in pausa l’ad set. Per ogni ad con hook rate crollato sotto 15%, manda alert Slack. Per ogni audience con frequency > 8, suggerisce refresh creative.

Vantaggio: monitoraggio 24/7 senza intervento umano per anomalie ricorrenti.

3. Bulk upload campagne

Brand multi-paese (50 mercati) che lancia campagna identica in ogni paese con localizzazione (lingua, valuta, audience, copy). Manualmente sarebbero 50 setup. Via API: configurazione una volta, replica con script per i 50 mercati, deploy in 10 minuti.

4. Integrazione MCP/AI

L’MCP server descritto in MCP Meta Ads usa la Marketing API per esporre le funzioni all’AI. Senza Marketing API non c’è MCP.

Limiti e cautele

1. Versioning: l’API ha versioni semestrali. Le vecchie versioni vengono deprecate dopo 24 mesi circa. Codice che funziona oggi su v18 va aggiornato a v20 entro la deadline.
2. Quotas non sempre prevedibili: in periodi di rush (Black Friday), Meta può applicare quote più strette per stabilità di sistema.
3. Permessi App Review: alcuni scope richiedono review manuale di Meta prima di poter essere usati in produzione (processo di 2-4 settimane).
4. Errori asincroni: certe operazioni (es. creare Lookalike) sono asincrone: l’API restituisce OK ma il risultato è disponibile solo dopo N minuti/ore. L’implementazione deve gestire polling o webhook.

Quando l’API conviene davvero

Per un singolo account piccolo o medio gestito da uno strategist, Ads Manager basta. L’API entra in gioco quando:

• 10+ account in parallelo (aggregazione cross-cliente).
• Pattern ricorrenti automatizzabili (alert, bulk upload, refresh).
• Integrazioni con sistemi esterni (CRM, e-commerce, BI).
• AI conversazionale via MCP (ridurre tempo strategico per query).

Vedi anche: MCP Meta Ads, Ads Manager, Workflow AI 3 fasi.